latex: Convert an S object to LaTeX, and Related Utilities

In harrelfe/Hmisc: Harrell Miscellaneous

Convert an S object to LaTeX, and Related Utilities

Description

latex converts its argument to a ‘.tex’ file appropriate for inclusion in a LaTeX2e document. latex is a generic function that calls one of latex.default, latex.function, latex.list.

latex.default does appropriate rounding and decimal alignment and produces a file containing a LaTeX tabular environment to print the matrix or data.frame x as a table.

latex.function prepares an S function for printing by issuing sed commands that are similar to those in the S.to.latex procedure in the s.to.latex package (Chambers and Hastie, 1993). latex.function can also produce verbatim output or output that works with the Sweavel LaTeX style.

latex.list calls latex recursively for each element in the argument.

latexTranslate translates particular items in character strings to LaTeX format, e.g., makes ‘⁠a^2 = a\$^2\$⁠’ for superscript within variable labels. LaTeX names of greek letters (e.g., "alpha") will have backslashes added if greek==TRUE. Math mode is inserted as needed. latexTranslate assumes that input text always has matches, e.g. [) [] (] (), and that surrounding by ‘⁠\$\$⁠’ is OK.

htmlTranslate is similar to latexTranslate but for html translation. It doesn't need math mode and assumes dollar signs are just that.

latexSN converts a vector floating point numbers to character strings using LaTeX exponents. Dollar signs to enter math mode are not added. Similarly, htmlSN converts to scientific notation in html.

latexVerbatim on an object executes the object's print method, capturing the output for a file inside a LaTeX verbatim environment.

dvi uses the system latex command to compile LaTeX code produced by latex, including any needed styles. dvi will put a ‘⁠\documentclass{report}⁠’ and ‘⁠\end{document}⁠’ wrapper around a file produced by latex. By default, the ‘⁠geometry⁠’ LaTeX package is used to omit all margins and to set the paper size to a default of 5.5in wide by 7in tall. The result of dvi is a .dvi file. To both format and screen display a non-default size, use for example print(dvi(latex(x), width=3, height=4),width=3,height=4). Note that you can use something like ‘⁠xdvi -geometry 460x650 -margins 2.25in file⁠’ without changing LaTeX defaults to emulate this.

dvips will use the system dvips command to print the .dvi file to the default system printer, or create a postscript file if file is specified.

dvigv uses the system dvips command to convert the input object to a .dvi file, and uses the system dvips command to convert it to postscript. Then the postscript file is displayed using Ghostview (assumed to be the system command gv).

There are show methods for displaying typeset LaTeX on the screen using the system xdvi command. If you show a LaTeX file created by latex without running it through dvi using show.dvi(object), the show method will run it through dvi automatically. These show methods are not S Version 4 methods so you have to use full names such as show.dvi and show.latex. Use the print methods for more automatic display of typesetting, e.g. typing latex(x) will invoke xdvi to view the typeset document.

Usage

latex(object, ...)

## Default S3 method:
latex(object,
    title=first.word(deparse(substitute(object))),
    file=paste(title, ".tex", sep=""),
    append=FALSE, label=title,
    rowlabel=title, rowlabel.just="l",
    cgroup=NULL, n.cgroup=NULL,
    rgroup=NULL, n.rgroup=NULL,
    cgroupTexCmd="bfseries",
    rgroupTexCmd="bfseries",
    rownamesTexCmd=NULL,
    colnamesTexCmd=NULL,
    cellTexCmds=NULL,
    rowname, cgroup.just=rep("c",length(n.cgroup)),
    colheads=NULL,
    extracolheads=NULL, extracolsize='scriptsize',
    dcolumn=FALSE, numeric.dollar=!dcolumn, cdot=FALSE,
    longtable=FALSE, draft.longtable=TRUE, ctable=FALSE, booktabs=FALSE,
    table.env=TRUE, here=FALSE, lines.page=40,
    caption=NULL, caption.lot=NULL, caption.loc=c('top','bottom'),
    star=FALSE,
    double.slash=FALSE,
    vbar=FALSE, collabel.just=rep("c",nc), na.blank=TRUE,
    insert.bottom=NULL, insert.bottom.width=NULL,
    insert.top=NULL,
    first.hline.double=!(booktabs | ctable),
    where='!tbp', size=NULL,
    center=c('center','centering','centerline','none'),
    landscape=FALSE,
    multicol=TRUE,
    math.row.names=FALSE, already.math.row.names=FALSE,
    math.col.names=FALSE, already.math.col.names=FALSE,
    hyperref=NULL, continued='continued',
    ...) # x is a matrix or data.frame

