r_markdown.Rmd

# RMarkdown

After you've written source code and maybe a package, an RMarkdown document is a good way to demonstrate how to use your code and results. R Markdown is an authoring framework for R code and output. R Markdown is part word-processor, part R output. It enables you to generate nice reports with R code, figures, tables, and text. It’s handy because it produces neat summaries of your work in HTML or PDF or other formats (Word docs). 

R Markdown is especially helpful with collaborative research and coursework, and is often used in supplemental materials with publications. If you haven’t already watched the R Markdown tutorial, you may want to refer to it when putting together an analysis write-up: http://rmarkdown.rstudio.com/lesson-1.html (including “How it Works”, “Code Chunks”, and “Markdown Basics”). I recommend using “KnitR” when you want to publish (i.e., click on “knit to HTML”, “knit to PDF”, etc. in the pull-down menu in RStudio).

When you click the Knit button in R Studio (looks like a knitting needle with ball of yarn) a document will be generated that includes both content as well as the output of any embedded R code chunks within the document.

  * Book on RMarkdown by the author: https://bookdown.org/yihui/rmarkdown/
  * Tutorial from Rstudio : https://rmarkdown.rstudio.com/articles_intro.html
  * Hadley Wickahm's chapter on Rmarkdown: https://r4ds.had.co.nz/r-markdown.html
  * introduction from U of M https://m-clark.github.io/Introduction-to-Rmarkdown/, 
  * I like this intro because the author was a grad student: https://rpubs.com/brandonkopp/RMarkdown
  * Communicating with R Markdown: A full-day workshop for  users who want to get more out of R Markdown (and friends): https://ysc-rmarkdown.netlify.app/

## Examples of RMarkdown: 

All of the tutorials form https://ourcodingclub.github.io/tutorials.html  are written in RMarkdown.  You can view these tutorials in the github repository for their website, e.g https://github.com/ourcodingclub/ourcodingclub.github.io/tree/master/_tutorials  If you open any one of these .md files in github and click 'raw' you see the markdown code. 

Note that Rstudio is not required to use RMarkdown but it's the entry point for most.   Rstudio has extended Rmarkdown to make it interactive for reporting (e.g. with Shiny, another topic entirely)

## R Notebooks

This is an Rstudio feature that builds up on RMarkdown and is a way to interactively create an RMarkdown file much like the Rconsole.  It's patterned after Jupyter Notebooks used for Python.   It's not required to write RMarkdown.  

Rstudio also has a feature where you can run chunks of code one by one before knitting, similar to the experience of Python notebooks. 

## RMarkdown, Knittr and File paths

Sometimes your markdown file or your code depends on files beiung in particular paths (e.g. data files).   When you source a script from the console, the working directory is what ever you've swet it to, or the top directory of your Rstudio project if you haven't.    This is also true when you run chunks in an Rmarkdown file as descrihbed above. 

However, when you 'knit' an Rmd file, the working directory is set (setwd() ) to the directory in which the markdown file sits.  This is different, and your markdown file may not be able to find files when using knittr than when you ran ti before. 

Knitr, by default, looks in the same directory as your .Rmd file to find any files you need to draw in, like data sets or script files. If you keep your data files and scripts in separate folders (and you should) you need to configure knitr.

You cannot use setwd() with knitr (or several other file-related operations like file.exists() ).  

One way to do this is to include uin  the 'setup'  code chunk, which is usually at the top of RMD file (Rstudio puts a chunk in when you create a new Rmd file: 

```
 ` ` ` {r setup, include=FALSE, echo=FALSE}
 require("knitr")
 knitr::opts_chunk$set(echo = TRUE)
 opts_knit$set(root.dir = "~/path/to/folder/")
 ` ` `
```

(taken from [blog post by Phil Mike Jones](https://philmikejones.me/tutorials/2015-05-20-set-root-directory-knitr/) )

This approach is not reproducible as it is a folder on your computer (not anyone else's).    Also the tilde "~" is shortcut for a users's homedirctory on Linux or Mac but not Windows.    One optionsis to place the root folder of your entire Rstudio project as an 'option' or environment variable that is set,   e.g. 

```
 ` ` `{ r setup, include=FALSE, echo=FALSE}
 require("knitr")
 knitr::opts_chunk$set(echo = TRUE)
 opts_knit$set(root.dir = file.path(options("projfolder")))
 ` ` `
```

There is a package to help this : "ezknitr - Avoid the typical working directory pain when using 'knitr'"

https://cran.r-project.org/web/packages/ezknitr/README.html

Another option is to use an .Renviron file and set a value there. 

More ideas here: https://stackoverflow.com/questions/33107908/how-to-tell-if-code-is-executed-within-a-knitr-rmarkdown-context

Some are Rstudio specific which would mean we'd have to dictate Rstudio usage