Site icon R-bloggers

Default knitr options and hooks

[This article was first published on The Jumping Rivers Blog, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

This is part four of our four part series

As with many aspects of programming, when you are working by yourself you can be (slightly) more lax with styles and set-up. However, as you start working in a team, different styles can quickly become a hindrance and lead to errors.

Using {knitr} is no different. When you work on documents with different team members, it’s helpful to have a consistent set of settings. If the default for eval changes, this can easily waste time as you try to track down an error. At Jumping Rivers, we use {knitr} a lot. From our training courses, to providing feedback to clients, to constructing monthly reports on clients infrastructure. The great thing about {knitr} is it’s really easy to customise. The bad thing is that without some care, it’s really easy for every member of the team to have different default options. This proliferation of different default options, means that when we pick up someone else document, mistakes may creep in.

We’ve found that to work effectively as team, we need a consistent set of global settings. To be honest, it isn’t really that important what the options are, it’s more crucial that they exist. In this post, we’ll describe the standard {knitr} we have and use.


Do you use RStudio Pro? If so, checkout out our managed RStudio services


Code Chunks

These options ensure that code chunks perform in a standard manner. The options below are relatively standard

Graphics Options

We’ve just had three blog posts on graphics options, so clearly standardisation is a good thing here! Having a consistent set of {knitr} options makes standardising figures across documents (slightly) easier.

These options control the graphics options.

Graphics Device

The graphics device is the default device for used to create and provide graphics. This options is controlled via the dev argument. For our training courses, where we produce PDF booklets of notes we set dev = "cairo_pdf" as the default. For blog post and HTML documents, such as this, we set dev = "svg". We also set dev.args = list(png = list(type = "cairo-png")), so that when we set dev = "png", we use the cairo-png variety.

{knitr} hooks

In our recent blog post on optimising PNG images, we discussed the optipng utility for reducing your file size. It’s actually straightforward to use optipng as a {knitr} hook, i.e. whenever you generate a PNG file, optipng automatically runs.

If you have optipng installed, you simply add the hook

knitr::knit_hooks$set(optipng = knitr::hook_optipng)

to the top of your document. You can also tweak the options via

# The args `-o1 -quiet' are passed to optipng
knitr::opts_chunk$set(optipng = "-o1 -quiet")

Putting it all together

When we put all of the above together, we end up with

knitr::opts_chunk$set(echo = FALSE, 
                      collapse = TRUE,
                      comment = "#>",
                      fig.path = "graphics/knitr-",
                      fig.retina = 2, # Control using dpi
                      fig.width = 6,  # generated images
                      fig.pos = "t",  # pdf mode
                      fig.align = "center",
                      dpi = if (knitr::is_latex_output()) 72 else 300, 
                      out.width = "100%",
                      dev = "svg",
                      dev.args = list(png = list(type = "cairo-png")),
                      optipng = "-o1 -quiet")

This can then be placed in an simple helper package to avoid duplication.

A note on aspect ratio: fig.asp

As with all graphic related options, there isn’t one single setting that is suitable for all situations. While fig.asp=0.7 gives a sensible default, you shouldn’t be frighted to change it. I found this article on when to use different aspect ratios very informative. R for Data Science also has a short section on figure sizing that’s worth reading.

For updates and revisions to this article, see the original post

To leave a comment for the author, please follow the link and comment on their blog: The Jumping Rivers Blog.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.