latex {Hmisc} | R Documentation

## 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.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. Math mode is inserted as needed. `latexTranslate` assumes that input text always has matches, e.g. `[) [] (] ()`, and that surrounding by `$$` is OK.

`latexSN` converts a vector floating point numbers to character strings using LaTeX exponents. Dollar signs to enter math mode are not added.

`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, title=first.word(deparse(substitute(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,
        rowname, cgroup.just=rep("c",length(n.cgroup)),
        colheads=dimnames(cx)[[2]],
        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'),
        double.slash=FALSE,
        vbar=FALSE, collabel.just=rep("c",nc), na.blank=TRUE,
        insert.bottom=NULL, first.hline.double=!(booktabs|ctable),
        where='!tbp', size=NULL,
        center=c('center','centering','none'),
        landscape=FALSE,
        multicol=TRUE,
        ...) # 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'), ...)

    ## 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, ...)

    latexSN(x)

    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.
`x` | any object to be `print`ed verbatim for `latexVerbatim`. For `latexSN` `x` is a numeric vector.
`title` | name of file to create without the `.tex` extension.
`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.
`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.
`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.
`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=NULL` 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` |
`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.
`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"`.
`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".
`center` | default is `"center"` to enclose the table in a `center` environment. Use `center="centering"` to instead use a LaTeX `centering` directive, or `center="none"` to use no centering. This option was implemented by Markus Jäntti markus.jantti@iki.fi 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 `Example` environment for `latex.function`, assuming you have installed `S.sty` in a location that the system latex command automatically accesses. Set `type="verbatim"` to instead use the LaTeX `verbatim` environment.
`...` | other arguments are accepted and ignored except that `latex` passes arguments to `format.df`. For `latexVerbatim` these arguments are passed to the `print` function. Ignored for `latexTranslate`.
`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`.
`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

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` and `ctable` styles in MikTeX to make optimum use of `latex()`.

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"`

### 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,
`f.harrell@vanderbilt.edu`

Richard M. Heiberger,
Department of Statistics,
Temple University, Philadelphia, PA.
`rmh@astro.ocis.temple.edu`

### See Also

`html`, `format.df`

### Examples

    ## Not run:
    x <- matrix(1:6, nrow=2, dimnames=list(c('a','b'),c('c','d','enLine 2')))
    latex(x)   # creates x.tex in working directory
    w <- latex(x, file='/tmp/my.tex')
    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
    latex(x, file="")   # just write out LaTeX code to screen

    # 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)

[Package Contents]