CompetingRiskRegression

Fits Fine-Gray subdistribution-hazards models as a weighted Cox model on the Fine-Gray risk set. associate$regression instantiates this family for model = "crr", which model = "auto" also picks for a surv() outcome that declares a competing event.

survival::finegray() builds the time-weighted counting-process data for the event of interest, and survival::coxph() with ties = "breslow" and a per-subject cluster estimates the coefficients with robust (sandwich) standard errors -- reproducing cmprsk::crr()'s coefficients and variance. Status is coded 0 = censored, 1 = event of interest, 2 = competing event, and an observation positive for both the outcome and the competing event aborts the fit. A surv(entry = ) column supplies a delayed-entry Surv(entry, time, status) left-hand side to finegray(); case weights are not supported.

Result rows follow the "crr" association schema (schemaCrr() in associate-schemas.R): one row per predictor main and interaction coefficient, on the log-subdistribution-hazard scale (effect.scale = "log.subdistribution.hazard", test = "z"), with normal Wald limits and time, event, competing, entry, time.origin, n, n.events, n.competing, reference.level and contrast.level carried alongside.

observed.curves holds Aalen-Johansen cumulative-incidence curves, one per predictor group when the predictor is categorical and one pooled curve otherwise; group.summary gives each group's n, n.events and n.competing, and risk.table the numbers at risk, where a subject leaves the risk set on any event or censoring. predicted.curves is 1 - S(t) from survival::survfit() on the weighted Cox fit at profile predictor values, and prediction.grid names the covariate profile behind each. Bounds on both curve artifacts are analytic full-model cumulative-incidence intervals, not a coefficient-only approximation.

PolyGenius::RegressionFamily -> CompetingRiskRegression

Public methods

• CompetingRiskRegression$new()
• CompetingRiskRegression$validate.frame()
• CompetingRiskRegression$prepare.frame()
• CompetingRiskRegression$build.formula()
• CompetingRiskRegression$fit.model()
• CompetingRiskRegression$build.summary.rows()
• CompetingRiskRegression$build.artifacts()
• CompetingRiskRegression$clone()

Method new()

Register this family under the key "crr".

Usage

CompetingRiskRegression$new()

Returns

A new CompetingRiskRegression.

Method validate.frame()

Check the survival roles resolved onto the frame before any model is built.

Usage

CompetingRiskRegression$validate.frame(frame, cell, fit.specs, conf.level)

Arguments

frame — A data.table resolved from a PolyGeniusStudy, whose roles() tags identify the time, entry, outcome, competing, predictor, interaction and covariate columns.

cell — Named list describing one fit cell: fit.id, analysis.id, family, outcome, predictor, interaction, stratum. Unused.

fit.specs — Named list of extra fitting options. Unused.

conf.level — Numeric scalar in (0, 1). Unused.

Returns

TRUE, invisibly. Aborts unless exactly one column carries the time role, exactly one the competing role, at most one the entry role, and none the weights role -- finegray() supplies its own weights.

Method prepare.frame()

Shape the data for the Fine-Gray fit: time, event, competing, predictor (releveled when reference.level was given), and optional entry, interaction and covariate columns. Rows missing any of them are dropped, then the estimability of every model term is checked so a degenerate cell surfaces as a not-fitted condition rather than a contrasts error inside coxph().

Usage

CompetingRiskRegression$prepare.frame(frame, cell, fit.specs, conf.level)

Arguments

frame — A data.table resolved from a PolyGeniusStudy, whose roles() tags identify the time, entry, outcome, competing, predictor, interaction and covariate columns.

cell — Named list describing one fit cell. Unused; columns come from the frame's roles.

fit.specs — Named list of extra fitting options. reference.level and time.origin are read here.

conf.level — Numeric scalar in (0, 1). Unused.

Returns

Named list: data (complete-case data.frame), time.name, event.name, competing.name, entry.name (NA_character_ when none), time.origin (NA_character_ when none), predictor.name, predictor.label, interaction.name, covariate.names and row.id, the retained row indices into frame. Aborts when any observation is positive for both the outcome and the competing event.

Method build.formula()

Build the FineGray(...) ~ predictor [* interaction] [+ covariates] formula recorded on the result rows. fit.model() drives the actual finegray()/coxph() call, so this formula is display and metadata only.

Usage

CompetingRiskRegression$build.formula(frame)

Arguments

frame — Named list returned by prepare.frame().

Returns

A formula, carrying the original-column-name form as the "display.formula" attribute.

Method fit.model()

Fit the Fine-Gray model as a weighted Cox model on the survival::finegray() risk set for status level "1", using ties = "breslow" and a per-subject cluster so the coefficients and robust standard errors match cmprsk::crr().

Usage

CompetingRiskRegression$fit.model(formula, frame, ...)

Arguments

formula — A formula from build.formula(). Unused for fitting; the coxph() formula is rebuilt over the finegray() columns.

frame — Named list returned by prepare.frame(); only $data, $entry.name, $interaction.name and $covariate.names are read.

... — Further arguments passed to survival::coxph().

Returns

A fitted, weighted coxph object over Surv(fgstart, fgstop, fgstatus).

Method build.summary.rows()

Turn the fitted model's predictor coefficients into standard result rows on the log-subdistribution-hazard scale, with robust standard errors read from vcov() -- which honours the cluster argument, so they match cmprsk::crr()$var.

Usage

CompetingRiskRegression$build.summary.rows(
  fit,
  fit.data,
  cell,
  fit.specs,
  conf.level,
  formula
)

Arguments

fit — A fitted, weighted coxph object.

fit.data — Named list returned by prepare.frame().

cell — Named list describing one fit cell: fit.id, analysis.id, family, outcome, predictor, stratum.

fit.specs — Named list of extra fitting options. Unused.

conf.level — Numeric scalar in (0, 1). Confidence level for lower/upper, taken from the normal distribution.

formula — Character scalar. Display formula recorded on each row.

Returns

A data.table of "crr"-schema rows, one per predictor main and interaction coefficient. Aborts when no coefficient name matches the predictor.

Method build.artifacts()

Build the observed Aalen-Johansen cumulative-incidence curves for the analysis sample and the model-predicted CIF curves at profile predictor values.

Usage

CompetingRiskRegression$build.artifacts(
  fit,
  fit.data,
  cell,
  fit.specs,
  conf.level,
  formula
)

Arguments

fit — A fitted, weighted coxph object.

fit.data — Named list returned by prepare.frame().

cell — Named list describing one fit cell.

fit.specs — Named list of extra fitting options. Unused.

conf.level — Numeric scalar in (0, 1). Passed to survival::survfit() for the predicted curves only; the observed CIF uses survfit()'s own default.

formula — Character scalar. Unused; present for interface parity.

Returns

Named list of data.frames: observed.curves, risk.table, group.summary, predicted.curves and prediction.grid.

Method clone()

The objects of this class are cloneable with this method.

Usage

CompetingRiskRegression$clone(deep = FALSE)

Arguments

deep — Whether to make a deep clone.

associate$regression, CoxRegression for the cause-specific fit without a competing event, KaplanMeierRegression for the unadjusted group comparison.

Other regression-families: CoxRegression, KaplanMeierRegression, LinearRegression, LogisticRegression, RegressionFamily