Score Construction

hddid.build_score_payload(data, nuisance_payload)[source]

Construct the doubly-robust score for Eq. (3.1) estimation.

Assembles the influence-function-based score S_hat from the estimated nuisance parameters (propensity score, conditional outcome means) and the observed outcomes, following Eq. (2.5) and (2.7) of the paper.

The score is defined as:

S_hat_i = rho_i * (Delta Y_i - (1 - pi_i) phi1_i - pi_i phi0_i)

where rho_i = (D_i - pi_i) / [pi_i (1 - pi_i)] is the propensity weight.

Parameters:

  • data (ValidatedHDDIDData) – Validated input data containing outcomes, treatment, covariates, the nonparametric variable z, evaluation grid z0, and basis configuration.

  • nuisance_payload (NuisancePayload) – Cross-fitted nuisance estimates including pi_hat (propensity scores), phi0_hat and phi1_hat (conditional means), rho_hat (propensity weights), valid_mask, and fold assignments.

Returns:

Contains the full-sample and valid-sample scores (s_hat, s_hat_valid), basis matrices for the sieve projection, the evaluation basis for computing f(z0), and all nuisance components needed downstream.

Return type:

ScorePayload

Raises:

ValueError – If nuisance_payload dimensions do not align with data, or if basis_family / basis_degree disagree between inputs.

Notes

Implements the doubly-robust score from Eq. (2.5) and (2.7) of Ning, Peng, and Tao (2020). The propensity trimming mask is inherited from nuisance_payload.valid_mask.

Reference: Ning, Peng, and Tao (2020), arXiv preprint arXiv:2009.03151.

class hddid.ScorePayload(delta_y, s_hat, s_hat_valid, valid_mask, fold_ids, fold_diagnostics, basis_family, basis_degree, oracle_lane, basis_matrix, x_valid, basis_valid_full, basis_design_valid, evaluation_basis, pi_hat, phi0_hat, phi1_hat, rho_hat, intercept_dropped_for_design)[source]

Doubly-robust influence-function score for Eq. (3.1) estimation.

Assembles the score S_hat = rho * (DeltaY - (1-pi)*phi1 - pi*phi0) from cross-fitted nuisance estimates and organizes the basis matrices needed for the partially-linear sieve regression.

Parameters:
delta_y

First-differenced outcome Y1 - Y0.

Type:

ndarray of float, shape (n,)

s_hat

Full-sample doubly-robust score.

Type:

ndarray of float, shape (n,)

s_hat_valid

Score restricted to propensity-trimmed observations.

Type:

ndarray of float, shape (n_valid,)

valid_mask

Boolean mask identifying trimmed-valid observations.

Type:

ndarray of bool, shape (n,)

fold_ids

Cross-fitting fold assignments.

Type:

ndarray of int, shape (n,)

fold_diagnostics

Per-fold trimming diagnostics.

Type:

list of FoldDiagnostics

basis_family

Sieve basis family.

Type:

str

basis_degree

Sieve truncation parameter.

Type:

int

oracle_lane

Computational lane for R-parity verification.

Type:

str

basis_matrix

Full-sample sieve basis matrix.

Type:

ndarray of float, shape (n, L)

x_valid

Covariates restricted to valid observations.

Type:

ndarray of float, shape (n_valid, p)

basis_valid_full

Basis matrix restricted to valid observations.

Type:

ndarray of float, shape (n_valid, L)

basis_design_valid

Basis design matrix (intercept dropped if present).

Type:

ndarray of float, shape (n_valid, L’)

evaluation_basis

Basis evaluated at the z0 grid for f(z0) prediction.

Type:

ndarray of float, shape (G, L)

pi_hat

Propensity scores from nuisance estimation.

Type:

ndarray of float, shape (n,)

phi0_hat

Conditional mean estimates for controls.

Type:

ndarray of float, shape (n,)

phi1_hat

Conditional mean estimates for treated.

Type:

ndarray of float, shape (n,)

rho_hat

Propensity weights.

Type:

ndarray of float, shape (n,)

intercept_dropped_for_design

Whether the leading intercept column was removed from basis_valid_full to form basis_design_valid.

Type:

bool