Fit Cox proportional hazards models and report hazard ratios.
Usage
cox_reg(
data,
time,
event,
exposures,
adjust_for = NULL,
stratifier = NULL,
interaction = NULL,
multivariable = FALSE,
multivariate = NULL,
format = c("flextable", "gt"),
theme = c("minimal"),
show_sample = "both",
model_stats = FALSE,
show_ref = TRUE,
baseline_strata = NULL,
time_start = NULL,
cluster = NULL,
weights = NULL,
robust = NULL,
ties = c("efron", "breslow", "exact"),
control = NULL
)Arguments
- data
A
data.framecontaining survival time, event status, and exposure variables.- time
Survival follow-up time. Quoted and bare names are accepted.
- event
Event indicator. Quoted and bare names are accepted. Numeric
0/1, numeric1/2, logical, character, and factor variables are accepted. For two-level character or factor variables, the second level is treated as the event.- exposures
Character vector of exposure variable names. Quoted names are recommended in scripts, and bare names are also accepted.
- adjust_for
Optional character vector of adjustment variables. When supplied, one adjusted Cox model is fitted per exposure.
- stratifier
Optional single stratifying variable. When supplied, stratum-specific Cox tables are produced using the same crude, adjusted, or multivariable workflow requested by the other arguments. The stratifier cannot also be used as the time, event, exposure, adjustment, or interaction variable.
- interaction
Optional character scalar specifying one interaction term using standard formula syntax, e.g.
"trt*prior". Quoted and bare interaction syntax are accepted. In exposure-by-exposure mode, supply a single exposure; inmultivariable = TRUEmode, the interaction is added to the single multivariable model.- multivariable
Logical; if
FALSE(default), the current exposure-by-exposure workflow is used. IfTRUE, one multivariable Cox model is fitted using all variables inexposures, and all exposure coefficients are reported.- multivariate
Optional logical alias for
multivariable. This is accepted for convenience;multivariableis used internally.- format
Output table format; one of
"flextable"(default) or"gt".- theme
Table styling preset.
- show_sample
For stratified Cox tables (
stratifiersupplied), controls which sample-size columns are shown in the publication table. One of"both"(default; N and events),"n","events", or"none". Model statistics, when requested, still retain both N and event counts. This argument is ignored whenstratifieris not supplied: non-stratified tables always show the model N column and report the number of events in a footnote.- model_stats
Logical; if
TRUE, extract model-fit statistics including AIC, BIC, log-likelihood, concordance, number of events, and N.- show_ref
Logical; if
TRUE(default), display reference-category rows as"Ref.". IfFALSE, hide reference rows; a message reminds users to useshow_ref = TRUEwhen reference rows are needed.- baseline_strata
Optional character vector of categorical variables used to stratify the baseline hazard within one Cox model. Common hazard ratios are estimated while each stratum has a separate baseline hazard. No hazard ratio is estimated for these variables. This cannot be combined with
stratifier, which fits separate models.- time_start
Optional numeric variable containing entry or interval-start times. When supplied, a counting-process response
Surv(time_start, time, event)is fitted, enabling delayed entry and start-stop data.- cluster
Optional variable identifying correlated observations. Cox models use a clustered sandwich variance estimate for this variable.
- weights
Optional numeric case-weight variable.
- robust
Optional logical passed to
survival::coxph(). The defaultNULLletscoxph()choose its standard behaviour; clustered models use robust variance automatically.- ties
Method for handling tied event times:
"efron"(default),"breslow", or"exact".- control
Optional named list of arguments for
survival::coxph.control(), or a completed control list returned by that function.
Value
A list of class c("gtregression","cox_reg", ...) with elements:
- table
A
flextableorgt_tbl.- table_body
Data frame of hazard ratios and confidence intervals.
- table_display
Data frame used to render the publication table.
- models
List of fitted
coxphmodels.- model_summaries
Summary output for the fitted models.
- model_stats
Model-fit statistics when
model_stats = TRUE; otherwiseNULL.- variable_labels
Named character vector of display labels.
- footnotes
Character vector used by the rendered table. Adjustment notes use the same display labels as the table.
- time,event,approach,format,source,adjust_for,baseline_strata, exposures,interaction
Metadata fields.
Details
By default, cox_reg() keeps the exposure-by-exposure workflow:
without adjust_for, one crude Cox model is fitted per exposure; with
adjust_for, one adjusted Cox model is fitted per exposure and only the
exposure estimate is reported. This is useful for screening or for reporting
several adjusted exposure effects.
With multivariable = TRUE, all variables in exposures are
included in a single Cox model and all coefficients are reported. This mirrors
the multivariable workflow used by multi_reg(). The
adjust_for argument is not used in this mode; include every variable
that belongs in the model inside exposures. Since these estimates are
adjusted for the other variables in the same model, the table reports
Adjusted HR (95% CI).
Interaction terms specified via interaction are included using
standard formula expansion (for example, trt*prior). Interaction
effects are displayed as additional rows beneath the corresponding exposure.
baseline_strata fits one Cox model with separate baseline hazards for
the observed combinations of the selected categorical variables. It reports
common hazard ratios for the predictors and no coefficient for the strata.
This differs from stratifier, which fits separate models and reports
stratum-specific results.
The proportional hazards assumption should be assessed separately, for
example with check_ph().
Stratified Cox tables show both N and event counts by default
(show_sample = "both"). Use show_sample = "n",
show_sample = "events", or show_sample = "none" to control the
displayed sample columns. All counts are taken from the fitted model within
each stratum, so rows dropped for missing values in any model variable
(including time_start, cluster, and weights) are not
counted. When models within a stratum use different numbers of
observations, the footnote reports the range. Rows with a missing
stratifier value are excluded and counted in a footnote.
show_sample has no effect without stratifier.
Complete-case analysis is used: each model uses the rows that are complete
for its own variables. Unused factor levels are dropped for each fitted
model, so the reference category shown as "Ref." is the first level
present in the data used by that model. Ordered factors are analysed with
treatment (category-versus-reference) contrasts. Data in which every
observation is an event are accepted.
If exposure variables have a "label" attribute, for example from
labelled::var_label(), those labels are used automatically in the
displayed table.
Examples
lung_data <- data_lungcancer
lung_data$trt <- factor(lung_data$trt, levels = c(1, 2),
labels = c("Standard", "Test"))
lung_data$prior <- factor(lung_data$prior, levels = c(0, 10),
labels = c("No", "Yes"))
cox_reg(
data = lung_data,
time = time,
event = status,
exposures = c("trt", "celltype", "karno", "age")
)
cox_reg(
data = lung_data,
time = time,
event = status,
exposures = c(trt, celltype, prior),
adjust_for = c(age, karno)
)
# Interaction in an adjusted exposure model
cox_reg(
data = lung_data,
time = time,
event = status,
exposures = trt,
adjust_for = c(age, karno),
interaction = trt*prior
)
cox_reg(
data = lung_data,
time = time,
event = status,
exposures = c(trt, celltype, prior, age, karno),
multivariable = TRUE
)
# One model with separate baseline hazards by cell type
cox_reg(
data = lung_data,
time = time,
event = status,
exposures = c(trt, age, karno),
baseline_strata = celltype,
multivariable = TRUE
)
# multivariate is accepted as an alias
cox_reg(
data = lung_data,
time = time,
event = status,
exposures = c(trt, age, karno),
multivariate = TRUE
)