knitr Language Engines

Specifying a Python Interpreter

By default, the interpreter returned by Sys.which("python") is used to execute the code. However, if you would like to use a different python interpreter, you can specify one by setting the engine.path option to the path of your preferred executable. For instance:

```{python, engine.path="/Users/me/anaconda/bin/python"}
import sys
print sys.version
```

The engine.path option can also be used on other chunk types which use an external interpreter.

Data Exchange

Since the python engine executes code in an external process, exchanging data between R chunks and python chunks is done via the file system. If you are exchanging data frames, you can use the feather package for very high performance transfer of even large data frames between python and R. Here’s an example that uses feather to transfer a data frame created with pandas to R for plotting with ggplot2:

```{python}
import pandas
import feather

# Read flights data and select flights to O'Hare
flights = pandas.read_csv("flights.csv")
flights = flights[flights['dest'] == "ORD"]

# Select carrier and delay columns and drop rows with missing values
flights = flights[['carrier', 'dep_delay', 'arr_delay']]
flights = flights.dropna()
print flights.head(10)

# Write to feather file for reading from R
feather.write_dataframe(flights, "flights.feather")
```

Now we read the feather file from R and plot the data frame using ggplot2:

```{r}
library(feather)
library(ggplot2)

# Read from feather and plot
flights <- read_feather("flights.feather")
ggplot(flights, aes(carrier, arr_delay)) + geom_point() + geom_jitter()
```

Number of Records Displayed

The number of records displayed is controlled by the max.print option, which is turn derived from the global knitr option sql.max.print (i.e. opts_knit$set(sql.max.print = 10)). For example, the following code chunk displays the first 20 records:

```{sql, connection=db, max.print = 20}
SELECT * FROM trials
```

You can specify no limit on the records to be displayed via max.print = -1 or max.print = NA.

Table Captions

By default the knitr SQL engine includes a caption that indicates the total number of records displayed. You can override this caption using the tab.cap chunk option. For example:

```{sql, connection=db, tab.cap = "My Caption"}
SELECT * FROM trials
```

You can specify that you want no caption all via tab.cap = NA.

Assigning Results to a Data Frame

If you want to assign the results of the SQL query to an R data frame, you can do this using the output.var option, for example:

```{sql, connection=db, output.var="trials"}
SELECT * FROM trials
```

When the results of a SQL query are assigned to a data frame no records are printed within the document (if desired, you can manually print the data frame in a subsequent R chunk).

Using R Variables in Queries

If you need to bind the values of R variables into SQL queries, you can do so by prefacing R variable references with a ?. For example:

```{r}
subjects <- 10
```

```{sql, connection=db, output.var="trials"}
SELECT * FROM trials WHERE subjects >= ?subjects
```

Setting a Default Connection

If you have many SQL chunks, it may be helpful to set a default for the connection chunk option in the setup chunk, so that it is not necessary to specify the connection on each individual chunk. You can do this as follows:

```{r setup}
library(DBI)
db <- dbConnect(RSQLite::SQLite(), dbname = "sql.sqlite")
knitr::opts_chunk$set(connection = "db")
```

Note that the connection parameter should contain a string naming the connection object (not the object itself). Once set, you can execute SQL chunks without naming an explicit connection:

```{sql}
SELECT * FROM trials
```

Caching

You can cache the compilation of C++ code chunks using standard knitr caching. Note however that this feature currently requires the most recent versions of both the Rcpp (v0.12.6) and knitr (v1.14) packages, which you can install as follows:

install.packages("Rcpp")
install.pakcages("knitr")

To cache the compilation of an Rcpp chunk simply add the cache = TRUE option to the chunk:

```{Rcpp, cache=TRUE}
#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
NumericVector timesTwo(NumericVector x) {
  return x * 2;
}
```

Combining Chunks

In some cases it’s desirable to combine all of the Rcpp code chunks in a document into a single compilation unit. This is especially useful when you want to intersperse narrative between pieces of C++ code (e.g. for a tutorial or user guide). It also reduces total compilation time for the document (since there is only a single invocation of the C++ compiler rather than multiple).

To combine all Rcpp chunks into a single compilation unit you use the ref.label chunk option along with the knitr::all_rcpp_labels() function to collect all of the Rcpp chunks in the document. Here’s a simple example:

```{Rcpp, ref.label=knitr::all_rcpp_labels(), cache=TRUE, include=FALSE}
```

```{Rcpp, eval = FALSE}
#include <Rcpp.h>
```

```{Rcpp, eval = FALSE}
// [[Rcpp::export]]
int timesTwo(int x) {
  return x * 2;
}
```

The two Rcpp chunks that include code will be collected and compiled together in the first Rcpp chunk via the ref.label chunk option. Note that we set the eval = FALSE option on the Rcpp chunks with code in them to prevent them from being compiled again.