Embedding images in R package help pages

by Andrie de Vries

Have you noticed that most R help does not contain any images? Historically, this was for a good reason: most programming language help assumes that you use the system on a text-only system, e.g. a headless linux server. If your system has no graphical capabilities, but the help contains images, then the help itself can become confusing.

That said, most R users use their help on a system with full graphical capabilities. Thus the R core team updated R itself in version 2.12 to have the ability to include images in your help.

The question is how do you go about creating help files that contain images?

My search engine skills only uncovered two references:

• A blog post by Romain Francois: "embed images in Rd documents".
• An answer to a question on StackOverflow: "Including images in R-package documentation (.Rd) files". This was answered by Roman Lustrik.

Both approaches require you to use a tag in your .Rd file:

• Use the \sexpr tag:
  • Romain's suggestion is really powerful, since it uses a mechanism to dynamically render R code directly in your Rd file.  I didn't know this, but the R Extensions manual describes how to use the tag \sexpr to render R code dynamically. In his blog post, Romain gives an example of doing this.
• Use the \figure tag:
  • The answer at StackOverflow points to the \figure tag. This allows you to post a png image into HTML help, or a pdf image into PDF help.

Putting this into action

For one of the projects I'm working on, the AzureML package, I opted for the second option. The AzureML package (source code on github) allows you to interact with the AzureML Machine Learning Studio, directly from R.

I wanted to include some diagrams in the help pages to make it easy to find the credentials you need to connect to the AzureML service.

The code to create the help page looks like this. Notice the \figure{} to include the images.

#' @section Finding your AzureML credentials:
#' You can find your Azure Machine Learning \code{workspace id} and \code{authorization token} in the Azure Machine Learning Studio interface.
#' 
#' Workspace ID
#' 
#' \if{html}{\figure{workspace_id.png}{options: width="60\%" alt="Figure: workspace_id.png"}}
#' 
#' Authorization token
#' 
#' \if{html}{\figure{authorization_token.png}{options: width="60\%" alt="Figure: authorization_token.png"}}
#' 

One more thing: you need to put the images in the package folder man/figures.

The result in RStudio looks like this:

 

For more information about the AzureML package, take a look at the README on github, or read the package vignette.

Comments

[Kent Johnson]

You can use RMarkdown to create HTML vignettes containing figures. It works the same as ordinary RMarkdown documents; i.e. very simple. Figures are created using R code. See the vignettes included in ggplot2 2.0 for examples.

[Andrie de Vries]

Kent

You are correct - it is very easy to embed figures in vignettes, with or without markdown. I should probably have mentioned this in my original post.

Thanks for the comment.

Andrie