Permalink
Fetching contributors…
Cannot retrieve contributors at this time
1998 lines (1449 sloc) 31.4 KB
#LyX 2.1 created this file. For more info see http://www.lyx.org/
\lyxformat 474
\begin_document
\begin_header
\textclass tufte-handout
\begin_preamble
\renewcommand{\textfraction}{0.05}
\renewcommand{\topfraction}{0.8}
\renewcommand{\bottomfraction}{0.8}
\renewcommand{\floatpagefraction}{0.75}
\usepackage[buttonsize=1em]{animate}
\end_preamble
\options justified
\use_default_options true
\begin_modules
knitr
\end_modules
\maintain_unincluded_children false
\language english
\language_package none
\inputencoding default
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_math auto
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref true
\pdf_bookmarks true
\pdf_bookmarksnumbered true
\pdf_bookmarksopen true
\pdf_bookmarksopenlevel 2
\pdf_breaklinks true
\pdf_pdfborder false
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle true
\pdf_quoted_options "pdfstartview=FitH"
\papersize default
\use_geometry true
\use_package amsmath 1
\use_package amssymb 1
\use_package cancel 1
\use_package esint 1
\use_package mathdots 1
\use_package mathtools 1
\use_package mhchem 1
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\justification true
\use_refstyle 1
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 2
\tocdepth 2
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header
\begin_body
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<setup, include=FALSE, cache=FALSE>>=
\end_layout
\begin_layout Plain Layout
library(knitr)
\end_layout
\begin_layout Plain Layout
options(formatR.arrow=TRUE,width=50)
\end_layout
\begin_layout Plain Layout
opts_chunk$set(fig.path='figure/graphics-', cache.path='cache/graphics-',
fig.align='center', dev='tikz', fig.width=5, fig.height=5, fig.show='hold',
cache=TRUE, par=TRUE)
\end_layout
\begin_layout Plain Layout
knit_hooks$set(par=function(before, options, envir){
\end_layout
\begin_layout Plain Layout
if (before && options$fig.show!='none') par(mar=c(4,4,.1,.1),cex.lab=.95,cex.axis=.9,mg
p=c(2,.7,0),tcl=-.3)
\end_layout
\begin_layout Plain Layout
}, crop=hook_pdfcrop)
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Title
knitr Graphics Manual
\end_layout
\begin_layout Author
Yihui Xie
\end_layout
\begin_layout Abstract
This manual shows features of graphics in the
\series bold
knitr
\series default
package (version
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
Sexpr{packageVersion('knitr')}
\end_layout
\end_inset
) in detail, including the graphical devices, plot recording, plot rearrangement
, control of plot sizes, the tikz device, figure captions, animations and
other types of plots such as
\series bold
rgl
\series default
or GGobi plots.
\end_layout
\begin_layout Standard
Before reading this specific manual
\begin_inset Foot
status open
\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://bit.ly/knitr-graphics-src
\end_layout
\end_inset
(Rnw source)
\end_layout
\end_inset
, you must have finished the main manual
\begin_inset Foot
status open
\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://bit.ly/knitr-main
\end_layout
\end_inset
\end_layout
\end_inset
.
\end_layout
\begin_layout Section
Graphical Devices
\end_layout
\begin_layout Standard
The
\series bold
knitr
\series default
package comes with more than 20 built-in graphical devices, and you can
specify them through the
\family typewriter
dev
\family default
option.
This document uses the global option
\family typewriter
dev='tikz'
\family default
, i.e., the plots are recorded by the tikz device by default, but we can change
the device locally.
Since tikz will be used extensively throughout this manual and you will
see plenty of tikz graphics later, now we first show a few other devices.
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<test-plot, eval=FALSE>>=
\end_layout
\begin_layout Plain Layout
with(trees, symbols(Height, Volume, circles = Girth/16, inches = FALSE,
bg = 'deeppink', fg = 'gray30'))
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Float marginfigure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<pdf-dev, ref.label='test-plot', dev='pdf', out.width='
\backslash
\backslash
linewidth', echo=FALSE>>=
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
The default PDF device.
\begin_inset CommandInset label
LatexCommand label
name "mar:pdf-dev"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Float marginfigure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<png-dev, ref.label='test-plot', dev='png', out.width='
\backslash
\backslash
linewidth', echo=FALSE>>=
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
The PNG device.
\begin_inset CommandInset label
LatexCommand label
name "mar:png-dev"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "mar:pdf-dev"
\end_inset
and
\begin_inset CommandInset ref
LatexCommand ref
reference "mar:png-dev"
\end_inset
show two standard devices in the
\series bold
grDevices
\series default
package.
We can also use devices in the
\series bold
Cairo
\series default
or
\series bold
cairoDevice
\series default
package, e.g., the chunk below uses the
\emph on
CairoPNG()
\emph default
device in the
\series bold
Cairo
\series default
package.
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<cairo-png-dev, ref.label='test-plot', dev='CairoPNG', out.width='.5
\backslash
\backslash
linewidth', echo=FALSE>>=
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Section
Plot Recording
\end_layout
\begin_layout Standard
As mentioned in the main manual,
\series bold
knitr
\series default
uses the
\series bold
evaluate
\series default
package to record plots.
There are two sources of plots: first, whenever
\emph on
plot.new()
\emph default
or
\emph on
grid.newpage()
\emph default
is called,
\series bold
evaluate
\series default
will try to save a snapshot of the current plot
\begin_inset Foot
status open
\begin_layout Plain Layout
For technical details, see
\family typewriter
?setHook
\family default
and
\family typewriter
?recordPlot
\end_layout
\end_inset
; second, after each complete expression is evaluated, a snapshot is also
saved.
To speed up recording, the null graphical device
\family typewriter
pdf(file = NULL)
\family default
is used.
Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:two-high"
\end_inset
shows two expressions producing two high-level plots.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<two-high, fig.width=3, fig.height=2.5, out.width='.49
\backslash
\backslash
linewidth'>>=
\end_layout
\begin_layout Plain Layout
plot(cars)
\end_layout
\begin_layout Plain Layout
boxplot(cars$dist,xlab='dist')
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
Two high-level plots are captured.
The key to arrange two plots side by side is to specify the
\family typewriter
out.width
\family default
option so that each plot takes less than half of the line width.
We do not have to use the
\family typewriter
par(mfrow)
\family default
trick, and it may not work in some cases (e.g.
to put base graphics and
\series bold
ggplot2
\series default
side by side; recall Figure 1 in the main manual).
\begin_inset CommandInset label
LatexCommand label
name "fig:two-high"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:low-plot-loop"
\end_inset
shows another example of two R expressions, but the second expression only
involves with low-level plotting changes.
By default, low-level plot changes are discarded, but you can retain them
with the option
\family typewriter
fig.keep='all'
\family default
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<low-plot-loop, fig.width=3, fig.height=2.5, out.width='.49
\backslash
\backslash
linewidth', fig.keep='all'>>=
\end_layout
\begin_layout Plain Layout
plot(0,0,type='n',ann=FALSE)
\end_layout
\begin_layout Plain Layout
for(i in seq(0, 2*pi,length=20)) {points(cos(i),sin(i))}
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
Two complete R expressions will produce at most two plots, as long as there
are not multiple high-level plotting calls in each expression; option
\family typewriter
fig.keep='all'
\family default
here.
\begin_inset CommandInset label
LatexCommand label
name "fig:low-plot-loop"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Together with
\family typewriter
fig.show='asis'
\family default
, we can show the process of plotting step by step like Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:high-with-low"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<high-with-low, fig.width=3, fig.height=2.5, out.width='.5
\backslash
\backslash
linewidth', fig.keep='all', fig.show='asis'>>=
\end_layout
\begin_layout Plain Layout
plot(cars)
\end_layout
\begin_layout Plain Layout
abline(lm(dist~speed, data=cars)) # a regression line
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
Low-level plot changes in base graphics can be recorded separately, and
plots can be put in the places where they were produced.
\begin_inset CommandInset label
LatexCommand label
name "fig:high-with-low"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
A further note on plot recording:
\series bold
knitr
\series default
examines all recorded plots (as R objects) and compares them sequentially;
if the previous plot is a
\begin_inset Quotes eld
\end_inset
subset
\begin_inset Quotes erd
\end_inset
of the next plot (= previous plot + low-level changes), the previous plot
will be removed when
\family typewriter
fig.keep='high'
\family default
.
If two successive plots are identical, the second one will be removed by
default, so it might be a little bit surprising that the following chunk
will only produce one plot by default
\begin_inset Foot
status open
\begin_layout Plain Layout
adapted from
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
https://github.com/yihui/knitr/issues/41
\end_layout
\end_inset
\end_layout
\end_inset
:
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<identical-plots,eval=FALSE>>=
\end_layout
\begin_layout Plain Layout
m = matrix(1:100, ncol = 10)
\end_layout
\begin_layout Plain Layout
image(m)
\end_layout
\begin_layout Plain Layout
image(m*2) # exactly the same as previous plot
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Section
Plot Rearrangement
\end_layout
\begin_layout Standard
We can rearrange the plots in chunks in several ways.
They can be inserted right after the line(s) of R code which produced them,
or accumulated till the end of the chunk.
There is an example in the main manual demonstrating
\family typewriter
fig.show='asis'
\family default
for two high-level plots, and Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:high-with-low"
\end_inset
in this manual also demonstrates this option for a high-level plot followed
by a low-level change.
\end_layout
\begin_layout Standard
Here is an example demonstrating the option
\family typewriter
fig.keep='last'
\family default
(only the last plot is kept):
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<fig-last, fig.width=5.2, fig.height=3, out.width='.7
\backslash
\backslash
linewidth', fig.keep='last', message=FALSE>>=
\end_layout
\begin_layout Plain Layout
library(ggplot2)
\end_layout
\begin_layout Plain Layout
pie <- ggplot(diamonds, aes(x = factor(1), fill = cut)) + xlab('cut') +
geom_bar(width = 1)
\end_layout
\begin_layout Plain Layout
pie + coord_polar(theta = "y") # a pie chart
\end_layout
\begin_layout Plain Layout
pie + coord_polar() # the bullseye chart
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
Two plots were produced in this chunk, but only the last one is kept.
This can be useful when we experiment with many plots, but only want the
last result.
(Adapted from the
\series bold
ggplot2
\series default
website)
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
When multiple plots are produced by a code chunk, we may want to show them
as an animation with the option
\family typewriter
fig.show='animate'
\family default
.
Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:clock-animation"
\end_inset
shows a simple clock animation; you may compare the code to Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:high-with-low"
\end_inset
to understand that high-level plots are always recorded, regardless of
where they appeared.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<clock-animation, fig.width=3, fig.height=3, out.width='.4
\backslash
\backslash
linewidth', fig.show='animate', tidy=FALSE, crop=TRUE>>=
\end_layout
\begin_layout Plain Layout
par(mar = rep(3, 4))
\end_layout
\begin_layout Plain Layout
for (i in seq(pi/2, -4/3 * pi, length = 12)) {
\end_layout
\begin_layout Plain Layout
plot(0, 0, pch = 20, ann = FALSE, axes = FALSE)
\end_layout
\begin_layout Plain Layout
arrows(0, 0, cos(i), sin(i))
\end_layout
\begin_layout Plain Layout
axis(1, 0, "VI"); axis(2, 0, "IX")
\end_layout
\begin_layout Plain Layout
axis(3, 0, "XII"); axis(4, 0, "III"); box()
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
A clock animation.
You have to view it in Adobe Reader: click to play/pause; there are also
buttons to speed up or slow down the animation.
\begin_inset CommandInset label
LatexCommand label
name "fig:clock-animation"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
We can also set the alignment of plots easily with the
\family typewriter
fig.align
\family default
option; this document uses
\family typewriter
fig.align='center'
\family default
as a global option, and we can also set plots to be left/right-aligned.
Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:maruko-plot"
\end_inset
is an example of a left-aligned plot.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<maruko-plot, fig.width=7, fig.height=4, out.width='.45
\backslash
\backslash
linewidth', fig.align='left', crop=TRUE>>=
\end_layout
\begin_layout Plain Layout
stars(cbind(1:16,10*(16:1)),draw.segments=TRUE)
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
A left-aligned plot adapted from
\family typewriter
?stars
\family default
(I call this the
\begin_inset Quotes eld
\end_inset
Maruko
\begin_inset Quotes erd
\end_inset
plot, and it is one of my favorites; see
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://en.wikipedia.org/wiki/Chibi_Maruko-chan
\end_layout
\end_inset
).
\begin_inset CommandInset label
LatexCommand label
name "fig:maruko-plot"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Section
Plot Size
\end_layout
\begin_layout Standard
We have seen several examples in which two or more plots can be put side
by side, and this is because the plots were resized in the output document;
with the chunk option
\family typewriter
out.width
\family default
less than half of the line width, LaTeX will arrange two plots in one line;
if it is less than
\begin_inset Formula $1/3$
\end_inset
of the line width, three plots can be put in one line.
Of course we can also set it to be an absolute width like
\family typewriter
3in
\family default
(3 inches).
This option is used extensively in this document to control the size of
plots in the output document.
\end_layout
\begin_layout Section
The tikz Device
\end_layout
\begin_layout Standard
The main advantage of using tikz graphics is the consistency of styles between
texts in plots and those in the main document.
Since we can use native LaTeX commands in plots, the styles of texts in
plots can be very sophisticated (see Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:math-formula-tt"
\end_inset
for an example).
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
<<math-formula-tt, fig.width=6, fig.height=2, out.width='
\backslash
\backslash
linewidth'>>=
\end_layout
\begin_layout Plain Layout
plot(0:1,0:1,type='n', ylab='origin of statistics', xlab='statistical presentati
on rocks with
\backslash
\backslash
LaTeX{}')
\end_layout
\begin_layout Plain Layout
text(.5,c(.8,.5,.2), c('
\backslash
\backslash
texttt{lm(y
\backslash
\backslash
textasciitilde{} x)}', '$
\backslash
\backslash
hat{
\backslash
\backslash
beta}=(X^{
\backslash
\backslash
prime}X)^{-1}X^{
\backslash
\backslash
prime}y$', '$(
\backslash
\backslash
Omega,
\backslash
\backslash
mathcal{F},
\backslash
\backslash
mu)$'))
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
A plot created by
\series bold
tikzDevice
\series default
with math expressions and typewriter fonts.
Note the font style consistency -- we write the same expressions in LaTeX
here:
\begin_inset Formula $\hat{\beta}=(X^{\prime}X)^{-1}X^{\prime}y$
\end_inset
and
\begin_inset Formula $(\Omega,\mathcal{F},\mu)$
\end_inset
; also
\family typewriter
lm(y ~ x)
\family default
.
\begin_inset CommandInset label
LatexCommand label
name "fig:math-formula-tt"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
When using XeLaTeX instead of PDFLaTeX to compile the document, we need
to tell the
\series bold
tikzDevice
\series default
package by setting the
\family typewriter
tikzDefaultEngine
\family default
option before all plot chunks (preferably in the first chunk):
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<xetex-tikz, eval=FALSE>>=
\end_layout
\begin_layout Plain Layout
options(tikzDefaultEngine='xetex')
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This is useful and often necessary to compile tikz plots which contain (UTF8)
multi-byte characters.
\end_layout
\begin_layout Section
Figure Caption
\end_layout
\begin_layout Standard
If the chunk option
\family typewriter
fig.cap
\family default
is not
\family typewriter
NULL
\family default
or
\family typewriter
NA
\family default
, the plots will be put in a
\family typewriter
figure
\family default
environment when the output format is LaTeX, and this option is used to
write a caption in this environment using
\family typewriter
\backslash
caption{}
\family default
.
The other two related options are
\family typewriter
fig.scap
\family default
and
\family typewriter
fig.lp
\family default
which set the short caption and a prefix string for the figure label.
The default short caption is extracted from the caption by truncating it
at the first period or colon or semi-colon.
The label is a combination of
\family typewriter
fig.lp
\family default
and the chunk label.
Because
\family typewriter
figure
\family default
is a float environment, it can float away from the chunk output to other
places such as the top or bottom of a page when the TeX document is compiled.
\end_layout
\begin_layout Section
Other Features
\end_layout
\begin_layout Standard
The
\series bold
knitr
\series default
package can be extended with hook functions, and here I give a few examples
illustrating the flexibility.
\end_layout
\begin_layout Subsection
Cropping PDF Graphics
\end_layout
\begin_layout Standard
Some R users may have been suffering from the extra margins in R plots,
especially in base graphics (
\series bold
ggplot2
\series default
is much better in this aspect).
The default graphical option
\family typewriter
mar
\family default
is about
\family typewriter
c(5, 4, 4, 2)
\family default
(see
\family typewriter
?par
\family default
), which is often too big.
Instead of endlessly setting
\family typewriter
par(mar)
\family default
, you may consider the program
\family typewriter
pdfcrop
\family default
, which can crop the white margin automatically
\begin_inset Foot
status open
\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://www.ctan.org/pkg/pdfcrop
\end_layout
\end_inset
\end_layout
\end_inset
.
In
\series bold
knitr
\series default
, we can set up the hook
\emph on
hook_pdfcrop()
\emph default
to work with a chunk option, say,
\family typewriter
crop
\family default
.
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<crop-hook, cache=FALSE>>=
\end_layout
\begin_layout Plain Layout
knit_hooks$set(crop=hook_pdfcrop)
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Now we compare two plots below.
The first one is not cropped (Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:pdf-nocrop"
\end_inset
); then the same plot is produced but with a chunk option
\family typewriter
crop=TRUE
\family default
which will call the cropping hook (Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:pdf-crop"
\end_inset
).
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
begin{kframe}
\end_layout
\begin_layout Plain Layout
<<pdf-nocrop, fig.width=3.2, fig.height=3.2, out.width='.5
\backslash
\backslash
linewidth'>>=
\end_layout
\begin_layout Plain Layout
par(mar=c(5,4,4,2),bg='white') # large margin
\end_layout
\begin_layout Plain Layout
plot(lat~long,data=quakes,pch=20,col=rgb(0,0,0,.2))
\end_layout
\begin_layout Plain Layout
@
\end_layout
\begin_layout Plain Layout
\backslash
end{kframe}
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
The original plot produced in R, with a large margin.
\begin_inset CommandInset label
LatexCommand label
name "fig:pdf-nocrop"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
begin{kframe}
\end_layout
\begin_layout Plain Layout
<<pdf-crop, ref.label='pdf-nocrop', echo=FALSE, fig.width=3.2, fig.height=3.2,
out.width='.5
\backslash
\backslash
linewidth', crop=TRUE>>=
\end_layout
\begin_layout Plain Layout
@
\end_layout
\begin_layout Plain Layout
\backslash
end{kframe}
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
The cropped plot; it fits better in the document.
\begin_inset CommandInset label
LatexCommand label
name "fig:pdf-crop"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
As we can see, the white margins are gone.
If we use
\emph on
par()
\emph default
, it might be hard and tedious to figure out a reasonable amount of margin
in order that neither is any label cropped nor do we get a too large margin.
My experience is that
\family typewriter
pdfcrop
\family default
works well with base graphics, but barely works with
\series bold
grid
\series default
graphics (therefore
\series bold
lattice
\series default
and
\series bold
ggplot2
\series default
are ruled out).
\end_layout
\begin_layout Subsection
Manually Saved Plots
\end_layout
\begin_layout Standard
We have explained how R plots are recorded before.
In some cases, it is not possible to capture plots by
\emph on
recordPlot()
\emph default
(such as
\series bold
rgl
\series default
plots), but we can save them using other functions.
To insert these plots into the output, we need to set up a hook first like
this (see
\family typewriter
?hook_plot_custom
\family default
for details):
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<custom-plot-hook, cache=FALSE>>=
\end_layout
\begin_layout Plain Layout
knit_hooks$set(custom.plot = hook_plot_custom)
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Then we set the chunk option
\family typewriter
custom.plot=TRUE
\family default
, and manually write plot files in the chunk.
Here we show an example of capturing GGobi plots using the function
\emph on
ggobi_display_save_picture()
\emph default
in the
\series bold
rggobi
\series default
package:
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<ggobi-plot, custom.plot=TRUE, fig.ext='png', out.width='2.5in', results='hide',
warning=FALSE>>=
\end_layout
\begin_layout Plain Layout
library(rggobi)
\end_layout
\begin_layout Plain Layout
ggobi(ggobi_find_file('data', 'flea.csv'))
\end_layout
\begin_layout Plain Layout
Sys.sleep(1) # wait for snapshot
\end_layout
\begin_layout Plain Layout
ggobi_display_save_picture(path=fig_path('.png'))
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Standard
One thing to note here is we have to make sure the plot filename is from
\emph on
fig_path()
\emph default
, which is a convenience function to return the figure path for the current
chunk.
\end_layout
\begin_layout Standard
We can do whatever normal R plots can do with this hook, and we give another
example below to show how to work with animations.
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
<<rgl-animation, custom.plot=TRUE, fig.ext='png', out.width='2.5in', fig.show='animat
e', fig.num=20, interval=.4, aniopts='controls,autoplay', results='hide',
warning=FALSE>>=
\end_layout
\begin_layout Plain Layout
library(animation) # adapted from demo('rgl_animation')
\end_layout
\begin_layout Plain Layout
data(pollen)
\end_layout
\begin_layout Plain Layout
uM = matrix(c(-0.37, -0.51, -0.77, 0, -0.73, 0.67, -0.1, 0, 0.57, 0.53, -0.63, 0,
0, 0, 0, 1), 4, 4)
\end_layout
\begin_layout Plain Layout
library(rgl)
\end_layout
\begin_layout Plain Layout
open3d(userMatrix = uM, windowRect = c(0, 0, 400, 400))
\end_layout
\begin_layout Plain Layout
plot3d(pollen[, 1:3])
\end_layout
\begin_layout Plain Layout
zm = seq(1, 0.05, length = 20)
\end_layout
\begin_layout Plain Layout
par3d(zoom = 1) # change the zoom factor gradually later
\end_layout
\begin_layout Plain Layout
for (i in 1:length(zm)) {
\end_layout
\begin_layout Plain Layout
par3d(zoom = zm[i]); Sys.sleep(.05)
\end_layout
\begin_layout Plain Layout
rgl.snapshot(fig_path('png', number = i))
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
@
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
rgl Plots
\end_layout
\begin_layout Standard
With the hook
\emph on
hook_rgl()
\emph default
, we can easily save snapshots from the
\series bold
rgl
\series default
package.
We have shown an example in the main manual, and here we add some details.
The rgl hook is a good example of taking care of details by carefully using
the
\family typewriter
options
\family default
argument in the hook; for example, we cannot directly set the width and
height of rgl plots in
\emph on
rgl.snapshot()
\emph default
or
\emph on
rgl.postscript()
\emph default
, so we make use of the options
\family typewriter
fig.width
\family default
,
\family typewriter
fig.height
\family default
and
\family typewriter
dpi
\family default
to calculate the expected size of the window, then resize the current window
by
\emph on
par3d()
\emph default
, and finally save the plot.
\end_layout
\begin_layout Standard
This hook is actually built upon
\emph on
hook_plot_custom()
\emph default
-- first it saves the
\series bold
rgl
\series default
snapshot, then it calls
\emph on
hook_plot_custom()
\emph default
to write the output code.
\end_layout
\begin_layout Section
\start_of_appendix
How to Compile This Manual
\end_layout
\begin_layout Standard
This manual has a long chain of dependencies, so it may not be easy to compile.
These packages are required (all of them are free software):
\end_layout
\begin_layout Description
R Cairo, ggplot2, tikzDevice, rgl, rggobi, animation (all available on CRAN
except tikzDevice which is on R-Forge for the time being)
\end_layout
\begin_layout Description
LaTeX animate, hyperref and the tufte-handout class
\end_layout
\begin_layout Description
Other GGobi, pdfcrop
\end_layout
\end_body
\end_document