## S3 method for class 'function'
latex(
	object,
	title=first.word(deparse(substitute(object))),
	file=paste(title, ".tex", sep=""),
	append=FALSE,
	assignment=TRUE,  type=c('example','verbatim','Sinput'),
    width.cutoff=70, size='', ...)

## S3 method for class 'list'
latex(
           object,
           title=first.word(deparse(substitute(object))),
           file=paste(title, ".tex", sep=""),
           append=FALSE,
           label,
           caption,
           caption.lot,
           caption.loc=c('top','bottom'),
           ...)

## S3 method for class 'latex'
print(x, ...)

latexTranslate(object, inn=NULL, out=NULL, pb=FALSE, greek=FALSE, na='',
               ...)

htmlTranslate(object, inn=NULL, out=NULL, greek=FALSE, na='',
              code=htmlSpecialType(), ...)

latexSN(x)

htmlSN(x, pretty=TRUE, ...)

latexVerbatim(x, title=first.word(deparse(substitute(x))),
    file=paste(title, ".tex", sep=""),
    append=FALSE, size=NULL, hspace=NULL,
    width=.Options$width, length=.Options$length, ...)

dvi(object, ...)
## S3 method for class 'latex'
dvi(object, prlog=FALSE, nomargins=TRUE, width=5.5, height=7, ...)
## S3 method for class 'dvi'
print(x, ...)
dvips(object, ...)
## S3 method for class 'latex'
dvips(object, ...)
## S3 method for class 'dvi'
dvips(object, file, ...)
## S3 method for class 'latex'
show(object)  # or show.dvi(object) or just object
dvigv(object, ...)
## S3 method for class 'latex'
dvigv(object, ...)       # or gvdvi(dvi(object))
## S3 method for class 'dvi'
dvigv(object, ...)

Arguments

