Nuisance Estimation

class hddid.CrossfitNuisanceEstimator(oracle_lane=None, nuisance_estimator=None)[source]

Cross-fitting estimator for nuisance parameters.

Orchestrates K-fold cross-fitting of propensity scores (pi_hat), conditional outcome means (Phi_0, Phi_1), and the propensity weight rho required by the doubly robust score in Eq. (5). Cross-fitting avoids empirical-process (Donsker) restrictions by estimating nuisance functions on training folds and predicting on held-out folds.

Parameters:

  • oracle_lane (str | None)

  • nuisance_estimator (Any | None)

oracle_lane

If set, forces a specific nuisance model lane (e.g. 'oracle').

Type:

str or None

nuisance_estimator

Optional custom sklearn-compatible estimator for nuisance models.

Type:

Any or None

fit(data, splits, *, n_jobs=1)[source]

Estimate nuisance parameters via K-fold cross-fitting.

Fits propensity scores pi_hat, conditional outcome means Phi_0 and Phi_1, and the propensity weight rho using K-fold cross-fitting to avoid Donsker-class restrictions. The resulting NuisancePayload feeds into the Eq. (5) doubly robust score construction.

Parameters:

  • data (ValidatedHDDIDData) – Validated input data with outcomes, treatment, covariates, and basis configuration.

  • splits (CrossfitPlan) – K-fold cross-fitting partition from make_crossfit_splits().

  • n_jobs (int, default 1) – Number of parallel workers for fold processing. Use -1 for all available cores. When 1, folds are processed sequentially.

Returns:

Contains pi_hat, phi0_hat, phi1_hat, rho_hat, valid_mask, fold_diagnostics, and basis configuration.

Return type:

NuisancePayload

Raises:

  • NuisanceTrainingSupportError – If any fold’s training set lacks treated or control obs.

  • ZeroValidHoldoutError – If any fold has zero valid holdout after trimming.

Notes

Implements the first-stage cross-fitting of Section 3 in Ning, Peng & Tao (2020), arXiv preprint arXiv:2009.03151. The weight rho = (D - pi) / [pi(1-pi)] enters the Eq. (5) score.

class hddid.NuisancePayload(pi_hat, phi0_hat, phi1_hat, rho_hat, fold_ids, fold_diagnostics, basis_family, basis_degree, oracle_lane, valid_mask=None)[source]

Cross-fitted first-stage nuisance estimates for Eq. (2.5).

Stores propensity scores, conditional outcome means, and the propensity weight rho required to construct the doubly-robust score in the second stage.

Parameters:
pi_hat

Estimated propensity scores P(D=1|X), strictly in (0, 1).

Type:

ndarray of float, shape (n,)

phi0_hat

Estimated conditional mean E[DeltaY | X, D=0].

Type:

ndarray of float, shape (n,)

phi1_hat

Estimated conditional mean E[DeltaY | X, D=1].

Type:

ndarray of float, shape (n,)

rho_hat

Propensity weight (D - pi) / [pi(1 - pi)].

Type:

ndarray of float, shape (n,)

fold_ids

Cross-fitting fold assignment per observation.

Type:

ndarray of int, shape (n,)

fold_diagnostics

Per-fold trimming and sample size diagnostics.

Type:

list of FoldDiagnostics

basis_family

Sieve basis family used (“polynomial”, “trigonometric”, or “bspline”).

Type:

str

basis_degree

Truncation parameter for the sieve basis.

Type:

int

oracle_lane

Computational lane identifier for R-parity verification.

Type:

str

valid_mask

Mask indicating observations retained after propensity trimming.

Type:

ndarray of bool or None