tabulr: Interface to Tabular Function

In harrelfe/Hmisc: Harrell Miscellaneous

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)

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