Draw a counter-matched nested case-control sample from a cohort
Description
Generates a counter-matched nested case-control (NCC) dataset from a full cohort: at each event time the case is matched to m controls drawn exclusively from the opposite surrogate stratum, concentrating study resources in subjects whose surrogate exposure differs from the case. The analysis weights (log-sampling-weights) for the Langholz-Borgan (1995) weighted partial likelihood are appended as a log_w column: the case represents its entire surrogate stratum (log-weight = log(n_same + 1)) and each control represents the opposite stratum divided by the controls drawn (log-weight = log(n_other / m)). The result feeds straight into matcha(design = counter_matched(strata = “set”, time = “risk_time”, weights = “log_w”)), whose survival::coxph fit reports the hazard ratio.
Usage
sample_ncc_counter_matched(
cohort,
time,
event,
surrogate,
m = 1L,
match = NULL,
entry = NULL
)
Arguments
cohort
A data.frame or data.table with one row per subject.
time
A single character string naming the exit / event-time column. Must be numeric.
event
A single character string naming the event indicator (logical, two-level factor, or numeric 0/1); at least one event must occur.
surrogate
A single character string naming the binary surrogate exposure column. Controls are drawn from subjects whose surrogate value differs from the case’s. Must be logical, numeric 0/1, or a two-level factor; no missing values.
m
A single whole number >= 1, the number of controls sampled per case from the opposite surrogate stratum (default 1).
match
NULL (no additional matching) or a one-sided formula naming population-stratum column(s) controls must share with the case (e.g. ~ sex + birth_cohort).
entry
NULL (everyone enters at the time origin) or a single character string naming a delayed-entry / left-truncation column.
Details
Controls are drawn without replacement from subjects at risk at the case’s failure time (entry < tc <= time) in the opposite surrogate stratum. When fewer than m eligible controls exist (late failure times or narrow strata), the smaller available set is returned rather than an error. A case with no eligible control in the opposite stratum — which means the entire at-risk population shares the case’s surrogate value — aborts with matchatr_empty_risk_set, signalling a sampling-design failure.
Additional matching (match = ~ s1 + s2) restricts each risk set to subjects sharing the case’s population-stratum values on the named variables. The eligibility pool is first restricted by the match stratum, and the surrogate split is then applied within that pool.
The surrogate column must be binary: logical, numeric 0/1, or a two-level factor. Missing values abort with matchatr_bad_input.
The log-weights are the key difference from unweighted sample_ncc(): with pure counter-matching the unweighted clogit is biased because the controls were drawn non-uniformly (opposite-stratum only), so the weighted partial likelihood (coxph + offset) must be used for analysis.
Value
A data.table with one row per sampled subject: the selected rows of cohort (all original columns) plus set (integer matched-set id), case (per-set 0/1 indicator), risk_time (the set’s failure time), and log_w (the log-sampling-weight for the weighted partial likelihood). Aborts with matchatr_empty_risk_set when any case has no eligible control in the opposite surrogate stratum.
References
Langholz B, Borgan O (1995). Counter-matching: a stratified nested case-control sampling method. Biometrika 82(1):69-79.
See Also
counter_matched(), matcha(), sample_ncc()
Other sampling: compute_ncc_weights(), reuse_ncc_endpoint(), sample_ncc()