object	For latex, any S object. For dvi or dvigv, an object created by latex. For latexTranslate is a vector of character strings to translate. Any NAs are set to blank strings before conversion.
x	any object to be printed verbatim for latexVerbatim. For latexSN or htmlSN, x is a numeric vector.
title	name of file to create without the ‘⁠.tex⁠’ extension. If this option is not set, value/string of x (see above) is printed in the top left corner of the table. Set title='' to suppress this output.
file	name of the file to create. The default file name is ‘x.tex’ where x is the first word in the name of the argument for x. Set file="" to have the generated LaTeX code just printed to standard output. This is especially useful when running under Sweave in R using its ‘⁠results=tex⁠’ tag, to save having to manage many small external files. When file="", latex keeps track of LaTeX styles that are called for by creating or modifying an object latexStyles (in .GlobalTemp in R or in frame 0 in S-Plus). latexStyles is a vector containing the base names of all the unique LaTeX styles called for so far in the current session. See the end of the examples section for a way to use this object to good effect. For dvips, file is the name of an output postscript file.
append	defaults to FALSE. Set to TRUE to append output to an existing file.
label	a text string representing a symbolic label for the table for referencing in the LaTeX ‘⁠\label⁠’ and ‘⁠\ref⁠’ commands. label is only used if caption is given.
rowlabel	If x has row dimnames, rowlabel is a character string containing the column heading for the row dimnames. The default is the name of the argument for x.
rowlabel.just	If x has row dimnames, specifies the justification for printing them. Possible values are "l", "r", "c". The heading (rowlabel) itself is left justified if rowlabel.just="l", otherwise it is centered.
cgroup	a vector of character strings defining major column headings. The default is to have none.
n.cgroup	a vector containing the number of columns for which each element in cgroup is a heading. For example, specify cgroup=c("Major 1","Major 2"), n.cgroup=c(3,3) if "Major 1" is to span columns 1-3 and "Major 2" is to span columns 4-6. rowlabel does not count in the column numbers. You can omit n.cgroup if all groups have the same number of columns.
rgroup	a vector of character strings containing headings for row groups. n.rgroup must be present when rgroup is given. The first n.rgroup[1] rows are sectioned off and rgroup[1] is used as a bold heading for them. The usual row dimnames (which must be present if rgroup is) are indented. The next n.rgroup[2] rows are treated likewise, etc.
n.rgroup	integer vector giving the number of rows in each grouping. If rgroup is not specified, n.rgroup is just used to divide off blocks of rows by horizontal lines. If rgroup is given but n.rgroup is omitted, n.rgroup will default so that each row group contains the same number of rows.
cgroupTexCmd	A character string specifying a LaTeX command to be used to format column group labels. The default, "bfseries", sets the current font to ‘bold’. It is possible to supply a vector of strings so that each column group label is formatted differently. Please note that the first item of the vector is used to format the title (even if a title is not used). Currently the user needs to handle these issue. Multiple effects can be achieved by creating custom LaTeX commands; for example, "\providecommand{\redscshape}{\color{red}\scshape}" creates a LaTeX command called ‘⁠\redscshape⁠’ that formats the text in red small-caps.
rgroupTexCmd	A character string specifying a LaTeX command to be used to format row group labels. The default, "bfseries", sets the current font to ‘bold’. A vector of strings can be supplied to format each row group label differently. Normal recycling applies if the vector is shorter than n.rgroups. See also cgroupTexCmd above regarding multiple effects.
rownamesTexCmd	A character string specifying a LaTeX command to be used to format rownames. The default, NULL, applies no command. A vector of different commands can also be supplied. See also cgroupTexCmd above regarding multiple effects.
colnamesTexCmd	A character string specifying a LaTeX command to be used to format column labels. The default, NULL, applies no command. It is possible to supply a vector of strings to format each column label differently. If column groups are not used, the first item in the vector will be used to format the title. Please note that if column groups are used the first item of cgroupTexCmd and not colnamesTexCmd is used to format the title. The user needs to allow for these issues when supplying a vector of commands. See also cgroupTexCmd above regarding multiple effects.
cellTexCmds	A matrix of character strings which are LaTeX commands to be used to format each element, or cell, of the object. The matrix must have the same NROW() and NCOL() as the object. The default, NULL, applies no formats. Empty strings also apply no formats, and one way to start might be to create a matrix of empty strings with matrix(rep("", NROW(x) * NCOL(x)), nrow=NROW(x)) and then selectively change appropriate elements of the matrix. Note that you might need to set numeric.dollar=FALSE (to disable math mode) for some effects to work. See also cgroupTexCmd above regarding multiple effects.
na.blank	Set to TRUE to use blanks rather than NA for missing values. This usually looks better in latex.
insert.bottom	an optional character string to typeset at the bottom of the table. For "ctable" style tables, this is placed in an unmarked footnote.
insert.bottom.width	character string; a tex width controlling the width of the insert.bottom text. Currently only does something with using longtable=TRUE.
insert.top	a character string to insert as a heading right before beginning tabular environment. Useful for multiple sub-tables.
first.hline.double	set to FALSE to use single horizontal rules for styles other than "bookmark" or "ctable"
rowname	rownames for tabular environment. Default is rownames of matrix or data.frame. Specify rowname=NULL to suppress the use of row names.
cgroup.just	justification for labels for column groups. Defaults to "c".
colheads	a character vector of column headings if you don't want to use dimnames(object)[[2]]. Specify colheads=FALSE to suppress column headings.
extracolheads	an optional vector of extra column headings that will appear under the main headings (e.g., sample sizes). This character vector does not need to include an empty space for any rowname in effect, as this will be added automatically. You can also form subheadings by splitting character strings defining the column headings using the usual backslash n newline character.
extracolsize	size for extracolheads or for any second lines in column names; default is "scriptsize"
dcolumn	see format.df
numeric.dollar	logical, default !dcolumn. Set to TRUE to place dollar signs around numeric values when dcolumn=FALSE. This assures that latex will use minus signs rather than hyphens to indicate negative numbers. Set to FALSE when dcolumn=TRUE, as dcolumn.sty automatically uses minus signs.
math.row.names	logical, set true to place dollar signs around the row names.
already.math.row.names	set to TRUE to prevent any math mode changes to row names
math.col.names	logical, set true to place dollar signs around the column names.
already.math.col.names	set to TRUE to prevent any math mode changes to column names
hyperref	if table.env=TRUE is a character string used to generate a LaTeX hyperref enclosure
continued	a character string used to indicate pages after the first when making a long table
cdot	see format.df
longtable	Set to TRUE to use David Carlisle's LaTeX longtable style, allowing long tables to be split over multiple pages with headers repeated on each page. The "style" element is set to "longtable". The latex ‘⁠\usepackage⁠’ must reference ‘⁠[longtable]⁠’. The file ‘longtable.sty’ will need to be in a directory in your TEXINPUTS path.
draft.longtable	I forgot what this does.
ctable	set to TRUE to use Wybo Dekker's ‘⁠ctable⁠’ style from CTAN. Even though for historical reasons it is not the default, it is generally the preferred method. Thicker but not doubled ‘⁠\hline⁠’s are used to start a table when ctable is in effect.
booktabs	set booktabs=TRUE to use the ‘⁠booktabs⁠’ style of horizontal rules for better tables. In this case, double ‘⁠\hline⁠’s are not used to start a table.
table.env	Set table.env=FALSE to suppress enclosing the table in a LaTeX ‘⁠table⁠’ environment. table.env only applies when longtable=FALSE. You may not specify a caption if table.env=FALSE.
here	Set to TRUE if you are using table.env=TRUE with longtable=FALSE and you have installed David Carlisle's ‘here.sty’ LaTeX style. This will cause the LaTeX ‘⁠table⁠’ environment to be set up with option ‘⁠H⁠’ to guarantee that the table will appear exactly where you think it will in the text. The "style" element is set to "here". The latex ‘⁠\usepackage⁠’ must reference ‘⁠[here]⁠’. The file ‘here.sty’ will need to be in a directory in your TEXINPUTS path. ‘⁠here⁠’ is largely obsolete with LaTeX2e.
lines.page	Applies if longtable=TRUE. No more than lines.page lines in the body of a table will be placed on a single page. Page breaks will only occur at rgroup boundaries.
caption	a text string to use as a caption to print at the top of the first page of the table. Default is no caption.
caption.lot	a text string representing a short caption to be used in the “List of Tables”. By default, LaTeX will use caption. If you get inexplicable ‘⁠latex⁠’ errors, you may need to supply caption.lot to make the errors go away.
caption.loc	set to "bottom" to position a caption below the table instead of the default of "top".
star	apply the star option for ctables to allow a table to spread over two columns when in twocolumn mode.
double.slash	set to TRUE to output ‘⁠"\"⁠’ as ‘⁠"\\"⁠’ in LaTeX commands. Useful when you are reading the output file back into an S vector for later output.
vbar	logical. When vbar==TRUE, columns in the tabular environment are separated with vertical bar characters. When vbar==FALSE, columns are separated with white space. The default, vbar==FALSE, produces tables consistent with the style sheet for the Journal of the American Statistical Association.
collabel.just	justification for column labels.
assignment	logical. When TRUE, the default, the name of the function and the assignment arrow are printed to the file.
where	specifies placement of floats if a table environment is used. Default is "!tbp". To allow tables to appear in the middle of a page of text you might specify where="!htbp" to latex.default.
size	size of table text if a size change is needed (default is no change). For example you might specify size="small" to use LaTeX font size “small”. For latex.function is a character string that will be appended to "Sinput" such as "small".
center	default is "center" to enclose the table in a ‘⁠center⁠’ environment. Use center="centering" or "centerline" to instead use LaTeX ‘⁠centering⁠’ or centerline directives, or center="none" to use no centering. centerline can be useful when objects besides a tabular are enclosed in a single table environment. This option was implemented by Markus J�ntti [e-mail] of Abo Akademi University.
landscape	set to TRUE to enclose the table in a ‘⁠landscape⁠’ environment. When ctable is TRUE, will use the rotate argument to ctable.
type	The default uses the S alltt environment for latex.function, Set type="verbatim" to instead use the LaTeX ‘⁠verbatim⁠’ environment. Use type="Sinput" if using Sweave, especially if you have customized the Sinput environment, for example using the Sweavel style which uses the listings LaTeX package.
width.cutoff	width of function text output in columns; see deparse
...	other arguments are accepted and ignored except that latex passes arguments to format.df (e.g., col.just and other formatting options like dec, rdec, and cdec). For latexVerbatim these arguments are passed to the print function. Ignored for latexTranslate and htmlTranslate. For htmlSN, these arguments are passed to prettyNum or format.
inn, out	specify additional input and translated strings over the usual defaults
pb	If pb=TRUE, latexTranslate also translates ‘⁠[()]⁠’ to math mode using ‘⁠\left, \right⁠’.
greek	set to TRUE to have latexTranslate put names for greek letters in math mode and add backslashes. For htmlTranslate, translates greek letters to corresponding html characters, ignoring "modes".
na	single character string to translate NA values to for latexTranslate and htmlTranslate
code	set to 'unicode' to use HTML unicode characters or '&' to use the ampersand pound number format
pretty	set to FALSE to have htmlSN use format instead of prettyNum
hspace	horizontal space, e.g., extra left margin for verbatim text. Default is none. Use e.g. hspace="10ex" to add 10 extra spaces to the left of the text.
length	for S-Plus only; is the length of the output page for printing and capturing verbatim text
width, height	are the options( ) to have in effect only for when print is executed. Defaults are current options. For dvi these specify the paper width and height in inches if nomargins=TRUE, with defaults of 5.5 and 7, respectively.
prlog	set to TRUE to have dvi print, to the S-Plus session, the LaTeX .log file.
multicol	set to FALSE to not use ‘⁠\multicolumn⁠’ in header of table
nomargins	set to FALSE to use default LaTeX margins when making the .dvi file

