latexTable: Create a LaTeX table from a matrix.
In jbullock35/Bullock: Tools for table-making and miscellaneous helper utilities

latexTable

R Documentation

Create a LaTeX table from a matrix.

Description

latexTable() takes a single matrix or tibble, mat. By default, it returns a LaTeX macro that creates a well-formatted LaTeX table.

Usage

latexTable(
  mat,
  SE_table = TRUE,
  headerFooter = TRUE,
  commandName = "myTable",
  callCommand = TRUE,
  label = commandName,
  floatPlacement = "p",
  landscape = if (SE_table) ncol(mat)/2 >= 6 else ncol(mat) >= 6,
  starredFloat = FALSE,
  horizOffset = "-0in",
  rowNames = rownames(mat),
  footerRows = lt_footer(),
  colNames = lt_colNames_default(),
  colNameExpand = FALSE,
  extraRowHeight = if (SE_table) "2pt" else "4pt",
  spacerColumns = lt_spacerColumns_default(),
  spacerColumnsWidth = ".67em",
  spacerRows = NULL,
  spacerRowsHeight = ".15in",
  tabColSep = "2.75pt",
  spaceBetweenColNameRows = "-.025in",
  columnTierSeparator = "  ",
  printCaption = TRUE,
  caption = paste0(label, " caption goes here."),
  captionMargins = NULL,
  formatNumbers = TRUE,
  decimalPlaces = 2,
  SE_fontSizeString = "\\fontsize{10.3bp}{10.3bp}\\selectfont",
  NA_text = "",
  clipboard = FALSE
)

Arguments

