as.includegraphics: Convert a filename into a complete 'LaTeX' '\includegraphics'...

In microplot: Microplots (Sparklines) in 'LaTeX', 'Word', 'HTML', 'Excel'

Convert a filename into a complete 'LaTeX' \includegraphics expression for use with 'LaTeX' \includegraphics macro in the graphicx package. This is used for pdf and png files with the system pdflatex command. This is used for ps files with the system latex command.

Description

Convert a filename into a complete 'LaTeX' \includegraphics expression for use with 'LaTeX' \includegraphics macro in the graphicx package. This is used for pdf and png files with the system pdflatex command. This is used for ps files with the system latex command. The argument wd is included in the pathname in the generated expression. The \includegraphics macro is generated with the height and optional width specified by the height.includegraphics and width.includegraphics arguments; the default NULL means use the values in the graphics (pdf, png, ps) files. If either is specified, the other should be left as NULL to retain the original aspect ratio. ## An optional raise value is available for vertical alignment. An optional trim argument is available to remove excess margins from the image. See the Details section for use of the trim argument to trim panels in an externally produced graphics file.

Usage

as.includegraphics(object, ...)

## Default S3 method:
as.includegraphics(object,
           height.includegraphics=NULL, ## LaTeX measurement (character)
           width.includegraphics=NULL, ## retains original aspect ratio,
           ##                             LaTeX measurement (character)
           scale=NULL, ## number
           raise=NULL, ## LaTeX measurement (character)
           tabularinclude=TRUE,
           hspace.left=NULL,  ## LaTeX measurement (character)
           hspace.right=NULL, ## LaTeX measurement (character)
           wd=getwd(), ## working directory.  No embedded spaces in directory name.
           viewport=NULL, ## if specified, then left bottom right top (character)
           ## used for pdf png jpeg
           ## See MediaBox in pdf file.
           ## Ask operating system for png or jpg file.
           bb=NULL, ## if specified, then left bottom right top (character)
           ## used for bmp tiff ps, ask operating system for values
           trim=NULL, ## for example, "0 0 0 0" left bottom right top (character)
           x.axis.includegraphics=TRUE, ## logical or a list of arguments
           ##                              to latex \includegraphics[here]{}
           y.axis.includegraphics=TRUE, ## logical or a list of arguments
           xlab.includegraphics=FALSE,  ## logical or a list of arguments
           ylab.includegraphics=FALSE,  ## logical or a list of arguments
           key.includegraphics=!is.null(attr(object, "key.name")),
           ##                           ## logical or a list of arguments
           as.attr=FALSE, ## logical
           label.x.axis="", ## empty, nchar=0
           label.y.axis=" ", ## one space, nchar=1
           columnKey=NULL, ## see ?microplotAttrDisplay
           ...)

## S3 method for class 'microplotMatrix'
as.includegraphics(object, ...) ## principal usage.  Calls default.

## S3 method for class 'includegraphicsMatrix'
as.includegraphics(object, ...) ## returns object

## S3 method for class 'trellis'
as.includegraphics(object, ...) ## generates an informative error message.

## S3 method for class 'ggplot'
as.includegraphics(object, ...) ## generates an informative error message.

## S3 method for class 'graphicsList'
as.includegraphics(object, ...) ## generates an informative error message.

Arguments

