Embed external images in knitr documents — include

When plots are not generated from R code, there is no way for knitr to capture plots automatically. In this case, you may generate the images manually and pass their file paths to this function to include them in the output. The major advantage of using this function is that it is portable in the sense that it works for all document formats that knitr supports, so you do not need to think if you have to use, for example, LaTeX or Markdown syntax, to embed an external image. Chunk options related to graphics output that work for normal R plots also work for these images, such as out.width and out.height.

Usage

include_graphics(
  path,
  auto_pdf = getOption("knitr.graphics.auto_pdf", FALSE),
  dpi = NULL,
  rel_path = getOption("knitr.graphics.rel_path", TRUE),
  error = getOption("knitr.graphics.error", TRUE)
)

Arguments

path: A character vector of image paths. Both local file paths and web paths are supported. Note that the auto_pdf and dpi arguments are not supported for web paths.
auto_pdf: Whether to use PDF images automatically when the output format is LaTeX. If TRUE, then e.g. foo/bar.png will be replaced by foo/bar.pdf if the latter exists. This can be useful since normally PDF images are of higher quality than raster images like PNG, when the output is LaTeX/PDF.
dpi: DPI (dots per inch) value. Used to calculate the output width (in inches) of the images. This will be their actual width in pixels, divided by dpi. If not provided, the chunk option dpi is used; if NA, the output width will not be calculated.
rel_path: Whether to automatically convert absolute paths to relative paths. If you know for sure that absolute paths work, you may set this argument or the global option knitr.graphics.rel_path to FALSE.
error: Whether to signal an error if any files specified in the path argument do not exist and are not web resources.

Value

The same as the input character vector path but it is marked with special internal S3 classes so that knitr will convert the file paths to proper output code according to the output format.

Note

This function is supposed to be used in R code chunks or inline R code expressions. For local images, you are recommended to use relative paths with forward slashes instead of backslashes (e.g., images/fig1.png instead of /Users/me/code/images/fig1.png).

The automatic calculation of the output width requires the png package (for PNG images) or the jpeg package (for JPEG images). The width will not be calculated if the chunk option out.width is already provided or dpi = NA.