[This article was first published on Revolutions, 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.

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.

---

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.