microplot (version 1.0-42)

latex.trellis: Display a table in 'latex' containing panels from R graphs in its cells.

Description

Display a table in 'latex' containing panels from R graphs in its cells. Hmisc::latex methods for "trellis", "ggplot", "graphicsList", "microplotMatrix", and "includegraphicsMatrix" objects.

Usage

# S3 method for graphicsClass
latex(  ## called by trellis, ggplot, graphicsList methods
      object,
      figPrefix=first.word(deparse(substitute(object))),
      title=figPrefix, ## subject to lazy evaluation
      ##
      ## microplot arguments
      device={
        latexcmd <- options()$latexcmd
        if (is.null(latexcmd))
          latexcmd <- "latex"
        switch(latexcmd,
               pdflatex="pdf",
               latex=,
               "postscript")
      },
      ... ## can include arguments to
      ## latex.graphicsClass,
      ## microplot,
      ## as.includegraphics,
      ## latex.includegraphicsMatrix,
      ## latex.default
      )
# S3 method for trellis
latex( ## calls latex.graphicsClass
      object=stop("trellis object is required", call. = FALSE),
      figPrefix=first.word(deparse(substitute(object))),
      title=figPrefix, ## subject to lazy evaluation
      ... ## can include arguments to
      ## latex.graphicsClass,
      ## microplot,
      ## as.includegraphics,
      ## latex.includegraphicsMatrix,
      ## latex.default
      )
# S3 method for ggplot
latex( ## calls latex.graphicsClass
      object=stop("ggplot object is required", call. = FALSE),
      figPrefix=first.word(deparse(substitute(object))),
      title=figPrefix, ## subject to lazy evaluation
      ... ## can include arguments to
      ## latex.graphicsClass,
      ## microplot,
      ## as.includegraphics,
      ## latex.includegraphicsMatrix,
      ## latex.default
      )
# S3 method for graphicsList
latex( ## calls latex.graphicsClass
      object=stop("graphicsList object is required", call. = FALSE),
      figPrefix=first.word(deparse(substitute(object))),
      title=figPrefix, ## subject to lazy evaluation
      ... ## can include arguments to
      ## latex.graphicsClass,
      ## microplot,
      ## as.includegraphics,
      ## latex.includegraphicsMatrix,
      ## latex.default
      )
# S3 method for includegraphicsMatrix
latex(
      object,
      dataobject, data.first=TRUE,
      title=first.word(deparse(substitute(object))),
      microplotMatrix=NULL,
      arraystretch=1,     ## The normal interrow space is multiplied by arraystretch,
      ##                     so changing it from its default value of 1 to 1.5 makes
      ##                     the rows 1.5 times farther apart.
      ##                     Uses the latex.default argument 'insert.top'.
      bottom.hline.raise=NULL, ## character with latex unit, for example "-10ex"
      ##        arraystretch interferes with bottom.hline.raise
      ##        Pick arraystretch first.
      bottom=if (!is.null(attr(object, "key.name")))
               attr(object, "key.name"),
      col.just.object=rep("c", ncol(object)),
      col.just.dataobject=rep("r", ncol(dataobject)),
      n.cgroup=NULL, ## generated below if cgroup is specified in ... and n.cgroup is not
      ...) ## arguments to latex.default
# S3 method for microplotMatrix
latex(object,
      title=first.word(deparse(substitute(object))),
      ...) ## all ... arguments are forwarded to both
           ## as.includegraphics and latex.includegraphicsMatrix

Arguments

object

For latex.trellis, a "trellis" object, usually a multi-panel object.

For latex.ggplot, a "ggplot" object, usually a multi-panel object.

For latex.graphicsList, a "graphicsList" object, usually a list of single panel graphics objects. All items in the list must be trellis objects or all must be ggplot objects.

For latex.microplotMatrix, a "microplotMatrix" object, the result of calling microplot on a "trellis" or "ggplot" object; a matrix of LaTeX filenames, possibly with axis.names or lab.names or key.name attributes.

For latex.includegraphicsMatrix, a "includegraphicsMatrix" object, the result of calling as.includegraphics on a "microplotMatrix" object; a matrix of LaTeX \includegraphics expressions, possibly with axis.names or lab.names or key.name attributes.

device

Function used to construct the graphics files. See microplot.

dataobject

Numeric or character matrix (or data.frame).

data.first

Logical. If TRUE, then output file will have dataobject columns first, then graphics object columns. If FALSE, then output file will have graphics object columns first, then dataobject columns.

figPrefix

See microplot.trellis. The 'latex' macro \includegraphics requires that there be no "." in the filename basename. We replace all "." in the figPrefix by "-".

title

Arguments to Hmisc::latex.

microplotMatrix

The microplotMatrix will be made an attribute of the resulting latex object.

arraystretch

The normal interrow space is multiplied by arraystretch, so changing it from its default value of 1 to 1.5 makes the rows 1.5 times farther apart. Uses the latex.default argument insert.top.

