PolyGenius
Contents

CoxRegression

Cox proportional-hazards family for associate$regression()

Fits right-censored proportional-hazards models with survival::coxph(). associate$regression instantiates this family for model = "cox", which model = "auto" also picks for a surv() outcome that declares no competing event.

Details

The fitted model is Surv(time, event) ~ predictor [* interaction] [+ covariates] on complete cases. A surv(entry = ) column switches the left-hand side to Surv(entry, time, event), so each event's risk set holds only subjects already under observation at that time; a row missing entry is dropped rather than treated as entering at time 0. Case weights are used when the resolved frame carries a weights column.

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

Artifacts

observed.curves is one pooled Kaplan-Meier curve over the analysis sample (curve.id = "analysis"), and group.summary its single row of n, n.events and median survival. risk.table is split by predictor group when the predictor is categorical and pooled otherwise. predicted.curves comes from survival::survfit() on the fitted model at profile predictor values -- observed levels for a categorical predictor, quartiles for a numeric one with more than six distinct values -- and prediction.grid names the covariate profile behind each predicted curve.

Super class

PolyGenius::RegressionFamily -> CoxRegression

Methods

Public methods

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

Method new()

Register this family under the key "cox".

Usage

CoxRegression$new()

Returns

A new CoxRegression.

Method validate.frame()

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

Usage

CoxRegression$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, predictor, interaction, covariate and weight 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 and at most one carries the entry role.

Method prepare.frame()

Shape the data for the survival::coxph() fit: time, event (0/1), predictor (releveled when reference.level was given), and optional entry, interaction, covariate and weights columns. Rows missing any of them are dropped.

Usage

CoxRegression$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, predictor, interaction, covariate and weight 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 with columns time, event, predictor and, when present, entry, interaction, the covariates and weights), time.name, event.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.

Method build.formula()

Build Surv(time, event) ~ predictor [* interaction] [+ covariates], or Surv(entry, time, event) ~ ... when the fit frame carries an entry time.

Usage

CoxRegression$build.formula(frame)

Arguments

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

Returns

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

Method fit.model()

Fit the model with survival::coxph() on frame$data, adding case weights when frame$data carries a weights column.

Usage

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

Arguments

formula — A formula from build.formula().

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

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

Returns

A fitted coxph object.

Method build.summary.rows()

Turn the fitted model's predictor coefficients into standard result rows on the log-hazard scale.

Usage

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

Arguments

fit — A fitted 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 "cox"-schema rows, one per predictor main and interaction coefficient. Aborts when no coefficient name matches the predictor.

Method build.artifacts()

Build the pooled observed Kaplan-Meier curve for the analysis sample and the model-predicted survival curves at profile predictor values.

Usage

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

Arguments

fit — A fitted 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 both the observed and the predicted bands.

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

CoxRegression$clone(deep = FALSE)

Arguments

deep — Whether to make a deep clone.

Examples

# Right-censored survival outcome; "auto" resolves to this family
associate$regression(data,
  outcomes = surv(time = age_obs, event = dementia),
  predictors = PRS_AD,
  covariates = c(sex, PC1, PC2))

# Left-truncated (delayed-entry) fit
associate$regression(data,
  outcomes = surv(time = age_exit, event = dementia, entry = age_entry,
                  origin = "age since birth"),
  predictors = PRS_AD)

See Also

associate$regression, CompetingRiskRegression when a competing event is declared, KaplanMeierRegression for the unadjusted group comparison.

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