This post provides a basic introduction to R Markdown.1 An R Markdown file contains three essential ingredients – a YAML header to define document-wide settings, chunks of R code, and markdown text. They are designed to be used:
- For communicating to those who want to focus on the conclusions, not the code behind the analysis.
- For collaborating with those who are interested in both the conclusions and how they were reached.
- For capturing the work you do and what you were thinking at the time.
- R Markdown Cheat Sheet: a quick reference
- R Markdown Reference: overview of markdown syntx, knitr chunk options, and Pandoc options
- R Markdown: The Definitive Guide: a comprehensive overview of R Markdown
- Git and Github chapter of R Packages: learn about git with R
toc: TRUEadds a table of contents.
toc_float: TRUEmakes the table of contents float as you scross through the document.
code_foldingmakes code chunks hidden by default but visible with a click.
- For a list of options, see
parametersto set values when rendering the report; useful with
pwalk()to re-render with different variables.
bibliographyto a bibliography file to automatically generate citations.
Formatting code chunks
eval = FALSEprevents code from being evaluated.
include = FALSEruns the code, but doesn’t show the code or results in the final document.
echo = FALSEprevents code, but not results from appearing in the finished file.
message = FALSEor
warning = FALSEprevents messages or warnings from appearing in the finished file.
results = 'hide'hides printed output, and
fig.show = 'hide'hides plots.
fig.show = 'hold'holds multiple plots from a code chunk, and
out.width = '50%'specifies the width.
error = TRUEcauses the render to continue even if code returns an error (for debugging).
Tip: To print fancier-looking tables, surround your code with
knitr::kable(..., caption = "Table Title") or use other packages such as
xtable, stargazer, apnder, tables, ascii.
Tip: Cache code chunks for better performance with the option
cache = TRUE. Use the
dependson option if the chunk needs to be re-run if a dependency is changed, specifying a character vector of every chunk that the cached cunk depends on. Clean the cache with
Tip: Change the code chunk defaults at the beginning of the document – for example, if you are presenting a doc for decision makers, you can turn off the default display of code globally:
Troubleshooting R Markdown
- Restart R, then run all chunks ( Ctrl + Alt + R )
- Check the working directory with
r getwd()in a chunk.
r error = TRUEon the chunk causing the problem, then use
r str()to check settings.
Misc Info - Additional R Markdown Formats
The output format can be set permanently by modifying the YAML header or set once by calling
- Basic document types:
html_notebookto collaborate; they contain full source code, are viewable in a browser and editable in RStudio.
beamer_presentationto create a PDF presentation with LaTeX Beamer
- To produce interactivity,
htmlwidgetsproduces interactive HTML visualizations in markdowon on the client-side, while
shinycreates interactivity using R code, but needs a Shiny server to be run online.
- Other formats include
bookdownto write books, or
prettydocto create nice-looking documents.