Parameterizing R Markdown Reports

On Tuesday, I attended an R-Ladies NYC Meetup which included an interesting talk on using parameters for R Markdown reports. This talk was presented by Elizabeth Mauer, a Research Biostatistician at Weill Cornell Medicine.

At work, Elizabeth creates a lot of R Markdown reports which she hands over investigators to review. A lot of the feedback that she receives centers around running the same analysis, but on different subsets of patients or under different conditions. With the amount of requests that Elizabeth gets, she would not want to re-write her source code each time; this would take time, she could make mistakes and threaten the overall reproducibility of her report. This led to the parameterized solution.

Essentially, parameters in R Markdown allow you to use the same source code, just to render different reports under different conditions. This is useful for creating reports with different selections of data like year, location, or whatever your subset of data might be.

How to Implement Parameters?

Parameters are implemented within the YAML header of an R Markdown file. This is the preset header in a R Markdown file that has fields for your file title, date and output (If you’re wondering what YAML means: “YAML Ain’t Markup Language”). Parameters are implemented with a “params” field below the preset fields as seen in the screenshot below:

In this case, Elizabeth specified parameters for which surgery data to use, which year to use and set printcode to TRUE (to designate chunks to print).

While parameters are specified in the YAML, they are accessed in the source code as seen in the screenshot below:

Knitting with Parameters

Once the source code is in place, the R Markdown can be Knit with the “Knit” button or the below “rmarkdown” code:

Parameter UI:

An alternative is to use an interactive user interface in RStudio which not only allows you to Knit your file, but to input your parameter values as well. This UI can be accessed by going to the “Knit” dropdown and selecting “Knit with Parameters” or using the follwing code: markdown::render(“My_Parameter_Document.Rmd”, params=”ask”)

Parameter Attributes

Lastly, sometimes, you might want to additional conditions to parameters by constraining the data range or data options for that parameter. This can also be done in the YAML by adding attributes (or additional arguments) to each parameter as seen below:

Parameter attributes can also be added through the interactive UI which also contains different features for selecting your inputs like sliders and check boxes. This can be observed above where Elizabeth added a “slider” option for the “year” parameter with the slider ranging from 2010 to 2018.

For further details and information, click here for Elizabeth’s full presentation and some practice code with wine ratings data.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s