Second-Stage Estimation

hddid.estimate_eq31_mainline(score_payload, *, penalty_lambda=0.0, max_iter=1000, tol=1e-10, solver='sklearn')[source]

Solve the Eq. (3.1) partially-linear sieve regression.

Estimates beta and the nonparametric function f(z) from the second-stage model:

S_hat = X’ beta + f(Z) + residual

The procedure projects out the sieve basis from both S_hat and X (Frisch-Waugh), then solves for beta via (optionally penalized) least squares. The sieve coefficients gamma are recovered by projecting (S_hat - X beta) onto the basis.

Parameters:

  • score_payload (ScorePayload) – Doubly-robust score payload from build_score_payload(), containing S_hat, the valid-sample mask, basis matrices, and the covariate matrix restricted to valid observations.

  • penalty_lambda (float, default 0.0) – L1 penalty on beta. When 0.0, ordinary least squares is used (requires full column rank in the projected design). When positive, coordinate-descent Lasso is applied.

  • max_iter (int, default 1000) – Maximum iterations for coordinate descent.

  • tol (float, default 1e-10) – Convergence tolerance for the maximum coordinate update.

  • solver (str, default "sklearn") – Solver backend. “sklearn” delegates to scikit-learn’s Lasso implementation; “builtin” or “native” use the pure-NumPy coordinate-descent implementation. If “sklearn” is requested but scikit-learn is not installed, a warning is issued and the native solver is used as a fallback.

Return type:

tuple[EstimationPayload, HDDIDResult]

Returns:

  • estimation_payload (EstimationPayload) – Contains beta_hat, gamma_hat, fitted values, residuals, and solver metadata.

  • result (HDDIDResult) – Result object populated with parametric and nonparametric point estimates (no inference yet).

Raises:

  • ValueError – If penalty_lambda is negative, tol is non-positive, or solver is not recognized.

  • Eq31ProjectionRankError – If the sieve basis or the projected design matrix lacks full column rank (when penalty_lambda == 0).

  • Eq31SolverConvergenceError – If coordinate descent fails to converge and KKT conditions are not satisfied.

Notes

Implements Eq. (3.1) from Ning, Peng, and Tao (2020). Reference: Ning, Peng, and Tao (2020), arXiv preprint arXiv:2009.03151.

class hddid.EstimationPayload(beta_hat, gamma_hat, fitted_f_valid, second_stage_prediction_valid, residual_valid, projection_x_valid, f_hat_at_z0, optimization_metadata)[source]

Second-stage Eq. (3.1) partially-linear sieve regression output.

Contains the estimated parametric coefficients beta, sieve coefficients gamma, fitted nonparametric function values, and residuals from S_hat = X’beta + f(Z) + epsilon.

Parameters:
beta_hat

Estimated high-dimensional parametric coefficients.

Type:

ndarray of float, shape (p,)

gamma_hat

Estimated sieve basis coefficients for f(z).

Type:

ndarray of float, shape (L,)

fitted_f_valid

Fitted nonparametric component f_hat on valid observations.

Type:

ndarray of float, shape (n_valid,)

second_stage_prediction_valid

Full second-stage prediction X’beta + f_hat on valid observations.

Type:

ndarray of float, shape (n_valid,)

residual_valid

Second-stage residuals S_hat - X’beta - f_hat.

Type:

ndarray of float, shape (n_valid,)

projection_x_valid

Covariates projected orthogonal to the sieve basis (Frisch-Waugh residualized design).

Type:

ndarray of float, shape (n_valid, p)

f_hat_at_z0

Estimated f(z) evaluated at the z0 grid points.

Type:

ndarray of float, shape (G,)

optimization_metadata

Solver diagnostics including convergence status, penalty, and dimension information.

Type:

dict

class hddid.Eq31ProjectionRankError(message, *, metadata)[source]

Raised when an Eq. (3.1) projection design is not identified.

Parameters:
class hddid.Eq31SolverConvergenceError(message, *, metadata)[source]

Raised when the Eq. (3.1) numerical solver fails to converge.

Parameters: