microplot {microplot}

Take a trellis or ggplot object, or graphicsList object (list of trellis or ggplot objects), and generate a set of graphics files, one per panel of a multi-panel display.

Description

Take a trellis or ggplot object, or graphicsList object (list of trellis or ggplot objects), and generate a set of graphics files, one per panel of a multi-panel display. Additional files are generated for the axes, the axis labels, and the key.

This help file documents the microplot function. See microplot-package for information on the entire microplot package.

Usage

microplot(object, ...)

## complete for an array of lattice panels
## S3 method for class 'trellis'
microplot(
          object=stop("trellis object is required", call. = FALSE),
          ## object must have class "trellis"
          figPrefix=first.word(deparse(substitute(object))),
          vectorgraph.colname=figPrefix,
          device=c("pdf","postscript","ps","png"),
          res=600, type=getOption("bitmapType"), ## used by png
          height.panel=1, width.panel=1, ## numeric in inches
          collapse=layoutCollapse, ## Zero out unwanted
                                   ## layout.heights and layout.widths.
                                   ## See below for example.
          height.x.axis=height.panel[1],
          axis.line=list(col="black"),
          xaxis.line=axis.line,
          par.settings.x.axis=
            list(layout.heights=list(panel=0, axis.bottom=1,
                                     axis.xlab.padding=0, xlab=0),
                 axis.line=xaxis.line),
          width.y.axis=width.panel[1],
          yaxis.line=axis.line,
          par.settings.y.axis=
            list(layout.widths=list(ylab=0, ylab.axis.padding=0,
                                    axis.left=1, panel=0),
                 axis.line=yaxis.line),
          height.xlab=height.panel[1],
          par.settings.xlab=
            list(layout.heights=list(panel=0, axis.bottom=0,
                                     axis.xlab.padding=0, xlab=1),
                 axis.line=list(col="transparent")),
          width.ylab=width.panel[1],
          par.settings.ylab=
            list(layout.widths=list(ylab=1, ylab.axis.padding=0,
                                    axis.left=0, panel=0),
                 axis.line=list(col="transparent")),
          key=FALSE,    ## FALSE or a list of arguments defining a key
          height.key=height.panel[1], width.key=width.panel[1],
          ...)  ## needed to match generic.  ignored in the trellis method


## S3 method for class 'ggplot'
microplot(object, ## object has class "ggplot"
           collapse=theme_collapse(), ## theme_collapse(...) ?
           figPrefix=first.word(deparse(substitute(object))),
           vectorgraph.colname=figPrefix,
           height.panel=1, ## inch
           width.panel=1,  ## inch
           height.x.axis=height.panel,
           width.y.axis=width.panel,
           height.xlab=height.panel,
           width.ylab=width.panel,
           height.key=height.panel,
           width.key=width.panel,
           tick.text.size=7,
           key=FALSE,  ## FALSE, or a ggplot object which is a valid key
           device=c("pdf","postscript","ps","png"),
           res=600, type=getOption("bitmapType"), ## used by png
            ...)

## S3 method for class 'graphicsList'
microplot(object, ## an array of identically structured,
           ## single-panel, graphics objects (trellis or ggplot)
           ## with dim and dimnames
           figPrefix=first.word(deparse(substitute(object))),
           device=c("pdf","postscript","ps","png"),
           res=600, type=getOption("bitmapType"), ## used by png
           height.panel=1, width.panel=1, ## numeric in inches
           key=FALSE,  ## FALSE, or a trellis or ggplot object which is a valid key
           height.key=height.panel, width.key=width.panel,
           ## valid arguments for microplot.trellis or microplot.ggplot
           ...)

Arguments

object

"trellis", or "ggplot", or a graphicsList object of either all similarly constructed "trellis" objects of all similarly constructed ggplot objects.

collapse

Function that zeros out unwanted layout.heights and layout.widths space for "trellis" objects (see layoutCollapse), or that specifies a "theme" for ggplot objects (see theme_collapse).

figPrefix

Character string used as prefix for the generated files. The 'latex' macro \includegraphics requires that there be no "." in the filename basename. We replace all "." in the figPrefix by "-".

vectorgraph.colname

Character string used as column name when a vector of filenames is converted to a column matrix of filenames.

height.panel, width.panel

Height and width in inches of the generated graphics files.

height.x.axis, width.y.axis

Dimensions for axis graphics files—usually smaller than for panel contents.

height.xlab, width.ylab

Dimensions for graphics files containing axis labels—usually smaller than for panel contents.

par.settings.x.axis, par.settings.y.axis, par.settings.xlab, par.settings.ylab

"trellis" only: par.settings for axis and xlab files.

axis.line, xaxis.line, yaxis.line

"trellis" only: the usual lwd, col, cex and such that could be defined in the scales argument for xyplot.

key

Logical or list (for lattice) or ggplot object (for ggplot). If logical and FALSE there is no key (legend). If a list for microplot.trellis, it must be defined as described in xyplot for "trellis" objects. If a "ggplot" object for microplot.ggplot it must be a valid ggplot object and will be displayed in the location appropriate for a legend.

height.key, width.key

Height and width in inches of key graphics file. Defaults to same height and width as the panels.

device

Function used to construct the graphics files.

For latex with (options("latexcmd")=="pdflatex") use "pdf" (the default for pdflatex).

For latex with (options("latexcmd")=="latex") use "postscript" (the default for latex). "ps" is equivalent to "postscript".

For MSWord use "png". png defaults to res=600, type=getOption("bitmapType").

res, type

res is nominal resolution in ppi. type is either operating system-specific or "cairo". See png and cairo.

tick.text.size

Text size of the tick labels in the x and y axes (microplot.ggplot).

...

Arguments to panel function, i.e., cex and such for lattice. Similar arguments for ggplot. Currently ignored for the microplot.ggplot function.

Value

Matrix of filenames with same dim and dimnames as the argument object. The result has class "microplotMatrix". There may be one or more attributes.

axis.names

contains filenames for the x and y axes.

lab.names

contains filenames for the xlab and ylab.

key.name

contains the filename for key (legend).

Author(s)

Richard M. Heiberger <[e-mail]>

See Also

latex.trellis, as.includegraphics, latex, msWord

Examples

## See demos