bottom.hline.raise

Character string with latex unit, for example "-10ex". arraystretch interacts with bottom.hline.raise. Pick arraystretch first.

bottom

default argument to latex.default's insert.bottom argument.

col.just.object, col.just.dataobject

Column justification. See formatDF. The default centers graph panel columns and right justifies dataobject columns because it assumes the dataobject contains formatted (hence aligned) numerical data.

n.cgroup

See latex. When cgroup is specified it always appears in .... ncgroup is an optional input here because we have enough information to generate it.

…

Arguments to microplot.trellis, microplot.ggplot, as.includegraphics, latex.includegraphicsMatrix, latex.default.

Value

The value of these latex methods is a "latex" object containing two components.

file

Pathname of the generated .tex file.

style

"graphicx", indicating that the latex \usepackage{graphicx} is required

See demo/HowToUseMicroplot.r for a tutorial. See the demos in demo/latex.r and demo/latex-ggplot.r for an elaborate example.

When one of the ... arguments is file="", the generated LaTeX code is printed to standard output. See the discussion of the file argument in latex to learn how to use this feature with Sweave.

Function latex.includegraphicsMatrix takes the output of as.includegraphics as its input and returns a "latex" object. If there is a key.name attribute, then it is forwarded to latex.default as the insert.bottom argument. The result has an attribute "includegraphicsMatrix" containing its argument object and an attribute "microplotMatrix" containing the "microplotMatrix" object from which the "includegraphicsMatrix" was constructed.

Function latex.microplotMatrix takes the output of microplot as its input and forwards it to latex.includegraphicsMatrix. All ... arguments are forwarded to latex.includegraphicsMatrix. The return value is a "latex" object.

Functions latex.trellis and latex.ggplot and latex.graphicsList take their input and forward it through latex.graphicsClass to microplot and then to latex.microplotMatrix.

The print method for "latex" objects, described in dvi, is to display the latexed file on the screen at 5.5in wide by 7in tall. The dimensions can be changed by an explicit call to the the dvi method with other dimensions, for example dvi(latex(MyTrellisObject), height.panel=11, width.panel=8.5) See an example in demo("latex", package="microplot", ask=TRUE)

The format of the screen display depends on three options described in latexSetOptions and latex.

For pdflatex normally use: latexSetOptions("pdflatex")

For latex normally use: latexSetOptions("latex")

Details

The explicit result is a "latex" object containing the name of a generated .tex file in the current directory. The file contains a latex \tabular environment holding a \table. The cells of the \table contain each of the filenames wrapped in an \includegraphics expression. To get the name of the created file, you must save the returned value from the "latex" function and display it with print.default.

The print method for "latex" objects wraps the generated file in a minimal complete latex file, runs that file through the system pdflatex or latex (depending on the value of options("latexcmd")) to create a pdf file (or dvi file, depending on the value of options("dviExtension")), and displays it on the screen. To get the name of the displayed file, you must explicitly use the dvi function on the "latex" object and save the otherwise invisible return value. If it is a pdf file it can be included with an \includegraphics expression into another .tex file for use with pdflatex. If it is a dvi file it can be converted with dvips to a .ps file and included with an \includegraphics expression into another .tex file for use with latex.

See Also

latex, microplot, as.includegraphics

Examples

# NOT RUN {
## See the examples in the help files, the demo files, and in the
## examples subdirectory.

## The example here shows how to locate the generated .tex file and the displayed .pdf file.
## The .tex file can be brought into a larger .tex file with an \include statement.
## The .pdf file can be brought into a larger .tex file with an \includegraphics statement.

# }
# NOT RUN {
## These are the settings for my machines
## Set options for Hmisc::latex
latexSetOptions()

mpgGraph <- lattice::xyplot(mpg ~ wt, group=factor(cyl), data=mtcars,
                            xlim=c(.8, 6.2), ylim=c(9,37),
                            pch=as.character(levels(factor(mtcars$cyl))), cex=2)
mpgGraph ## on your interactive device
mpgLatex <-
  latex(mpgGraph,
        height.panel=2, width.panel=3, ## inch. pick numbers that look right to you.
        height.x.axis=.37, width.y.axis=.44,  ## inch. these require trial and error.
        height.xlab=.18, width.ylab=.27,      ## inch. these require trial and error.
        rowname=NULL,    ## suppress rownames, see ?latex
        colheads=FALSE)  ## suppress colnames, see ?latex
print.default(mpgLatex)  ## file is in your working directory
mpgPdf <- dvi(mpgLatex)
print.default(mpgPdf) ## File is in a temporary directory.
                      ## If Macintosh shows "//", replace by "/" before using.
mpgPdf

# }
# NOT RUN {
## Sweave users can bring the generated files directly into their
## document.  See the discussion of the \code{file} argument in
## \code{\link[Hmisc]{latex}} to learn how to use this feature with
## Sweave.
# }