`mat`	Matrix or tibble of numbers to be displayed in a LaTeX table.
`SE_table`	Logical variable that indicates whether `mat` contains pairs (or "tiers") of columns, with the first column in each pair containing estimates, and the second column containing standard errors. Defaults to `TRUE`. If `TRUE`, the even-numbered columns of `mat` will be rendered in smaller type than the odd-numbered columns. That is, the standard errors will be rendered in smaller type than their corresponding estimates. This default type sizing can be overridden by the `SE_fontSizeString` argument.
`headerFooter`	Logical variable. If `TRUE`, which is the default, the output will be (or at least include) a LaTeX macro that generates a table. For example, you will be able to produce a table simply by calling `\myTable{p}` or `\myTable{h}` in your master LaTeX document. \indent If `headerFooter` is `FALSE`, the only output of the function will be LaTeX code for "data rows"—one row for each row of `mat`.
`commandName`	A string. It is the name of the macro that produces the LaTeX table (if `headerFooter` is `TRUE`). By default, it is "myTable"; you can change it to something more descriptive, e.g., "mainEstimates".
`callCommand`	Logical variable. Should the last line of the `latexTable` object be a call to the macro that creates the table? If `callCommand` is `TRUE`, which is the default, sourcing a file that contains `latexTable` output—that is, by using `\input` or `\include` in your master LaTeX document—will produce a table when that master LaTeX document is rendered. If `callCommand` is `FALSE`, sourcing the file will make the macro available in your LaTeX document, but it won't call the macro. (You will need to call the macro yourself by adding a line like `\myTable{p}` to your LaTeX document.)
`label`	A string. Specifies the LaTeX label for a table. It is not printed anywhere in the table, but references to the figure in your LaTeX document (for example, references created by `\ref` or `\autoref`) must include the label name. For simplicity, the default `label` is the same as the `commandName` argument.
`floatPlacement`	Character vector of length\NB1. Acceptable values are `p` (the default, which places each table on its own page), `h, H, t, b,` and `!`. See the LaTeX wikibook for more on float placement in LaTeX.
`landscape`	Logical variable. Determines whether the table is printed in landscape or in portrait mode. Affects the output only if if `headerFooter == TRUE` and `callCommand == TRUE`.
`starredFloat`	Logical variable that indicates whether the LaTeX table should be specified with `table*` instead of `table`. The default is FALSE, but you may want to set it to TRUE if you want you are using a multi-column page layout in LaTeX and want the table to cross both columns.
`horizOffset`	A string that specifies a LaTeX length, e.g., ".25in". When the LaTeX code produced by `latexTable` is rendered, the table will be moved to the right by this length (or to the left if the length is negative, e.g., "-.25in").
`rowNames`	Character vector of labels for the rows in `mat`. The labels will be printed to the left of each row in `mat`. `rowNames` can be `NULL`.
`footerRows`	List, object that can be coerced to a list, or a function that creates a list. Each element in the list is a character vector that specifies entries for a row of the footer, or a function that creates such a character vector. The default is \linkIntlt_footer, which typically provides a "Number of observations" row. If a model is of class "lm," it will also provide an R² and "Std. error of regression" row. \indent The first entry in each `footerRows` list-element should be the row name for the corresponding footer row (e.g., '$F$', '$R^2$'). \indent See the examples for various ways to specify the `footerRows` argument.
`colNames`	List, or object that can be coerced to a list, of column headings. Typically, each element in the list is a character vector, and the elements of the character vector specify the names of the table's columns. \indent If `SE_table` is `TRUE` (the default), each column name will appear over a pair of columns. In this case, each element in the `colNames` list should contain `ncol(mat)/2` entries. \indent To specify multi-line column labels, use a list with multiple elements. The entries in the first list element will then appear in the top row of the column label, the entries in the second list element will appear in the next row of the column label, and so\NBon. \indent By default, column names will be taken from `colnames(mat)`. If `colnames(mat)` is `NULL`, columns will be numbered "(1)", "(2)", etc. See \linkIntlt_colNames_default for more information.
`colNameExpand`	Logical variable. By default, an entry of '' in a `colNames` list element—that is, an empty entry—indicates that a column should have no column heading. But if `colNameExpand` is `TRUE` and a text entry in a `colNames` list element is followed by one or more '' entries, the column name specified by the text entry will bridge the columns that have '' entries. \indent `colNameExpand` and `spacerColumns` do not play well together. If you run `latexTable` with `colNameExpand == TRUE` and a non-NULL `spacerColumns` argument, you will get LaTeX output, but you will probably need to edit the "\multicolumn" and "\cmidrule" commands in the output so that LaTeX can render the output.
`extraRowHeight`	A string that specifies a length that LaTeX recognizes, e.g., '2pt' or '.25in'. The `extrarowheight` length in LaTeX will be set to `extraRowHeight`. In practice, this means that the vertical space between every row will be increased by `extraRowHeight`. This argument has no effect if `headerFooter` is `FALSE`.
`spacerColumns`	A vector of integers. Specifies columns in `mat` after which to insert columns that contain no entries. These "spacer columns" are used to insert horizontal space into the typeset table. By default, spacerColumns are specified by a helper function, `spacerColumns_default()`: If `SE_table` is `FALSE`, there is a spacer column between every column in `mat`. If `SE_table` is `TRUE`, there is a spacer column after every even-numbered column in `mat`, except for the last column. If `rowNames` is not `NULL`, a spacer column is inserted between the table's row names and the first column of data. \indent To add a spacerColumn between the rownames and the first data column, make 0 one of the values in spacerColumns. \indent `colNameExpand` and `spacerColumns` do not play well together. If you run `latexTable` with `colNameExpand == TRUE` and a non-NULL `spacerColumns` argument, you will get LaTeX output, but you will probably need to edit the "\multicolumn" and "\cmidrule" commands in the output so that LaTeX can render the output. \indent See the end of the Building better tables in less time vignette for a technical note on `spacerColumns` and column spacing in LaTeX.
`spacerColumnsWidth`	Either a single string of a recognizable LaTeX length (e.g., '.5em') or a character vector indicating the width of each spacer column. Has no effect unless `headerFooter` is `TRUE`.
`spacerRows`	A vector of integers. After each row in `mat` whose number is in `spacerRows`, a vertical space of `spacerRowsHeight` will be printed. For example, if `spacerRows == c(2, 4)`, a vertical space will be added after rows 2 and 4 of `mat`.
`spacerRowsHeight`	A string that specifies a recognizable LaTeX length, e.g., ".15in".
`tabColSep`	Character vector indicating a length that LaTeX recognizes, e.g., ".25in". The `tabcolsep` value in LaTeX will be set to this value if `headerFooter` is `TRUE`. If `SE_table` is `TRUE`, `tabColSep` will be the default distance between the estimate and the SE column in each column pair, and it will be half of the distance between column pairs. If `SE_table` is FALSE, `tabColSep` will simply be half of the default distance between columns. These distances between columns can be increased by the `spacerColumns` argument.
`spaceBetweenColNameRows`	String specifying a LaTeX length, e.g., "-.025in" (the default). When column names are to be split across multiple rows, a vertical space of this length will be inserted between the rows.
`columnTierSeparator`	A string. In the LaTeX code generated by `latexTable`, all columns are separated from each other by " & ". Column tiers – that is, pairs of columns giving the estimate and the SE for a particular coefficient – are further separated by `columnTierSeparator`, which defaults to two spaces (' '). This option affects only the LaTeX code produced by `latexTable`; it exists to make the LaTeX code more readable. It does not affect the typeset (e.g., PDF) version of the table.
`printCaption`	Logical variable.
`caption`	A string. It can include LaTeX commands, e.g., "\\textitResults from a minimal specification." It can also include references to other labeled parts of your LaTeX document, e.g., "\\autorefSomeFigure". See the examples.
`captionMargins`	A vector of two strings that specify the margins of the caption. The strings should be LaTeX lengths, e.g., ".25in" or ".67em". By default, `captionMargins` is `NULL`.
`formatNumbers`	Logical variable, `TRUE` by default. Pretty-print the entries in `mat`\NBby: Rounding all entries to the `decimalPlaces` digit. Padding out entries with trailing zeroes. For example, `3` will become `3.00` if `decimalPlaces == 2`. Removing leading zeroes. For example, `0.12` will become `.12`. If `formatNumbers` is `FALSE`, formatting of entries in `mat` will be handled by `print.default()`.
`decimalPlaces`	Integer. If `formatNumbers` is `TRUE`, table entries will be shown to this decimal place. For example, if `decimalPlaces==2`, both "3.0035" and "3" will become "3.00." \indent If `formatNumbers` is `FALSE`, entries will not be adjusted, but `decimalPlaces` will still be used to determine the widths of columns and some aspects of column spacing. For example, even if `formatNumbers` is `FALSE`, data columns will be wider when `decimalPlaces` is `10` than when it is\NB`2`.
`SE_fontSizeString`	A string. Indicates how standard errors are to be formatted when `SE_table` is `TRUE`. Defaults to `\\fontsize{10.3bp}{10.3bp}\\selectfont`, which renders standard errors in slightly smaller type than the corresponding estimates.
`NA_text`	A string. `NA` and `NaN` entries in `mat` will be replaced by the string.
`clipboard`	Logical variable. Copy entire output to clipboard. Useful if you want to paste the output directly into a `.tex` file. Works only on Windows.

