Cross-Fitting

hddid.make_crossfit_splits(n_obs, n_folds, random_state, *, trim_lower=0.01, trim_upper=0.99)[source]

Generate cross-fitting sample splits for nuisance estimation.

Randomly partitions the sample into K non-overlapping folds of approximately equal size. Each fold serves as the holdout set once, with the remaining observations used for training.

Parameters:

  • n_obs (int) – Total number of observations. Must be >= 2.

  • n_folds (int) – Number of cross-fitting folds K. Must satisfy 2 <= n_folds <= n_obs.

  • random_state (int or None) – Seed for the random number generator controlling the permutation. Use None for non-deterministic splits.

  • trim_lower (float, default 0.01) – Lower propensity score trimming threshold recorded in fold diagnostics.

  • trim_upper (float, default 0.99) – Upper propensity score trimming threshold recorded in fold diagnostics.

Returns:

Contains fold_ids (array of fold assignments per observation) and a list of CrossfitFold objects with train/holdout indices and per-fold diagnostics.

Return type:

CrossfitPlan

Raises:

ValueError – If n_obs < 2, n_folds is out of range, random_state is invalid, or trim bounds are inconsistent.

Notes

Cross-fitting is used to avoid Donsker-class restrictions on the nuisance estimators, as described in Section 3 of Ning, Peng, and Tao (2020). Each fold’s nuisance estimates are computed on the training set and evaluated on the holdout set.

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

class hddid.CrossfitFold(fold_id, train_indices, holdout_indices, diagnostics)[source]

A single cross-fitting fold with train/holdout index partitions.

Each fold serves as one split in the K-fold cross-fitting procedure used for nuisance estimation (Section 3 of the paper).

Parameters:
fold_id

One-based fold identifier.

Type:

int

train_indices

Indices of observations used for first-stage nuisance estimation.

Type:

ndarray of int

holdout_indices

Indices of observations used for second-stage score evaluation.

Type:

ndarray of int

diagnostics

Per-fold propensity trimming and sample size diagnostics.

Type:

FoldDiagnostics

class hddid.CrossfitPlan(fold_ids, folds)[source]

Complete K-fold cross-fitting partition of the sample.

Produced by make_crossfit_splits() and consumed by the nuisance estimation stage to avoid Donsker-class restrictions.

Parameters:
fold_ids

Fold assignment for each observation (1-based).

Type:

ndarray of int, shape (n_obs,)

folds

Ordered list of K fold objects with train/holdout splits.

Type:

list of CrossfitFold