tbl_rift() builds a table from a design data frame with one row per
table row. The columns of the design and the values of its type column
follow the rifttable package, so a design written for
rifttable::rifttable() builds the same table here. Only type is
required; every other column has a default.
Columns of the design
| column | content |
type | The estimand of the row, one of the types below. "", "blank" or NA gives an empty row. |
label | The text of the first column. Defaults to type. A label starting with two spaces is indented; a label in **double asterisks** is bold and one in *single asterisks* or _underscores_ italic. |
exposure | The categorical variable whose levels become the columns. Every row must name the same variable. Without it the table has a single column. |
outcome | The outcome of the binary and continuous types: 0/1 or TRUE/FALSE for the binary types, numeric for the continuous ones. |
time, event | The follow-up time and the event indicator (0/1 or logical) of the event-time types. With competing events, event = "variable@level" names a factor whose first level is the censoring code and the level whose cumulative incidence is shown. |
time2 | With late entry, the exit time; time is then the entry time, as in survival::Surv(time, time2, event). |
effect_modifier, stratum | The rows are restricted to the observations whose effect_modifier equals stratum. stratum may hold several levels, NA for the observations with a missing modifier, and NULL or "" for no restriction. |
confounders | Covariates added to a model, as the tail of a formula: "+ age + sex". strata(), cluster() and offset() are available. |
trend | A numeric variable whose per-unit estimate is shown in a Trend column, for the comparative types. |
digits | Decimal places of the row, overriding the table's risk_digits, diff_digits, ratio_digits and rate_digits. |
nmin | A cell with fewer observations (or outcomes, or events) than nmin shows -- (<nmin). |
na_rm | Whether observations with a missing outcome, time or event are dropped before the row is computed. Default is FALSE, and a missing value then makes the cell missing. |
ci | The confidence level of the row, overriding the table's conf.level. |
to | The separator of the row's confidence limits, overriding the table's to. |
arguments | A list column of named lists: timepoint for the survival types, approach for rr, rd and the survival contrasts, robust for hr. |
Designs written for rifttable may carry weights and type2 columns; this
version of ltsummary stops with a message when they are filled.
Types
Descriptive types show one value per exposure level, and in the overall
column. Comparative types show each level against the first level of the
exposure, whose cell reads 1 (reference) or 0 (reference).
Binary outcomes (outcome coded 0/1):
| type | cell |
"outcomes" | Count of outcomes. |
"total" | Count of observations. |
"outcomes/total" | Both counts. |
"cases/controls" | Outcomes and non-outcomes. |
"risk" | Proportion with the outcome, a percentage with risk_percent. |
"risk (ci)" | The proportion with its Wilson score interval (Agresti and Coull, 1998), the "wilson.no.correct" method of add_ci(). |
"outcomes (risk)", "outcomes/total (risk)" | The counts with the proportion in parentheses. |
"rr", "rd" | Risk ratio and risk difference by marginal standardization after logistic regression with delta-method limits, or with approach in arguments a log-binomial model ("glm", "glm_startp") or a Poisson model with robust variance ("robpoisson"). See rift_risk. |
"or" | Odds ratio from logistic regression, with profile-likelihood limits. |
Continuous outcomes (outcome numeric):
| type | cell |
"total", "sum", "range" | Count, sum, and min, max. |
"mean", "mean (sd)", "sd" | Mean and standard deviation. |
"mean (ci)" | The mean with its normal interval, mean ± z * sd / sqrt(n), as rifttable reports it (add_ci() uses the t interval). |
"geomean" | Geometric mean. |
"median", "median (iqr)" | Median and quartiles (type 7 quantiles, where tbl_summary() uses type 2). |
"diff" | Mean difference from a linear model, with t limits. |
"fold" | Ratio of arithmetic means from a gaussian model with a log link. |
"foldlog" | Ratio of geometric means: a linear model of the log outcome, exponentiated. |
"irr", "irrrob" | Rate ratio from a Poisson model, with profile-likelihood limits or with the HC0 sandwich variance. |
Event-time outcomes (time and event):
| type | cell |
"events", "time", "events/time", "events/total" | Counts of events and observations, and person-time. |
"rate", "rate (ci)", "events/time (rate)" | Events per factor person-time, with normal-log limits, exp(log(d / T) ± z / sqrt(d)). See rift_rate(). |
"surv", "surv (ci)" | Kaplan-Meier survival at timepoint (the last observed time when none is given), with the log-transformed Greenwood limits of survival::survfit(). |
"cuminc", "cuminc (ci)" | Cumulative incidence, 1 - survival, or with competing events the Aalen-Johansen estimate of the named event. |
"medsurv", "medsurv (ci)" | Median survival time with the limits of quantile(survfit). |
"medfu", "medfu (iqr)" | Median follow-up by reverse Kaplan-Meier, with quartiles. |
"maxfu" | Longest follow-up. |
"hr" | Hazard ratio from survival::coxph(), with Wald limits; arguments = list(robust = TRUE) asks for the robust variance. |
"survdiff", "survratio" | Difference and ratio of survival at timepoint, with MOVER limits (Zou and Donner, 2008) or, for the difference, approach = "squareadd". See rift_survival. |
"cumincdiff", "cumincratio" | The same for the cumulative incidence. |
Append _joint to hr, rr, rd, or, irr, irrrob, diff,
fold, foldlog or a survival contrast for a joint model of the
exposure and the effect modifier: one model on every observation with a
non-missing modifier, with a single reference category (the first level
of both), where the row shows the coefficients of its stratum. A
trend in a joint row is still estimated within the stratum.
Rounding
Each type rounds with one of the table's digit arguments: risk_digits
for risks, survival, cumulative incidence and their differences;
ratio_digits for every ratio; rate_digits for rates; diff_digits
for the continuous statistics, means, differences and survival times; and
no decimals for counts and person-time. A digits value in the design
wins. ratio_digits_decrease then drops decimals from large ratios.
Suppression with nmin
nmin compares with the number of observations for the continuous
types, diff, irr, irrrob, fold and foldlog; with the number of
outcomes for the binary types, rr, rd and or; and with the number of
events for the event-time types, hr and the survival contrasts. The
reference cell is suppressed like any other.
References
Stopsack KH. rifttable: Results tables to bridge the rift between epidemiologists and their data. R package, https://stopsack.github.io/rifttable/.
Rothman KJ. The growing rift between epidemiologists and their data. Eur J Epidemiol 2017;32:863-5.
Agresti A, Coull BA. Approximate is better than "exact" for interval estimation of binomial proportions. Am Stat 1998;52:119-26.
Zou GY, Donner A. Construction of confidence limits about effect measures: a general approach. Stat Med 2008;27:1693-702.
Wilcox AJ. On precision. Epidemiology 2004;15:1.
See also
Other results tables:
rift_rate(),
rift_risk,
rift_survival,
tbl_rift()
Examples
# a design as a data frame, one row per estimand
design <- data.frame(
label = c("**Response**", " Responders/N (%)", " Risk ratio (95% CI)"),
type = c("", "outcomes/total (risk)", "rr"),
outcome = "response",
exposure = "trt",
na_rm = TRUE
)
tbl_rift(design, trial, risk_percent = TRUE)