wdsmatchATT: Weighted Double Score Matching Estimator for Population...

In wdsmatch: Weighted Double Score Matching for Survey-Weighted Causal Inference

Weighted Double Score Matching Estimator for Population Average Treatment Effect on the Treated

Description

Estimates the population average treatment effect on the treated (PATT) using survey-weighted double score matching. Treated units are matched to controls using the control-side double score consisting of propensity probability and control prognostic score. Only the missing control outcome requires imputation; treated outcomes remain observed. Aggregation uses treated-side survey weights and Hajek normalization.

Usage

wdsmatchATT(
  Y,
  X,
  Z,
  weights,
  M = 5,
  ps = NULL,
  pg = NULL,
  model.ps = NULL,
  model.pg = NULL,
  sampling = c("retrospective", "prospective"),
  use.bias.correction = TRUE,
  varest = TRUE,
  boots = 200,
  alpha = 0.05
)

Arguments

Y	Finite numeric vector of observed outcomes, with no missing values.
X	Numeric matrix or data frame with finite numeric covariate columns, one row per unit, and unique names other than Y or Z.
Z	Binary treatment indicator (1 = treated, 0 = control), with one entry per unit and both groups represented.
weights	Finite, strictly positive numeric vector of survey design weights, with one entry per unit. Required.
M	Positive integer number of nearest neighbors (default 5). Each required donor arm must contain at least M units.
ps	Optional finite numeric vector of pre-estimated propensity probabilities strictly between zero and one. If NULL (default), estimate internally using model.ps. Supplied scores remain fixed during replication; see Details.
pg	Optional matrix of pre-estimated prognostic scores, with columns psi0 (control) and psi1 (treated) in that order and one row per unit. PATT also accepts a one-column matrix containing only the control-side score; with two columns, only the first is used. If NULL (default), estimate the required arm-specific scores using model.pg. Supplied scores remain fixed during replication; see Details.
model.ps	Formula for the propensity model, such as Z ~ X1 + X2. If NULL, use all columns of X. Used only when ps is NULL.
model.pg	Formula for the prognostic regression, such as Y ~ X1 + X2. If NULL, use all columns of X. Used only when pg is NULL.
sampling	Character: "retrospective" (default) for treatment-dependent sampling with survey-weighted propensity fitting, or "prospective" for treatment-independent sampling with unweighted propensity fitting. This choice also applies to replication refits.
use.bias.correction	Logical: apply the arm-specific complete quadratic bias correction (default TRUE); see Details for the interpretation of FALSE.
varest	Logical: compute replication variance and a centered normal Wald interval (default TRUE).
boots	Integer number of multinomial replicates, at least 2 when variance is requested (default 200).
alpha	Significance level strictly between zero and one (default 0.05). The interval confidence level is 1 - alpha.

Details

PATT uses only the control-side prognostic and bias-correction regressions; a treated-outcome regression is not required. Treatment identification uses one-sided unconfoundedness of the control potential outcome, together with the required survey identification, positivity, and regularity assumptions.

Matching, score fitting, arm-specific quadratic bias correction, strict numerical checks, and the behavior of supplied scores follow wdsmatchATE. The PATT replication expression retains the original weighted control reuse coefficients and normalizes by the replicate's treated-side survey-weight total. Variance uses divisor boots; intervals are centered normal Wald intervals. All requested replicates must succeed, otherwise an informative error is raised.

Supplied scores remain fixed during replication, so their external estimation uncertainty is excluded. With use.bias.correction = FALSE, matching discrepancies remain and the bias-corrected asymptotic justification does not automatically apply. The weight-only interface and individual-unit multinomial replication do not provide general variance estimation for arbitrary clustered or stratified survey designs. See wdsmatchATE for full details.

Value

A list of class wdsmatch with the same components as wdsmatchATE, with estimate targeting PATT and estimand identifying PATT.

Examples

data(survey_obs)
fit <- wdsmatchATT(
  Y = survey_obs$Y,
  X = survey_obs[, c("X1", "X2", "X3", "X4", "X5", "X6")],
  Z = survey_obs$Z,
  weights = survey_obs$survey_weight,
  M = 3,
  model.ps = Z ~ X1 + X2 + X3 + X4 + X5 + X6 + X1:X2,
  model.pg = Y ~ X1 + X2 + X3 + X4 + X5 + X6 + X1:X2,
  sampling = "retrospective",
  varest = FALSE
)
fit

wdsmatch documentation built on Sept. 12, 2026, 1:06 a.m.