object	A "microplotMatrix", that is a character vector or matrix of filenames for graphics files. The argument may include attributes axis.names, lab.names, and key.name for graphics files containing the "x.axis", "y.axis", "xlab", "ylab", and "key" (legend) panels.
scale	Scale factor (number) applied to figure. If either height.includegraphics or width.includegraphics is specified, then scale is ignored.
height.includegraphics, width.includegraphics	Character vector containing a LaTeX distance (by default NULL). Specifying at most one of these retains the original aspect ratio. Specifying a value for both might distort the figure by changing the aspect ratio. Specifying trim on height of a panel requires a new height to be specified to retain the aspect ratio. Specifying trim on width of a panel requires a new width to be specified to retain the aspect ratio. See demo("latex") and demo("latex-ggplot") for an example.
wd	The directory in which the files reside. The default is the full path to the current working directory that R is using. The full path is necessary when using the Hmisc::print.latex and related functions because they run the operating system's latex or pdflatex command in a temporary directory. The relative path to the current directory (wd=".") is sufficient if the file will be brought into a larger tex file with the LaTeX \input macro. Should the working directory have an embedded blank anywhere in its pathname, then as.includegraphics will generate an informative error. This is to protect you from a less-informative error that the system 'latex' command would otherwise generate. The recommended repair is to setwd() to a directory whose path has no embedded blanks anywhere. A workaround is to use wd="." in the latex call. Automatic printing with Hmisc::print.latex will not work. \input{} of the generated .tex file into your larger .tex will work. Moving the generated .tex file in the temporary directory to your working directory will work.
raise	Character vector containing a LaTeX distance (by default NULL). This value may be negative. Use it if the default vertical alignment of the graphs in the table is not satisfactory. Usually a better approach would be to use the arraystretch argument to latex.trellis.
tabularinclude	Logical. When TRUE place the generated \includegraphics{} statements inside a tabular environment. This makes the center of the included graphic align with the text on the same line of the tabular environment.
hspace.left, hspace.right	Character vector containing a LaTeX distance (by default NULL). This value may be negative. Use it if the default distance on the left or right between columns of graphs in the table is not satisfactory.
viewport	Size in pixels of the image file. This is the MediaBox in a pdf file. It is the number reported by the operating system for a png file. The viewport is optional. When specified it must be a character string containing four numbers in order: left, bottom, right, top.
bb	Bounding Box: Size in pixels of the image file. It is the number reported by the operating system for a ps file. When specified it must be a character string containing four numbers in order: left, bottom, right, top.
trim	Size in pixels to be trimmed. It must be a character string containing four numbers in order: left, bottom, right, top. See the manual for the LaTeX package graphicx for details. When trim is used, either height.includegraphics or width.includegraphics will also need to be changed. See demo("latex") and demo("latex-ggplot") for an example. See the Details section for additional use of the trim argument.
x.axis.includegraphics, y.axis.includegraphics	logical, or list of arguments to nested calls to as.includegraphics.
xlab.includegraphics, ylab.includegraphics, key.includegraphics	logical, or list of arguments to nested calls to as.includegraphics.
as.attr	Logical. When TRUE the attributes in the "microplotMatrix" argument become attributes in the "includegraphicsMatrix" result. When FALSE, the label.x.axis, label.y.axis, and columnKey arguments are passed through to microplotAttrDisplay.
label.x.axis, label.y.axis	Labels that will used by microplotAttrDisplay in the column name of the y.axis and the y.axis position for the x.axis in the 'latex' display of the graphic.
columnKey	If as.attr is FALSE and the key in attr(object, "key.name") is non-null, then microplotAttrDisplay will place its key.name as a new last value in the specified columns. The column numbering is with respect to the input object, before the y.axis or ylab are evaluated.
...	Other arguments currently ignored.

Details

We recommend that the aspect ratio be controlled by the 'R' functions that generated the figure. as.includegraphics will use the height and width values that are encoded in the pdf, png, ps files. If you need to change the size of the image we recommend that at most one of height.includegraphics and width.includegraphics be used in as.includegraphics. Using both will change the aspect ratio and consequently stretch the figure. The trim argument is used to remove excess margins from the figure; when trim is specified for height or width, the height.includegraphics or width.includegraphics will also need to be specified to retain the aspect ratio. See demo("latex") and demo("latex-ggplot") for an example.

Either the viewport (for pdf or png files) or bb (for ps files) should be specified, not both.

The trim argument can be used to take apart an externally produced graphics file and use subsets of its area as components in a 'LaTeX' table. See the files examples/irisSweaveTakeApart.Rtex and examples/irisSweaveTakeApart-Distributed.pdf for an example.

Value

A "includegraphicsMatrix" object, a vector or matrix of 'LaTeX' expressions with the 'LaTeX' macro \includegraphics for each of the input filenames. If the input argument has axis.names or lab.names or key.name attributes, then the value will also have those attributes, enclosed in \includegraphics statements. The arguments allow different \includegraphics options for the panels, the x.axis, the y.axis, xlab, ylab, and the key (legend). The location of the files listed in the input argument attributes depends on the value of the as.attr argument. When as.attr is TRUE the object attributes will become result attributes. When as.attr is FALSE, see the microplotAttrDisplay for details.

Author(s)

Richard M. Heiberger <[e-mail]>

See Also

latex.trellis, microplot, latex

Examples

as.includegraphics("abc.pdf")
## [1] "\setlength{\tabcolsep}{0pt}\begin{tabular}{c}
##      \includegraphics{/Users/rmh/Rwd/abc.def}\end{tabular}"
## attr(,"class")
## [1] "includegraphicsMatrix" "character"
## This form, with the full pathname, is required when the Hmisc::print.latex
## and related functions are used for automatic display of
## the current .tex file on screen.

as.includegraphics("abc.pdf", wd=".")
## [1] "\setlength{\tabcolsep}{0pt}\begin{tabular}{c}
##      \includegraphics{./abc.pdf}\end{tabular}"
## attr(,"class")
## [1] "includegraphicsMatrix" "character"
## This form, with the relative path, is optional when the .tex file will be
## embedded into a larger file, and will not be automatically displayed on screen.


## Please see the package documentation ?microplot for a simple example in context.

## Please see the demos for more interesting examples.
## demo(package="microplot")

microplot documentation built on March 18, 2022, 7:56 p.m.