R: Insert animations into a LaTeX document and compile it

saveLatex {animation}

R Documentation

Insert animations into a LaTeX document and compile it

Description

Record animation frames and insert them into a LaTeX document with the animate package. Compile the document if an appropriate LaTeX command is provided.

Usage

saveLatex(expr, nmax, img.name = "Rplot", ani.opts, centering = TRUE, caption = NULL, 
    label = NULL, pkg.opts = NULL, documentclass = "article", latex.filename = "animation.tex", 
    pdflatex = "pdflatex", install.animate = TRUE, overwrite = TRUE, full.path = FALSE, 
    ...)

Arguments

`expr`	an expression to generate animations; use either the animation functions (e.g. `brownian.motion()`) in this package or a custom expression (e.g. `for(i in 1:10) plot(runif(10), ylim = 0:1)`).
`nmax`	maximum number of animation frames (if missing and the graphics device is a bitmap device, this number will be automatically calculated); note that we do not have to specify `nmax` when using PDF devices.
`img.name`	basename of file names of animation frames; see the Note section for a possible adjustment on `img.name`
`ani.opts`	options to control the behavior of the animation (passed to the LaTeX macro `"\animategraphics"`; default to be `"controls,width=\linewidth"`)
`centering`	logical: whether to center the graph using the LaTeX environment \begin{center} and \end{center}
`caption,label`	caption and label for the graphics in the figure environment
`pkg.opts`	global options for the `animate` package
`documentclass`	LaTeX document class; if `NULL`, the output will not be a complete LaTeX document (only the code to generate the PDF animation will be printed in the console); default to be `article`, but we can also provide a complete statement like \documentclass[a5paper]{article}
`latex.filename`	file name of the LaTeX document; if an empty string `""`, the LaTeX code will be printed in the console and hence not compiled
`pdflatex`	the command for pdfLaTeX (set to `NULL` to ignore the compiling)
`install.animate`	copy the LaTeX style files ‘animate.sty’ and ‘animfp.sty’ to `ani.options('outdir')`? If you have not installed the LaTeX package `animate`, it suffices just to copy these to files.
`overwrite`	whether to overwrite the existing image frames
`full.path`	whether to use the full path (`TRUE`) or relative path (`FALSE`) for the animation frames; usually the relative path suffices, but sometimes the images and the LaTeX document might not be in the same directory, so `full.path = TRUE` could be useful; in the latter case, remember that you should never use spaces in the filenames or paths!
`...`	other arguments passed to the graphics device `ani.options('ani.dev')`, e.g. `ani.height` and `ani.width`

Details

This is actually a wrapper to generate a LaTeX document using R. The document uses the LaTeX package called animate to insert animations into PDF's. When we pass an R expression to this function, the expression will be evaluated and recorded by a grahpics device (typically png and pdf). At last, a LaTeX document will be created and compiled if an appropriate LaTeX command is provided. And the final PDF output will be opened with the PDF viewer set in getOption("pdfviewer") if ani.options("autobrowse") == TRUE.

Value

Invisible NULL

Note

This function will detect if it was called in a Sweave environment – if so, img.name will be automatically adjusted to prefix.string-label, and the LaTeX output will not be a complete document, but rather a single line like

\animategraphics[ani.opts]{1/interval}{img.name}{}{}

This automatic feature can be useful to Sweave users (but remember to set the Sweave option results=tex). See demo('Sweave_animation') for a complete example. PDF devices are recommended because of their high quality and usually they are more friendly to LaTeX, but the size of PDF files is often much larger; in this case, we may set the option 'qpdf' or 'pdftk' to compress the PDF graphics output. To set the PDF device, use ani.options(ani.dev = 'pdf', ani.type = 'pdf') So far animations created by the LaTeX package animate can only be viewed with Acrobat Reader (Windows) or acroread (Linux). Other PDF viewers may not support JavaScript (in fact the PDF animation is driven by JavaScript). Linux users may need to install acroread and set options(pdfviewer = 'acroread').

Author(s)

Yihui Xie <http://yihui.name>

References

To know more about the animate package, please refer to http://www.ctan.org/tex-archive/macros/latex/contrib/animate/. There are a lot of options can be set in ani.opts and pkg.opts.

Examples

## brownian motion: note the 'loop' option in ani.opts and the careful settings
## in documentclass

saveLatex({
    par(mar = c(3, 3, 1, 0.5), mgp = c(2, 0.5, 0), tcl = -0.3, cex.axis = 0.8, cex.lab = 0.8, 
        cex.main = 1)
    brownian.motion(pch = 21, cex = 5, col = "red", bg = "yellow", main = "Demonstration of Brownian Motion")
}, img.name = "BM", ani.opts = "controls,loop,width=0.95\\\\textwidth", 
    latex.filename = ifelse(interactive(), "brownian_motion.tex", ""), interval = 0.1, 
    nmax = 10, ani.dev = "pdf", ani.type = "pdf", ani.width = 7, ani.height = 7, 
    documentclass = paste("\\\\documentclass{article}", "\\\\usepackage[papersize={7in,7in},margin=0.3in]{geometry}", 
        sep = "\n"))

## the PDF graphics output is often too large because it is uncompressed; try
## the option ani.options('pdftk') or ani.options('qpdf') to compress the PDF
## graphics; see ?pdftk or ?qpdf and ?ani.options

[Package animation version 2.2 Index]