It is really that easy

Here is how long it takes to get it up and running, package installation included:

Infinite moon reader

Kind of obviously, this functionality can become a huge time saver, especially if you are tweaking the design of your slides and want to see the results quickly without the need to click/call knit over and over again.

A quick example

A working example is worth more than explanations here, so here we go. Just copy the following, save for example into script.R and run knitr::spin("script.R"):

#' # This is just an R script
#' ## Rendered to a html report with knitr::spin()
#' * just by adding comments we can make a really nice output

#'
#' > And the code runs just like normal, eg. via `Rscript` after all
#' __comments__ are just *comments*.
#'
#' ## The report begins here
#+
knitr::kable(head(mtcars))

#' ## A chart
#+ fig.width=8, fig.height=8
heatmap(cor(mtcars))

#' ## Some tips
#'
#' 1. Optional chunk options are written using `#+`
#' 1. You can write comments between `/*` and `*/`

By default, the result will something like the following:

Spinned it right round

Compile Report and RMarkdown’s render() vs. knitr’s spin()

We can achieve similar results in RStudio by clicking on File -> Compile Report..., which is equivalent to using rmarkdown::render() on an R script file. This will call spin() and add some metadata such as title, author and time to the output.

So why bother with spin() at all?

The default behavior has some important differences between calling the functions mentioned above. One of them for HTML output is that render() will by default include inline base64 representations of fonts and JavaScript sources, increasing the output file size from less them 20 KB to more than 600 KB even with the smallest amount of content.

This is why I personally like to call knitr::spin() to keep the output at smaller sizes by default, without having to dig in into the options passed to pandoc.

Regardless of the technical details, being able to produce good looking reports directly from R scripts can save a lot of time and error-prone copying, while keeping the content and runnable code in one place, instead of copy-pasting into code chunks of an R Markdown file.

This is of course not to say that R Markdown files are not useful. To the contrary, they are great for many use cases. However, if the content is mostly code with some accompanying text, using spin() can come in really handy.

results='asis' to keep content generated by a chunk unprocessed

Especially when producing HTML output it may be helpful to create functions that produce output we want to include directly in the rendered document without any processing, such as HTML code produced by a pre-made function.

One example I use often is a function makeHighChart() that creates a lightweight JavaScript representation of a chart created via highcharter from an R object. The output of that function is HTML code that should be placed as-is into the output, for which the results='as-is' chunk option is made:

# This chunk uses the results='as-is' option like so:
# ```{r results='asis'}
# The results is an interactive chart:
jhaddins::makeHighChart(
  highcharter::hcboxplot(mtcars$hp),
  chartname = "examplechart",
  docat = TRUE
)

# This one does not use the results option, it is just
# ```{r}
# The result is not very useful printed HTML:
jhaddins::makeHighChart(
  highcharter::hcboxplot(mtcars$mpg),
  chartname = "examplechart",
  docat = TRUE
)
## <script type="text/javascript">
## $(function () {
##   $('#examplechart').highcharts({
##   title: {     
##     text: null     
##   },     
##   yAxis: {     
##     title: {     
##       text: null     
##     }     
##   },     
##   credits: {     
##     enabled: false     
##   },     
##   exporting: {     
##     enabled: false     
##   },     
##   plotOptions: {     
##     series: {     
##       turboThreshold: 0,     
##       marker: {     
##         symbol: "circle"     
##       },     
##       showInLegend: false     
##     },     
##     treemap: {     
##       layoutAlgorithm: "squarified"     
##     },     
##     bubble: {     
##       minSize: 5,     
##       maxSize: 25     
##     }     
##   },     
##   annotationsOptions: {     
##     enabledButtons: false     
##   },     
##   tooltip: {     
##     delayForDisplay: 10     
##   },     
##   chart: {     
##     type: "bar"     
##   },     
##   xAxis: {     
##     type: "category",     
##     categories: ""     
##   },     
##   series: [     
##     {     
##       name: null,     
##       data: [     
##         {     
##           name: null,     
##           low: 10.4,     
##           q1: 15.35,     
##           median: 19.2,     
##           q3: 22.8,     
##           high: 33.9     
##         }     
##       ],     
##       type: "boxplot",     
##       id: null     
##     }     
##   ]     
## }     
##   );
## });
## </script>
## 
## <div id="examplechart"></div>

class.output="some_css_class" to format chunk output with custom css

For HTML output, we may want to style it with our own css. This option allows to use defined css classes to style the output produced by that chunk. This can be very convenient if we want to style some chunks in a different manner elegantly. We can also provide multiple css classes in a character vector instead of just one.

cache=TRUE to render faster and more reproducibly

In case your documents contain calculations that a take lot of time, or just cause unnecessary pain when re-executed with each render, for example when including benchmarking results in posts, it is very convenient to cache the chunk results. This will not only make the rendering faster, but also ensure that the results of the same code will stay the same in the output, even if we re-render the document.

Note that for keeping reproducibility when random number generation is included with caching results, it is advised to also include knitr::opts_chunk$set(cache.extra = knitr::rand_seed) in the document. available here.