Rmarkdown
Markdown language
According to wikipedia:
Markdown is a lightweight markup language, originally created by John Gruber with substantial contributions from Aaron Swartz, allowing people “to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)”.
- Markup is a general term for content formatting - such as HTML - but markdown is a library that generates HTML markup.
- Nice summary from stackoverflow.com and more complete list from github.
- An example https://gist.github.com/jeromyanglim/2716336
- Convert mediawiki to markdown using online conversion tool from pandoc.
- R markdown file and use it in RStudio. Customizing Chunk Options can be found in knitr page and rpubs.com.
Github markdown Readme.md
- https://help.github.com/en/categories/writing-on-github
- https://guides.github.com/features/mastering-markdown/
- https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
- Online editor with preview https://jbt.github.io/markdown-editor/
- An example from pathwayHeatmap
Rmarkdown
- http://rmarkdown.rstudio.com/html_document_format.html
- R Markdown: Eight ways
- https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf
- https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf
- https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf
- Chunk options http://kbroman.org/knitr_knutshell/pages/Rmarkdown.html
HTML5 slides examples
- http://yihui.name/slides/knitr-slides.html
- http://yihui.name/slides/2012-knitr-RStudio.html
- http://yihui.name/slides/2011-r-dev-lessons.html#slide1
- http://inundata.org/R_talks/BARUG/#intro
Software requirement
- Rstudio
- knitr, XML, RCurl (See omegahat or this internal link for installation on Ubuntu)
- pandoc package This is a command line tool. I am testing it on Windows 7.
Slide #22 gives an instruction to create
- regular html file by using RStudio -> Knit HTML button
- HTML5 slides by using pandoc from command line.
Files:
- Rcmd source: 009-slides.Rmd Note that IE 8 was not supported by github. For IE 9, be sure to turn off "Compatibility View".
- markdown output: 009-slides.md
- HTML output: 009-slides.html
We can create Rcmd source in Rstudio by File -> New -> R Markdown.
There are 4 ways to produce slides with pandoc
- S5
- DZSlides
- Slidy
- Slideous
Use the markdown file (md) and convert it with pandoc
pandoc -s -S -i -t dzslides --mathjax html5_slides.md -o html5_slides.html
If we are comfortable with HTML and CSS code, open the html file (generated by pandoc) and modify the CSS style at will.
Built-in examples from rmarkdown
# This is done on my ODroid xu4 running Ubuntu Mate 15.10 (Wily) # I used sudo apt-get install pandoc in shell # and install.packages("rmarkdown") in R 3.2.3 library(rmarkdown) rmarkdown::render("~/R/armv7l-unknown-linux-gnueabihf-library/3.2/rmarkdown/rmarkdown/templates/html_vignette/skeleton/skeleton.Rmd") # the output <skeleton.html> is located under the same dir as <skeleton.Rmd>
Note that the image files in the html are embedded Base64 images in the html file. See
- http://stackoverflow.com/questions/1207190/embedding-base64-images
- Data URI scheme
- http://www.r-bloggers.com/embed-images-in-rd-documents/
- How to not embed Base64 images in RMarkdown
- Upload plots as PNG file to your wordpress
Templates
- https://github.com/rstudio/rticles/tree/master/inst/rmarkdown/templates
- https://github.com/rstudio/rticles/blob/master/inst/rmarkdown/templates/jss_article/resources/template.tex
Knit button
- It calls rmarkdown::render()
- R Markdown = knitr + Pandoc
- rmarkdown::render () = knitr::knit() + a system() call to pandoc
Pandoc's Markdown
Originally Pandoc is for html.
Extensions
- YAML metadata
- Latex Math
- syntax highlight
- embed raw HTML/Latex (raw HTML only works for HTML output and raw Latex only for Latex/pdf output)
- tables
- footnotes
- citations
Types of output documents
- Latex/pdf, HTML, Word
- beamer, ioslides, Slidy, reval.js
- Ebooks
- ...
Some examples:
pandoc test.md -o test.html pandoc test.md -s --mathjax -o test.html pandoc test.md -o test.docx pandoc test.md -o test.pdf pandoc test.md --latex-engine=xlelatex -o test.pdf pandoc test.md -o test.epb
Check out ?rmarkdown::pandoc_convert()/
When you click the Knit button in RStudio, you will see the actual command that is executed.
Global options
Suppose I want to create a simple markdown only documentation without worrying about executing code, instead of adding eval = FALSE to each code chunks, I can insert the following between YAML header and the content. Even bash chunks will not be executed.
```{r setup, include=FALSE} knitr::opts_chunk$set(echo = TRUE, eval = FALSE) ```
Examples/gallery
Some examples of creating papers (with references) based on knitr can be found on the Papers and reports section of the knitr website.
- https://rmarkdown.rstudio.com/gallery.html
- https://github.com/EBI-predocs/knitr-example
- https://github.com/timchurches/meta-analyses
- http://www.gastonsanchez.com/depot/knitr-slides
Read the docs Sphinx theme and journal article formats
http://blog.rstudio.org/2016/03/21/r-markdown-custom-formats/
- rticles package
- rmdformats package
rmarkdown news
Useful tricks when including images in Rmarkdown documents
http://blog.revolutionanalytics.com/2017/06/rmarkdown-tricks.html
Converting Rmarkdown to F1000Research LaTeX Format
BiocWorkflowTools package and paper
icons for rmarkdown
https://ropensci.org/technotes/2018/05/15/icon/
Reproducible data analysis
Interactive document: Shiny
When I follow the direction to add the code to the end of this Rmd file, I see
- I can't run "Build" anymore. An error will come out: Error in numericInput("n", "How many cars?", 5) : could not find function "numericInput".
- After I click "Run Document", the Rmd file will be displayed in either RStudio or a regular browser using R's built-in web server (http://127.0.0.1:YYYY/XXX.Rmd).
Automatic document production with R
https://itsalocke.com/improving-automatic-document-production-with-r/
Documents with logos, watermarks, and corporate styles
http://ellisp.github.io/blog/2017/09/09/rmarkdown
rticles and pinp for articles
- https://cran.r-project.org/web/packages/rticles/index.html
- http://dirk.eddelbuettel.com/code/pinp.html
Gmisc: create Table 1 used in medical articles
https://cran.r-project.org/web/packages/Gmisc/index.html
3 sources of reproducibility issues and options how to tackle them
R Markdown: 3 sources of reproducibility issues and options how to tackle them
Tips
- Create R Markdown reports and presentations even better with these 3 practical tips
- Live preview of R Markdown files with xaringan’s infinite_moon_reader(). The Ultimate Infinite Moon Reader for xaringan Slides.
- Creating beautiful, multi format reports directly from R scripts
- Advanced chunk options with useful effects
Cache
- Cache not work
- Examples
> system.time(rmarkdown::render("~/Downloads/tmp.Rmd")) # first time ... Output created: tmp.html user system elapsed 3.123 0.108 5.426 # It will create two directories: tmp_files, tmp_cache > system.time(rmarkdown::render("~/Downloads/tmp.Rmd")) # Second time ... Output created: tmp.html user system elapsed 0.239 0.019 0.317
RStudio
RStudio is the best editor.
Markdown has two drawbacks: 1. it does not support TOC natively. 2. RStudio cannot show headers in the editor.
Therefore, use rmarkdown format instead of markdown.
Writing a R book and self-publishing it in Amazon
Create professional reports from R scripts, with custom styles
How to create professional reports from R scripts, with custom styles
Publish R results
5 amazing free tools that can help with publishing R results and blogging
Scheduling R Markdown Reports via Email
http://www.analyticsforfun.com/2016/01/scheduling-r-markdown-reports-via-email.html
Create presentation file (beamer)
- http://rmarkdown.rstudio.com/beamer_presentation_format.html
- http://www.theresearchkitchen.com/archives/1017 (markdown and presentation files)
- http://rmarkdown.rstudio.com/
- Create Rmd file first in Rstudio by File -> R markdown. Select Presentation > choose pdf (beamer) as output format.
- Edit the template created by RStudio.
- Click 'Knit pdf' button (Ctrl+Shift+k) to create/display the pdf file.
An example of Rmd is
--- title: "My Example" author: You Know Me date: Dec 32, 2014 output: beamer_presentation --- ## R Markdown This is an R Markdown presentation. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>. When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. ## Slide with Bullets - Bullet 1 - Bullet 2 - Bullet 3. Mean is $\frac{1}{n} \sum_{i=1}^n x_i$. $$ \mu = \frac{1}{n} \sum_{i=1}^n x_i $$ ## New slide ![picture of BDGE](/home/brb/Pictures/BDGEFinished.png) ## Slide with R Code and Output ```{r} summary(cars) ``` ## Slide with Plot ```{r, echo=FALSE} plot(cars) ```
R notebook vs R markdown in RStudio
Difference between R MarkDown and R NoteBook
There is no coding difference. The difference is in the rendering. The file extension is the same.
R notebook
- It adds html_notebook in the output option in the header.
- You can then preview the rendering quickly without having to knit it (does not execute any of your R code chunks). If you manually 'Run' the chunks, the result will be shown up in preview.
- It also refreshes the preview every time you save.
- However in that preview you don't have the code output (no figures, no tables..)
- You can mix several output options in your header so that you can keep the preview and keep your knit options for export
- R Notebook is everything and above what R MarkDown is
Table creating packages
stargazer: Produces LaTeX code, HTML/CSS code and ASCII text for well-formatted tables that hold regression analysis results from several models side-by-side, as well as summary statistics
bookdown.org
The website is full of open-source books written with R markdown.
- Announce bookdown
- bookdown package: Authoring Books and Technical Documents with R Markdown
- Compile R for Data Science to a PDF
pkgdown: create a website for your package
- Creating websites in R Emily C. Zabor
- Tip: After creating an R project with <_site.yml> and <index.Rmd> files, we need to quit and open the R project again in order to see the "Build" tab. This can be confirmed by clicking Tools -> Project Options -> Build Tools. The 'Project build tools' should show "Website" (other choices are "(None)", "Package", "Makefile", "Custom"). See also the RStudio IDE section from blogdown: Creating Websites with R Markdown.
- R Markdown Websites
- Building a website with pkgdown: a short guide
- Integrating 'pkgdown' with Your Personal Website
- Introduction to pkgdown. The source code is an Rmd file.
Blogdown
- https://github.com/rstudio/blogdown
- https://bookdown.org/yihui/blogdown/
- BLOGDOWN TUTORIAL Peter's blog
- Customizing Hugo / Blogdown RSS Templates
- Setting up our blog with RStudio and blogdown I: Creating the blog
Posterdown
posterdown: Use RMarkdown to generate PDF Conference Posters via HTML or LaTeX
Latex tools
Mathpix Snip Take a screenshot of math and paste the LaTeX into your editor