excess_risk – matchatr

Time-varying cumulative excess hazard from an additive NCC fit

Description

Estimates the Aalen cumulative regression functions B_j(t) = ∫₀ᵗ β_j(s) ds — the time-varying excess cumulative hazard for each covariate — from a fitted IPW nested case-control additive-hazards (“ipw_aalen”) design. Where contrast(type = “excess”) reports one time-constant excess hazard per covariate (the Lin-Ying model), excess_risk() relaxes the constant-effect assumption and returns the full cumulative regression function over time — the additive analogue of absolute_risk().

Usage

excess_risk(fit, ...)

## S3 method for class 'matchatr_fit'
excess_risk(fit, times, conf_level = 0.95, ...)

Arguments

fit A matchatr_fit returned by matcha() with estimator = “ipw_aalen”.

… Unused; present for S3 consistency.

times Non-empty numeric vector of evaluation times. Duplicates are dropped and times sorted; times before the first event return B̂ = 0, times after the last estimable event return the last cumulative value (step-function extrapolation).

conf_level Numeric in (0, 1). Pointwise confidence level. Default 0.95.

Details

The fully nonparametric additive-hazards model (Aalen 1980) writes λ(t | x) = β₀(t) + Σ_j β_j(t) x_j with time-varying coefficients. Its weighted least-squares estimator gives the cumulative regression functions in increments at each event time t_i,

dB̂(t_i) = (X̃ᵀ W X̃)⁻¹ X̃ᵀ W dN(t_i),

where X̃ is the at-risk design matrix (an intercept column plus the covariates), W = diag(w) the Samuelsen inclusion weights, and dN(t_i) the event indicator over the risk set. B̂_j(t) = Σ over (t_i ≤ t) of dB̂_j(t_i). Pointwise variances use the Aalen (martingale) estimator

V̂(t) = Σ over (t_i ≤ t) of (X̃ᵀ W X̃)⁻¹ (Σ over failures w_i² x̃_i x̃_iᵀ) (X̃ᵀ W X̃)⁻¹,

and the pointwise interval is B̂_j(t) ± z·sqrt(V̂_jj(t)) on the linear scale (symmetric, possibly negative — an excess hazard is a rate difference). The weighted estimator reuses controls via 1/π_j and is valid under nested case-control sampling (Borgan & Langholz 1997). timereg::aalen (without const()) computes the same cum and var.cum.

The estimator is defined only while the weighted design X̃ᵀWX̃ is non-singular; if the risk set shrinks below full column rank at a late event time, B̂(t) is truncated there and a matchatr_truncated_excess warning reports the last estimable time. The intercept (baseline cumulative hazard) is not reported — only the covariate excess-hazard functions.

Value

A matchatr_excess_risk object. See excess_risk.matchatr_fit for the structure.

A matchatr_excess_risk list with elements:

$estimates: a data.table with columns term (covariate), time, estimate (B̂_j(t)), se, ci_lower, ci_upper (symmetric Wald interval on the linear scale).
$times: the sorted evaluation times.
$terms: the reported covariate terms.
$conf_level, $ci_method, $engine, $estimator, $n.

References

Aalen OO (1980). A model for nonparametric regression analysis of counting processes. In Mathematical Statistics and Probability Theory (Lecture Notes in Statistics 2), pp. 1-25. Springer.

Lin DY, Ying Z (1994). Semiparametric analysis of the additive risk model. Biometrika 81(1):61-71.

Borgan O, Langholz B (1997). Estimation of excess risk from case-control data using Aalen’s linear regression model. Biometrics 53(2):690-697.

Examples

library("matchatr")

ncc <- sample_ncc(cohort, time = "t", event = "d", m = 3, incl_prob = TRUE)
fit <- matcha(ncc, outcome = "d", exposure = "x",
              design = nested_cc(strata = "set", time = "t"),
              estimator = "ipw_aalen")
excess_risk(fit, times = c(1, 2, 3, 4))