matchatr

matchatr provides causal inference for (matched) case-control, nested case-control (NCC), and case-cohort study designs. It pairs design-faithful classical estimators with marginal causal effects, and integrates with the etverse ecosystem — delegating estimation to causatr (g-computation / IPW / AIPW with sandwich and bootstrap variance) and survatr (causal survival on person-period data).

Status: classical engines complete; the case-control-weighting causal layer complete. The design taxonomy, the two-step matcha() / contrast() API, and the (design, estimator) dispatch (PHASE_1) are in place, and the classical engines run end to end: the unmatched case-control logistic and Mantel-Haenszel ORs (PHASE_2), the matched case-control conditional-logistic and McNemar ORs with stratum-specific effect modification (PHASE_3), the polytomous subtype ORs with test_homogeneity() (PHASE_4), the nested case-control risk-set hazard ratio (PHASE_5), the case-cohort Prentice / Self-Prentice / Borgan hazard ratios and absolute risk (PHASE_6), and the Samuelsen IPW weighted Cox / AFT / additive-hazards analyses of NCC data with absolute and excess risk (PHASE_7). The causal layer is complete (PHASE_9): estimator = "ccw_gformula" / "ccw_ipw" / "ccw_aipw" / "ccw_tmle" report a marginal risk difference, risk ratio, or marginal odds ratio from an unmatched or matched case-control sample with a known (or cohort-estimated) prevalence q₀, via Rose & van der Laan case-control weighting — g-computation / IPW / (doubly-robust) AIPW delegated to causatr, and a doubly-robust targeted maximum likelihood (TMLE) engine matchatr builds itself. Variance is the causatr sandwich / TMLE efficient influence function, optionally widened for an estimated q₀ or replaced by a design-preserving within-stratum bootstrap. See the articles for worked examples. The design-weighted causal survival layer and the efficiency phases (PHASE_10–PHASE_20) remain at the design stage.

What it does

Two orthogonal axes: a design object encodes the sampling structure (strata, matching ratio, time scale, prevalence, inclusion weights); an estimator chooses the analysis.

Design	Classical estimand	Causal (marginal) estimand
Unmatched case-control	conditional OR, Mantel-Haenszel	RD / RR / marginal OR (case-control weighting)
Matched case-control	conditional OR (conditional logistic)	RD / RR via standardization
Nested case-control	risk-set HR; Samuelsen IPW Cox	marginal survival contrasts (design-weighted)
Case-cohort	Prentice / Self-Prentice / Borgan HR	absolute risk, RD(t), RMST

Marginal causal effects use case-control weighting (the Rose & van der Laan g-formula / IPW / AIPW / TMLE family) and design-based inclusion weighting (Samuelsen, Borgan): the weights are passed as observation weights into the etverse engines, so they compose directly with existing estimators.

Installation

You can install the development version of matchatr from GitHub with:

# install.packages("pak")
pak::pak("etverse/matchatr")

Example

library(matchatr)

# Matched case-control -> conditional odds ratio (infert: a matched study of
# spontaneous/induced abortion and infertility, matched on age and parity).
fit <- matcha(
  infert,
  outcome = "case", exposure = "spontaneous",
  design = matched_cc(strata = "stratum"),
  confounders = ~ induced, estimator = "clogit"
)

contrast(fit, type = "or")
#> <matchatr_result>
#>  Estimator:  clogit  (engine: clogit)
#>  Estimand:   conditional OR
#>  Contrast:   Odds ratio
#>  CI method:  model
#>  N:          248
#> 
#> Contrasts:
#>     comparison estimate     se ci_lower ci_upper
#>         <char>    <num>  <num>    <num>    <num>
#> 1: spontaneous 7.285423 2.5677 3.651357 14.53635

The marginal causal contrasts (case-control weighting) reuse the same two-step API once a source-population prevalence q0 is supplied — they are part of the roadmap below:

fit <- matcha(
  data,
  outcome = "case", exposure = "x",
  design = unmatched_cc(prevalence = 0.02),   # source-population prevalence q0
  confounders = ~ age + smoke, estimator = "ccw_gformula"
)
contrast(fit, type = "difference", ci_method = "sandwich")

Roadmap

The design is documented in PHASE_1–PHASE_20 at the repository root, mapping the Handbook of Statistical Methods for Case-Control Studies (Borgan et al., 2018) to an implementation plan. See CLAUDE.md for the phase index and FEATURE_COVERAGE_MATRIX.md for what is implemented and tested.

Part of the etverse

matchatr is one package in the etverse family for causal inference and methodological triangulation, alongside causatr (causal effect estimation) and survatr (causal survival analysis).