compute_ncc_weights

Compute working-model inclusion probability weights for an NCC sample

Description

Replaces or sets the ipw_weight column of a nested case-control dataset using a working model for the probability that a subject is selected as a control at each event time. Two estimation strategies are available:

“glm” — fits a logistic regression of the binary selection indicator (selected ~ selection_formula) across all (subject, event-time) pairs where the subject is in the risk set; uses stats::glm().
“gam” — same but uses mgcv::gam() so that smooth terms (e.g. s(risk_time)) are available in selection_formula.

Both methods require the full Phase-1 cohort to reconstruct the risk set at every event time and determine which subjects were eligible but not selected. Omitting cohort (or supplying a cohort without the time column) aborts with matchatr_missing_phase1.

Usage

compute_ncc_weights(
  ncc,
  cohort,
  method = c("glm", "gam"),
  selection_formula = NULL,
  time,
  entry = NULL
)

Arguments

ncc A data.table or data.frame from sample_ncc() with incl_prob = TRUE. Must contain the columns .cohort_row (integer cohort row index), ipw_weight, set (matched-set id), case (per-set 0/1 indicator), and risk_time (set’s event time).

cohort A data.frame or data.table — the full Phase-1 cohort from which ncc was drawn. Must contain the time column and any covariates referenced in selection_formula. Required for working-model methods; NULL is rejected with matchatr_missing_phase1.

method Character scalar; the weight estimation strategy. One of “glm” (logistic regression via stats::glm()) or “gam” (generalised additive model via mgcv::gam()).

selection_formula NULL (the default) or a one-sided formula naming the predictors for the selection model. The response is always selected (the binary indicator of being chosen as a control). Default NULL maps to ~ risk_time. Smooth terms (e.g. s(risk_time)) are supported only for method = “gam”.

time A single character string naming the event/follow-up time column in cohort. Determines which cohort subjects are at risk at each event time: a subject is eligible if cohort[[time]] >= risk_time_k (and cohort[[entry]] < risk_time_k when entry is supplied).

entry NULL (everyone enters at the origin) or a single character string naming a delayed-entry column in cohort.

Details

The working-model inclusion probability for subject j is:

π_j = 1 − ∏_(k: j ∈ R(t_k)) (1 − p̂_jk)

where the product runs over all event times t_k at which j was in the risk set R(t_k) (excluding the case’s own failure time), and p̂_jk is the predicted probability from the fitted selection model. Cases (cohort events) are always included with weight 1.

The default selection_formula = NULL maps to ~ risk_time, a time-only logistic model in the spirit of the estimated-weight (working-model) approach of Samuelsen, Ånestad & Skrondal (2007, Scandinavian Journal of Statistics 34(1)). Richer models can include cohort covariates: ~ risk_time + age + sex.

Population-stratum matching caveat. If ncc was generated with sample_ncc() using a match argument (e.g. match = ~ sex), controls were drawn only from subjects in the case’s matching stratum. The default working model does not condition on the matching variable, which causes all at-risk subjects (including those from other strata) to be treated as "eligible but not selected". Add the matching variable to selection_formula (e.g. selection_formula = ~ risk_time + sex) to partially account for this.

Value

A copy of ncc (as a data.table) with the ipw_weight column set to the working-model inverse inclusion probabilities: 1 for cases, 1/π_j (>= 1) for sampled controls. The .cohort_row column is preserved unchanged.

References

Samuelsen SO (1997). A pseudolikelihood approach to analysis of nested case-control studies. Biometrika 84(2):379-394.

Samuelsen SO, Ånestad H, Skrondal A (2007). Stratified case-cohort analysis of general cohort sampling designs. Scandinavian Journal of Statistics 34(1):103-119.

Examples

library("matchatr")

set.seed(1)
tt <- rexp(500, 0.1)
cohort <- data.frame(
  id = 1:500,
  t  = pmin(tt, 15),          # bound follow-up to avoid empty late risk sets
  d  = as.integer(tt <= 15),
  x  = rbinom(500, 1, 0.4)
)
ncc <- sample_ncc(cohort, time = "t", event = "d", m = 2, incl_prob = TRUE)

# Replace Samuelsen KM weights with GLM working-model weights
ncc_glm <- compute_ncc_weights(ncc, cohort = cohort, method = "glm", time = "t")

# Fit IPW Cox using the GLM weights
fit <- matcha(ncc_glm, outcome = "d", exposure = "x",
              design = nested_cc(strata = "set", time = "t"),
              estimator = "ipw_cox")
contrast(fit)

<matchatr_result>
 Estimator:  ipw_cox  (engine: ipw_cox)
 Estimand:   hazard ratio
 Contrast:   Hazard ratio
 CI method:  model
 N:          494

Contrasts:
   comparison  estimate        se  ci_lower ci_upper
       <char>     <num>     <num>     <num>    <num>
1:          x 0.9800633 0.1004238 0.8017416 1.198047