HowTo.md

HOWTO.md: How to use main.rmd

--- Andy Clifton

To run main.rmd, follow the instructions below for your platform and preferred interface.

Feedback or information on different ways to run main.rmd is always welcome. Please submit this as an issue to https://github.com/AndyClifton/LiterateDemo/issues.

Prerequisites

You will need:

• A working R installation. This can be obtained from http://www.r-project.org. You may find RStudio to be a good IDE.
• A working LaTeX installation. This can be obtained from https://www.latex-project.org/get/.
• Pandoc. rmarkdown calls Pandoc. I suggest you start with the instructions for installing pandoc.

Set up your directory structure

Create a directory somewhere for your project (let's call this $ROOT). Clone the GitHub repository or download the .zip from https://github.com/AndyClifton/LiterateDemo/ into that directory .

In $ROOT you should now have:

• A code/ directory with some .R files.
• A data/ directory with a couple of short .csv data files.

Update main.rmd

1. Open main.rmd in an editor.
2. Change project.root to be $ROOT, e.g. base.dir <- file.path('/user/ahab/files/stuff/test/').
3. Change made.by to whoever's name you want to appear on the figures.

Render the output files

Rendering is the process of running the markdown file, which runs the analysis and generates the documentation at the same time.

We use rmarkdown::render() to generate the outputs ¹. At the R command line, try the following:

1. rmarkdown::render("path/to/file.Rmd") will use the first defined format.

2. You can also use rmarkdown::render("path/to/file.Rmd", output_format = "all") to use all formats given in the file, or

3. Use rmarkdown::render("path/to/file.Rmd", output_format = c("bookdown::pdf_document2", "bookdown::html_document2")) to specify a list of output formats.

See ?rmarkdown::render for the full details."

-- Ralf Stubner

These commands are all included in the make_main.r file, together with several housekeeping steps.

¹ Many thanks to Ralf Stubner for providing this information in an answer through stackoverflow.com. ↩

How to run make_main.r in R

You need to run make_main.r in R. This script will render main.rmd, which means that it runs the analysis and generates the documentation.

• On mac or Linux/Unix systems with R and LaTeX installed, run the shell script make_main.sh from the terminal. It should build all of the output files.

Integration with Git

You might like to try to integrate the above workflow with a Git system.

Commit the results back to Git

Once we have rendered the file, we could commit it back to our git. There are lots of ways to do this, and lots of pointers on how to write a good commit message.

• On mac or Linux/unix systems run git commit -m "My head line" -m "My content line.". I have included this in the comments in the shell script make_main.sh, but not implemented it - it seemed a bit cheeky to write stuff to your git...

END OF FILE