Basic Usage

R code chunks can be used as a means render R output into documents or to simply display code for illustration. Here is a simple R code chunk that will result in both the code and it’s output being included:

```{r}
summary(cars)
```

To display the output of a code chunk but not the underlying R code, you specify the echo=FALSE option:

```{r, echo=FALSE}
summary(cars)
```

Note that R code chunks can also be used to render plots. To display a plot while omitting the code used to generate the plot you’d do this:

```{r, echo=FALSE}
plot(cars)
```

To display R code without evaluating it, you specify the eval=FALSE chunk option:

```{r, eval=FALSE}
summary(cars)
```

Table Output

By default data frames and matrixes are output as they would be in the R terminal (in a monospaced font). However, if you prefer that data be displayed with additional formatting you can use the knitr::kable function. For example:

```{r, results='asis'}
knitr::kable(mtcars)
```

Note the use of the results='asis' chunk option. This is required to ensure that the raw table output isn’t processed furthur by knitr. The kable function includes several options to control the maximum number of digits for numeric columns, alignment, etc (refer to the knitr package documentation for additional details).

Caching

If document rendering becomes time consuming due to long computations or plots that are expensive to generate you can use knitr caching to improve performance. The documentation knitr chunk and package options describe how caching works and the cache examples provide additional details.

If you want to enable caching globally for a document you can include a code chunk like this at the top of the document:

```{r setup, include=FALSE}
knitr::opts_chunk$set(cache=TRUE)
```

If you run into problems with cached output you can always clear the knitr cache by removing the folder named with a _cache suffix within your document’s directory.

Rcpp Code Chunks

You can also create code chunks that define functions in C++ using Rcpp Attributes. This is accomplished using the engine = 'Rcpp' chunk option. For example:

```{r engine='Rcpp'}
#include <Rcpp.h>

// [[Rcpp::export]]
int fibonacci(const int x) {
    if (x == 0 || x == 1) return(x);
    return (fibonacci(x - 1)) + fibonacci(x - 2);
}
```

Because fibonacci was defined with the Rcpp::export attribute it can now be called as a normal R function:

```{r}
fibonacci(10L)
fibonacci(20L)
```

Note that caching should not be used with Rcpp code chunks (since the compiled C++ function will not survive past the lifetime of the current R session).

Learning More

The knitr package is an extremely powerful tool for dynamic content generation and is worth studying in detail to understand all of it’s features and capabilities. Good resources for learning more about knitr include:

comments powered by Disqus