3.3 Render an R script to a report

Even if you are a long-time R Markdown user, you may have missed another possibility. Dean Attali called it “knitr’s best hidden gem.” That is, you can render a pure R script to a report directly. If you use the RStudio IDE, the keyboard shortcut to render R scripts is the same as when you knit Rmd documents (Ctrl / Cmd + Shift + K).

When rendering an R script to a report, the function knitr::spin() is called to convert the R script to an Rmd file first. This function is what Dean Attali called knitr’s best hidden gem. You will see all text and graphical output in the report.

If you want granular control over the elements in the report, below are a few syntax rules to help you:

  • Roxygen comments will be treated as normal text. A roxygen comment is an R comment that starts with #'. This can help you write narratives in your report. You can use any Markdown syntax in the comments.

  • A comment starting with #+ is treated as the knitr chunk header. For example, knitr::spin() will translate the comment #+ label, fig.width=5 to the chunk header ```{r label, fig.width=5} in R Markdown.

  • R code of the form {{ code }} is translated to an inline R expression in R Markdown. Please note that {{ code }} must be on its own line.

  • The YAML frontmatter can be written in the beginning of the R script in roxygen comments, too. Please watch out for the indentation in YAML fields. It is very important. If you omit the indentation, the data structure expressed in your YAML will be different and incorrect. For example, the field keep_tex: true should be indented for two more spaces under pdf_document in the example below.

  • Any text between /* and */ will be ignored (i.e., they are treated as true comments).

Below is a full example illustrating the above rules:

  1. #' ---
  2. #' title: "A report generated from a pure R script"
  3. #' output:
  4. #'   pdf_document:
  5. #'     keep_tex: true
  6. #' ---
  7. #'
  8. #' This is a report generated by `knitr::spin()`.
  9. #'
  10. #' Let's try some **knitr** options:
  12. #+ echo=FALSE, fig.width=7
  13. #  This is a normal R comment.
  14. plot(cars)
  16. #' Now write an inline value. We know the value of $\pi$ is
  17. {{ pi }}
  18. #' .
  19. #'
  20. #' Finally please note that all roxygen comments are
  21. #' optional. You do not need chunk options, either,
  22. #' unless you want more control over the output
  23. #' elements such as the size of plots.
  25. # /* Write comments between /* and */ like C comments:
  26. Sys.sleep(60)
  27. # */

When this script is rendered to a report, knitr::spin() will convert it to R Markdown:

  1. ---
  2. title: "A report generated from a pure R script"
  3. output:
  4.   pdf_document:
  5.     keep_tex: true
  6. ---
  8. This is a report generated by `knitr::spin()`.
  10. Let's try some **knitr** options:
  12. ```{r echo=FALSE, fig.width=7}
  13. #  This is a normal R comment.
  14. plot(cars)
  15. ```
  17. Now write an inline value. We know the value of $\pi$ is
  18. ``r  pi  ``
  19. .
  21. Finally please note that all roxygen comments are
  22. optional. You do not need chunk options, either,
  23. unless you want more control over the output
  24. elements such as the size of plots.

This method of generating reports can be particularly useful when you primarily work with R scripts and do not need a lot of narratives. If the proportion of text is substantial in your report, R Markdown may be a better choice, because you do not need to put all text in roxygen comments.