Package {wdsmatch}

Print method for wdsmatch objects

Description

Print method for wdsmatch objects

Usage

## S3 method for class 'wdsmatch'
print(x, digits = 4, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console, including the point estimate, standard error, confidence interval, number of matches, and sample sizes.

Summary method for wdsmatch objects

Description

Summary method for wdsmatch objects

Usage

## S3 method for class 'wdsmatch'
summary(object, ...)

Arguments

Value

Invisibly returns the input object. Called for its side effect of printing a formatted summary to the console.

Simulated Survey Observational Data

Description

A simulated dataset drawn from a survey-weighted observational study with treatment-dependent (retrospective) sampling. Contains 6 covariates, a binary treatment indicator, observed outcome, and survey design weights. The true PATE is approximately 0.8 and the true PATT approximately 1.0.

Usage

survey_obs

Format

A data frame with approximately 120 rows and 9 variables:

Y

Observed outcome (continuous).

Z

Binary treatment indicator (1 = treated, 0 = control).

X1, X2, X3, X4, X5, X6

Pre-treatment covariates (continuous). The true propensity and prognostic models include an X1:X2 interaction.

survey_weight

Survey design weight (inverse selection probability).

Details

Generated by a simulation where:

• Treatment assignment: P(Z=1|X) = \text{logit}^{-1}(0.3 + 0.6 X_1 + 0.4 X_2 - 0.3 X_3 + 0.2 X_1 X_2).

• Outcome model: Y(0) = 1 + X_1 + 0.5 X_2 - 0.3 X_3 + 0.2 X_4 + 0.3 X_1 X_2 + \varepsilon, with treatment effect \tau(X) = 0.8 + 0.2 X_1.

• Survey selection: treatment-dependent (retrospective) with P(S=1|Z,X) = \text{logit}^{-1}(-2 + 0.3 Z + 0.2 X_1 + 0.15 X_2).

Source

Simulated data; see data-raw/make_survey_data.R.

Examples

data(survey_obs)
head(survey_obs)

# Estimate PATE
fit <- wdsmatchATE(Y = survey_obs$Y, X = survey_obs[, 3:8],
                   Z = survey_obs$Z, weights = survey_obs$survey_weight,
                   M = 3, varest = FALSE)
fit

Weighted Double Score Matching Estimator for Population Average Treatment Effect

Description

Estimates the population average treatment effect (PATE) using weighted double score matching with survey design weights. Matching uses propensity probabilities and arm-specific prognostic scores. Missing potential outcomes are imputed by survey-weighted averaging within match sets and aggregated using Hajek normalization. Optional polynomial bias correction adjusts for matching discrepancies. Inference uses fixed-reuse multinomial replication with centered normal Wald intervals.

Usage

wdsmatchATE(
  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

Details

Under retrospective sampling, the propensity score is fitted with survey weights; under prospective sampling it is fitted without survey weights. Prognostic regressions are unweighted within each treatment arm in both designs. These modeling choices require the corresponding identification and sampling assumptions; weighting alone does not establish those assumptions.

Matching uses unweighted pooled standardization of propensity probabilities and the relevant prognostic score. The bias-correction regression uses survey weights and a complete quadratic basis in that arm's own double score: an intercept, both coordinates, their squares, and their interaction. Distances are Euclidean, matching is with replacement, and distance ties are resolved by the original donor row order. Propensity fitting starts from zero coefficients and checks convergence and finite, nonsaturated fitted probabilities.

Multinomial replication draws counts for the original sample units and keeps the original match sets and weighted reuse coefficients fixed. With bias correction enabled, internally estimated nuisance scores are refitted using the counts, with additional survey weighting for retrospective propensity fitting and outcome bias correction. Supplied scores remain fixed. Thus, when scores are supplied, the resulting inference is conditional on them and excludes uncertainty from their external estimation. The corresponding model formula is not used to replace a supplied score during replication.

With B = boots successful replicates, the variance estimate is mean((boot.estimates - mean(boot.estimates))^2), using divisor B. The interval is estimate + c(-1, 1) * qnorm(1 - alpha/2) * se. All requested replicates must succeed. An invalid fit, degenerate score, unsuccessful replicate, or nonfinite calculation raises an error; failed draws are not omitted or replaced by zeros. A successful numerical check does not establish adequate statistical overlap.

With use.bias.correction = FALSE, point estimation uses direct matched imputation without polynomial outcome adjustment, and replication uses the fixed-reuse expression without a bias-correction regression. Unused nuisance scores are not refitted for these raw fixed-match replicates. Matching discrepancies remain, so the asymptotic justification for the bias-corrected estimator does not automatically apply to this option.

Double robustness concerns consistency under the stated identification, sampling, positivity, and regularity assumptions when a required score model is correctly specified; it does not guarantee negligible finite-sample bias or nominal interval coverage in every setting. This interface accepts unit-level weights, not survey strata, clusters, or design-specific replicate weights. The individual-unit multinomial procedure is not a general variance estimator for arbitrary complex survey designs.

Value

A list of class wdsmatch with components:

Examples

data(survey_obs)
fit <- wdsmatchATE(
  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

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

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