latex                 package:Hmisc                 R Documentation

_C_o_n_v_e_r_t _a_n _S _o_b_j_e_c_t _t_o _L_a_T_e_X, _a_n_d _R_e_l_a_t_e_d _U_t_i_l_i_t_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     '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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

  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 Jntti
          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 

_D_e_t_a_i_l_s:

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

_V_a_l_u_e:

     '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

_S_i_d_e _E_f_f_e_c_t_s:

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

_A_u_t_h_o_r(_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'

_S_e_e _A_l_s_o:

     'html', 'format.df'

_E_x_a_m_p_l_e_s:

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