Details

latex.default optionally outputs a LaTeX comment containing the calling statement. To output this comment, run options(omitlatexcom=FALSE) before running. The default behavior or suppressing the comment is helpful when running RMarkdown to produce pdf output using LaTeX, as this uses pandoc which is fooled into try to escape the percent comment symbol.

If running under Windows and using MikTeX, latex and yap must be in your system path, and yap is used to browse ‘.dvi’ files created by latex. You should install the ‘geometry.sty’ and ‘ctable.sty’ styles in MikTeX to make optimum use of latex().

On Mac OS X, you may have to append the ‘/usr/texbin’ directory to the system path. Thanks to Kevin Thorpe ([e-mail]) one way to set up Mac OS X is to install ‘⁠X11⁠’ and ‘⁠X11SDK⁠’ if not already installed, start ‘⁠X11⁠’ within the R GUI, and issue the command Sys.setenv( PATH=paste(Sys.getenv("PATH"),"/usr/texbin",sep=":") ). To avoid any complications of using ‘⁠X11⁠’ under MacOS, users can install the ‘⁠TeXShop⁠’ package, which will associate ‘.dvi’ files with a viewer that displays a ‘pdf’ version of the file after a hidden conversion from ‘dvi’ to ‘pdf’.

System options can be used to specify external commands to be used. Defaults are given by options(xdvicmd='xdvi') or options(xdvicmd='yap'), options(dvipscmd='dvips'), options(latexcmd='latex'). For MacOS specify options(xdvicmd='MacdviX') or if TeXShop is installed, options(xdvicmd='open').