Value

An object of classes latexTable and character. The returned object is a vector of strings of LaTeX code; each string is a line in a LaTeX macro that can create a table.
\indent There is one small exception. If callCommand is TRUE, the last line is not part of the macro; instead, it calls the macro, thereby telling LaTeX to display the table. For example, if commandName and label are myTable, and if callCommand is TRUE, the last line of the returned object is \mytable{p}.

Note

Required LaTeX packages. The LaTeX code produced by the latexTable makes use of capabilities provided by the booktabs, caption, float, numprint, and ragged2e LaTeX packages—and, for landscaped tables, the pdflscape\NBpackage. If you haven't installed those LaTeX packages, you won't be able to render the tables produced by latexTable.
\indent The LaTeX code produced by latexTable also makes use of capabilities provided by the array and afterpage LaTeX packages—but these packages are included in every LaTeX distribution.

Changes from pre-release versions:

The names of some arguments have changed slightly since the pre-release versions of this function. They have been changed to enforce consistency: camelCase is used for all arguments, and every acronym is followed by an underscore (_) character. We thus have SE_table instead of SEtable, tabColSep instead of tabcolsep, and so\NBon.
The hspace argument has been renamed to horizOffset.
Some default arguments have changed. In particular, the default spacerColumns argument is no longer NULL. Instead, the default is to insert spacer columns in appropriate places. See documentation of the spacerColumns argument for details.

Examples

data(iris)
lm1 <- lm(Sepal.Length ~ Petal.Length,               data = iris)
lm2 <- lm(Sepal.Length ~ Petal.Length + Petal.Width, data = iris)
lm3 <- lm(Sepal.Length ~ Petal.Length * Petal.Width, data = iris)
rT1 <- regTable(list(lm1, lm2, lm3))
latexTable(rT1)
latexTable(rT1, SE_table = FALSE, colNames = lt_colNumbers())
lt2 <- latexTable(
  mat      = rT1, 
  colNames = list(qw("model model model"), qw("1 2 3")))
## Not run: 
lt3 <- latexTable(
  mat         = rT1, 
  colNames    = lt_colNumbers(),
  rowNames    = c(
    "Intercept", 
    "Petal length", 
    "Petal width", 
    "Petal length $\\times$ petal width"),
  footerRows  = list(lt_nobsRow(), lt_rSquaredRow()),
  commandName = 'mainEstimates',
  caption     = "Each entry is an estimate or a standard error from a separate OLS regression.")
lt4 <- update(
  lt3,
  commandName = 'myEstimates',  # change name of LaTeX macro
  spacerRows  = 1,              # add vertical space after intercept row
  footerRows  = list(
    c("My first footer row",  "a",     "b",     "c"),
    c("My second footer row", "Lorem", "ipsum", "dolor")
  ))

## End(Not run)

# You can pass a previously created list to the "footerRows" argument. To
# store functions in that list, use alist():
footerList <- alist(lt_rSquaredRow, lt_SER_row)
latexTable(rT1, footerRows = footerList)

jbullock35/Bullock documentation built on April 1, 2022, 6:21 p.m.