R: Interface to Tabular Function

tabulr {Hmisc} | R Documentation

## Interface to Tabular Function

### Description

`tabulr` is a front-end to the `tables` package's `tabular` function so that the user can take advantage of variable annotations used by the `Hmisc` package, particular those created by the `label`, `units`, and `upData` functions. When a variable appears in a `tabular` function, the variable `x` is found in the `data` argument or in the parent environment, and the `labelLatex` function is used to create a LaTeX label. By default any units of measurement are right justified in the current LaTeX tabular field using `hfill`; use `nofill` to list variables for which `units` are not right-justified with `hfill`. Once the label is constructed, the variable name is preceeded by `Heading("LaTeX label")*x` in the formula before it is passed to `tabular`. `nolabel` can be used to specify variables for which labels are ignored.

`tabulr` also replaces `trio` with `table_trio`, `N` with `table_N`, and `freq` with `table_freq` in the formula.

`table_trio` is a function that takes a numeric vector and computes the three quartiles and optionally the mean and standard deviation, and outputs a LaTeX-formatted character string representing the results. By default, calculated statistics are formatted with 3 digits to the left and 1 digit to the right of the decimal point. Running `table_options(left=l, right=r)` will use `l` and `r` digits instead. Other options that can be given to `table_options` are `prmsd=TRUE` to add mean +/- standard deviation to the result, `pn=TRUE` to add the sample size, `bold=TRUE` to set the median in bold face, `showfreq='all', 'low', 'high'` used by the `table_freq` function, `pctdec`, specifying the number of places to the right of the decimal point for percentages (default is zero), and `npct='both','numerator','denominator','none'` used by `table_formatpct` to control what appears after the percent. Option `pnformat` may be specified to control the formatting for `pn`. The default is `"(n=..)"`. Specify `pnformat="non"` to suppress `"n="`. `pnwhen` specifies when to print the number of observations. The default is `"always"`. Specify `pnwhen="ifna"` to include `n` only if there are missing values in the vector being processed.

`tabulr` substitutes `table_N` for `N` in the formula. This is used to create column headings for the number of observations, without a row label.

`table_freq` analyzes a character variable to compute, for a single output cell, the percents, numerator, and denominator for each category, or optimally just the maximum or minimum, as specified by `table_options(showfreq)`.

`table_formatpct` is a function that formats percents depending on settings of options in `table_options`.

`nFm` is a function that calls `sprintf` to format numeric values to have a specific number of digits to the `left` and to the `right` of the point.

`table_latexdefs` writes (by default) to the console a set of LaTeX definitions that can be invoked at any point thereafter in a `knitr` or `sweave` document by naming the macro, preceeded by a single slash. The `blfootnote` macro is called with a single LaTeX argument which will appear as a footnote without a number. `keytrio` invokes `blfootnote` to define the output of `table_trio` if mean and SD are not included. If mean and SD are included, use `keytriomsd`.

### Usage

    tabulr(formula, data = NULL, nolabel=NULL, nofill=NULL, ...)
    table_trio(x)
    table_freq(x)
    table_formatpct(num, den)
    nFm(x, left, right, neg=FALSE, pad=FALSE, html=FALSE)
    table_latexdefs(file='')

### Arguments

`formula` | a formula suitable for `tabular` except for the addition of `.(variable name)`, `.n()`, `trio`.
`data` | a data frame or list. If omitted, the parent environment is assumed to contain the variables.
`nolabel` | a formula such as `~ x1 + x2` containing the list of variables for which labels are to be ignored, forcing use of the variable name
`nofill` | a formula such as `~ x1 + x2` contaning the list of variables for which units of measurement are not to be right-justified in the field using the LaTeX `hfill` directive
`...` | other arguments to `tabular`
`x` | a numeric vector
`num` | a single numerator or vector of numerators
`den` | a single denominator
`left, right` | number of places to the left and right of the decimal point, respectively
`neg` | set to `TRUE` if negative `x` values are allowed, to add one more space to the left of the decimal place
`pad` | set to `TRUE` to replace blanks with the LaTeX tilde placeholder
`html` | set to `TRUE` to make `pad` use an HTML space character instead of a LaTeX tilde space
`file` | location of output of `table_latexdefs`

### Value

`tabulr` returns an object of class `"tabular"`

### Author(s)

Frank Harrell

### See Also

`tabular`, `label`, `latex`, `summaryM`

### Examples

    ## Not run:
    n <- 400
    set.seed(1)
    d <- data.frame(country=factor(sample(c('US','Canada','Mexico'), n, TRUE)),
                    sex=factor(sample(c('Female','Male'), n, TRUE)),
                    age=rnorm(n, 50, 10),
                    sbp=rnorm(n, 120, 8))
    d <- upData(d,
                preghx=ifelse(sex=='Female', sample(c('No','Yes'), n, TRUE), NA),
                labels=c(sbp='Systolic BP', age='Age', preghx='Pregnancy History'),
                units=c(sbp='mmHg', age='years'))
    contents(d)
    require(tables)
    invisible(booktabs())  # use booktabs LaTeX style for tabular
    g <- function(x) {
      x <- x[!is.na(x)]
      if(length(x) == 0) return('')
      paste(latexNumeric(nFm(mean(x), 3, 1)),
            ' \hfill{\smaller[2](', length(x), ')}', sep='')
    }
    tab <- tabulr((age + Heading('Females')*(sex == 'Female')*sbp)*
                  Heading()*g + (age + sbp)*Heading()*trio ~
                  Heading()*country*Heading()*sex, data=d)
    # Formula after interpretation by tabulr:
    # (Heading('Age\hfill {\smaller[2] years}') * age + Heading("Females")
    # * (sex == "Female") * Heading('Systolic BP {\smaller[2] mmHg}') * sbp)
    # * Heading() * g + (age + sbp) * Heading() * table_trio ~ Heading()
    # * country * Heading() * sex
    cat('\begin{landscape}\n')
    cat('\begin{minipage}{\textwidth}\n')
    cat('\keytrio\n')
    latex(tab)
    cat('\end{minipage}\end{landscape}\n')

    getHdata(pbc)
    pbc <- upData(pbc, moveUnits=TRUE)
    # Convert to character to prevent tabular from stratifying
    for(x in c('sex', 'stage', 'spiders')) {
      pbc[[x]] <- as.character(pbc[[x]])
      label(pbc[[x]]) <- paste(toupper(substring(x, 1, 1)), substring(x, 2), sep='')
    }
    table_options(pn=TRUE, showfreq='all')
    tab <- tabulr((bili + albumin + protime + age) *
                  Heading()*trio +
                  (sex + stage + spiders)*Heading()*freq ~ drug, data=pbc)
    latex(tab)

    ## End(Not run)

[Package Hmisc version 4.7-0 Index]