To use ‘⁠pdflatex⁠’ rather than ‘⁠latex⁠’, set options(latexcmd='pdflatex'), options(dviExtension='pdf'), and set options('xdvicmd') to your chosen PDF previewer.

If running S-Plus and your directory for temporary files is not ‘/tmp’ (Unix/Linux) or ‘\windows\temp’ (Windows), add your own tempdir function such as tempdir <- function() "/yourmaindirectory/yoursubdirectory"

To prevent the latex file from being displayed store the result of latex in an object, e.g. w <- latex(object, file='foo.tex').

Value

latex and dvi return a list of class latex or dvi containing character string elements file and style. file contains the name of the generated file, and style is a vector (possibly empty) of styles to be included using the LaTeX2e ‘⁠\usepackage⁠’ command.

latexTranslate returns a vector of character strings

Side Effects

creates various system files and runs various Linux/UNIX system commands which are assumed to be in the system path.

Author(s)

Frank E. Harrell, Jr.,
Department of Biostatistics,
Vanderbilt University,
[e-mail]

Richard M. Heiberger,
Department of Statistics,
Temple University, Philadelphia, PA.
[e-mail]

David R. Whiting,
School of Clinical Medical Sciences (Diabetes),
University of Newcastle upon Tyne, UK.
[e-mail]

See Also

html, format.df, texi2dvi

Examples

x <- matrix(1:6, nrow=2, dimnames=list(c('a','b'),c('c','d','this that')))
## Not run: 
latex(x)   # creates x.tex in working directory
# The result of the above command is an object of class "latex"
# which here is automatically printed by the latex print method.
# The latex print method prepends and appends latex headers and
# calls the latex program in the PATH.  If the latex program is
# not in the PATH, you will get error messages from the operating
# system.

w <- latex(x, file='/tmp/my.tex')
# Does not call the latex program as the print method was not invoked
print.default(w)
# Shows the contents of the w variable without attempting to latex it.

d <- dvi(w)  # compile LaTeX document, make .dvi
             # latex assumed to be in path
d            # or show(d) : run xdvi (assumed in path) to display
w            # or show(w) : run dvi then xdvi
dvips(d)     # run dvips to print document
dvips(w)     # run dvi then dvips
library(tools)
texi2dvi('/tmp/my.tex')   # compile and produce pdf file in working dir.

## End(Not run)
latex(x, file="")   # just write out LaTeX code to screen

## Not run: 
# Use paragraph formatting to wrap text to 3 in. wide in a column
d <- data.frame(x=1:2,
                y=c(paste("a",
                    paste(rep("very",30),collapse=" "),"long string"),
                "a short string"))
latex(d, file="", col.just=c("l", "p{3in}"), table.env=FALSE)

## End(Not run)

## Not run: 
# After running latex( ) multiple times with different special styles in
# effect, make a file that will call for the needed LaTeX packages when
# latex is run (especially when using Sweave with R)
if(exists(latexStyles))
  cat(paste('\usepackage{',latexStyles,'}',sep=''),
      file='stylesused.tex', sep='\n')
# Then in the latex job have something like:
# \documentclass{article}
# \input{stylesused}
# \begin{document}
# ...

## End(Not run)

harrelfe/Hmisc documentation built on Nov. 21, 2024, 3:47 p.m.