Inference

hddid.estimate_parametric_inference(score_payload, estimation_payload, *, result=None, xi=None, alpha=0.05, lambda_prime=0.0, max_threshold_steps=25)[source]

Perform debiased inference on the parametric component beta.

Constructs asymptotically normal confidence intervals for linear functionals xi’ beta using the debiasing approach of Eq. (4.1). The debiasing direction w is obtained by solving the Eq. (4.2) sparse optimization problem.

Parameters:

score_payload (ScorePayload) – Doubly-robust score payload.
estimation_payload (EstimationPayload) – Output from estimate_eq31_mainline() containing beta_hat, residuals, and the projected covariate matrix.
result (HDDIDResult or None, default None) – Existing result object to augment with inference outputs. When None, a fresh result is created.
xi (ndarray of shape (k, p) or None, default None) – Target matrix for inference. When None, defaults to I_p (componentwise inference on each element of beta).
alpha (float, default 0.05) – Significance level for the two-sided confidence intervals.
lambda_prime (float, default 0.0) – Relaxation parameter for the Eq. (4.2) constraint.
max_threshold_steps (int, default 25) – Maximum threshold steps passed to the sparse direction solver.

Return type:

tuple[ParametricInferencePayload, HDDIDResult]

Returns:

payload (ParametricInferencePayload) – Contains t_hat (debiased estimates), standard errors, confidence intervals, and all intermediate quantities.
result (HDDIDResult) – Updated result with parametric standard errors and confidence intervals.

Raises:

InvalidInferenceInputError – If payloads are inconsistent or dimension mismatches occur.
NonpositiveVarianceError – If the estimated asymptotic variance is non-positive.
SparseDirectionInfeasibleError – If the Eq. (4.2) solver cannot find a feasible direction.

Notes

Implements Eq. (4.1) and (4.2) from Ning, Peng, and Tao (2020). The debiased estimator is:

t_hat_j = xi_j’ beta_hat - w_j’ (1/n) sum_i [epsilon_i X_tilde_i]

with asymptotic variance w_j’ Omega_beta w_j / n. Reference: Ning, Peng, and Tao (2020), arXiv preprint arXiv:2009.03151.

hddid.estimate_nonparametric_inference(score_payload, estimation_payload, *, result=None, alpha=0.05, lambda_double_prime=0.0, max_threshold_steps=25, n_boot=1000, random_state=None, allow_omega_f_fallback=False)[source]

Perform debiased inference on the nonparametric function f(z).

Constructs pointwise confidence intervals and a simultaneous confidence band for the nonparametric component f(z) using the debiasing approach of Theorem 3.

The procedure:

Solves the Eq. (12) projection matrix M to orthogonalize the sieve basis against high-dimensional covariates.
Computes the orthogonalized basis psi_tilde = psi - M*X.
Estimates Sigma_f = E_n[psi_tilde psi'] and Omega_f = E_n[sigma_i^2 psi psi'] - M E_n[sigma_i^2 X X'] M'.
Forms the sandwich V_f = Sigma_f^{-1} Omega_f Sigma_f^{-1}.
Debiases: bar_gamma = gamma - Sigma_f^{-1} score_moment.
Computes pointwise CI bar_f(z) +/- z_{1-alpha/2} * sqrt(psi(z)' V_f psi(z) / n).
Computes uniform band via Gaussian bootstrap over the grid.

Parameters:

score_payload (ScorePayload) – Doubly-robust score payload containing basis matrices and valid-sample covariates.
estimation_payload (EstimationPayload) – Output from estimate_eq31_mainline() containing gamma_hat, residuals, and beta_hat.
result (HDDIDResult or None, default None) – Existing result to augment with inference outputs.
alpha (float, default 0.05) – Significance level for confidence intervals and uniform band.
lambda_double_prime (float, default 0.0) – Relaxation parameter for the Eq. (12) constraint.
max_threshold_steps (int, default 25) – Maximum threshold steps for the projection solver.
n_boot (int, default 1000) – Number of bootstrap replications for the uniform band.
random_state (int or None, default None) – Random seed for the Gaussian bootstrap.
allow_omega_f_fallback (bool, default False) – Whether to allow fallback when Omega_f is not PSD. Currently must be False (paper-difference is required).

Return type:

tuple[NonparametricInferencePayload, HDDIDResult]

Returns:

payload (NonparametricInferencePayload) – Contains bar_gamma_hat, bar_f_at_z0, pointwise CI, uniform band, and all intermediate quantities (M, Sigma_f, Omega_f, V_f).
result (HDDIDResult) – Updated result with nonparametric standard errors and confidence intervals.

Raises:

InvalidInferenceInputError – If payloads are inconsistent or dimensions mismatch.
SparseDirectionInfeasibleError – If the Eq. (12) projection solver is infeasible.
SingularCovarianceError – If Sigma_f_hat is singular.
NonpositiveVarianceError – If Omega_f or the pointwise variance is non-positive.
MissingEvaluationGridError – If the evaluation grid is empty.

Notes

Implements Eq. (12) and Theorem 3 from Ning, Peng & Tao (2020). The asymptotic normality result is sqrt(n) sigma_z^{-1/2} (f_bar(z) - f_0(z)) ->_d N(0, 1).

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

hddid.solve_eq42_sparse_direction(*, sigma_tilde_x_hat, xi, lambda_prime, max_threshold_steps=25)[source]

Solve the Eq. (4.2) sparse direction optimization.

For each row of xi, finds a direction vector w that minimizes ||w||_1 subject to the constraint ||xi_j + w_j’ Sigma_tilde_X||_inf <= lambda’.

This direction is used to debias the parametric estimate in the high-dimensional setting where direct inversion of Sigma_tilde_X is infeasible.

Parameters:

sigma_tilde_x_hat (ndarray of shape (p, p)) – Estimated covariance of the projected (residualized) covariates. Must be symmetric and positive semidefinite.
xi (ndarray of shape (k, p) or (p, p)) – Target matrix specifying which linear functionals of beta to perform inference on. When None is passed to estimate_parametric_inference(), defaults to the identity matrix (componentwise inference).
lambda_prime (float) – Relaxation parameter controlling the constraint tolerance. Typically set to 0 for exact solutions.
max_threshold_steps (int, default 25) – Maximum threshold search steps (reserved for alternative solvers; the LP solver uses this as metadata only).

Return type:

tuple[ndarray, dict[str, object]]

Returns:

w_hat (ndarray of shape (k, p)) – Optimal sparse direction matrix, one row per xi target.
metadata (dict) – Solver diagnostics including feasibility status, constraint violations, and per-row metadata.

Raises:

ValueError – If sigma_tilde_x_hat is not square, not symmetric, or not positive semidefinite; if xi has incompatible dimensions.
SparseDirectionInfeasibleError – If the linear program fails to find a feasible solution for any target row.

Notes

Implements Eq. (4.2) from Ning, Peng, and Tao (2020). The optimization is solved via linear programming (HiGHS). Reference: Ning, Peng, and Tao (2020), arXiv preprint arXiv:2009.03151.

hddid.solve_eq43_projection_matrix(*, sigma_x_hat, cross_moment_hat, lambda_double_prime, max_threshold_steps=25)[source]

Solve the Eq. (4.3) sparse projection matrix optimization.

For each row of cross_moment_hat, finds a projection vector m that minimizes ||m||_1 subject to the constraint ||m’ Sigma_X - cross_j||_inf <= lambda’’.

The projection matrix M is used to orthogonalize the sieve basis against high-dimensional covariates for nonparametric inference.

Parameters:

sigma_x_hat (ndarray of shape (p, p)) – Estimated covariance of the covariates X’X / n. Must be symmetric and positive semidefinite.
cross_moment_hat (ndarray of shape (L, p)) – Cross-moment matrix psi’X / n, where psi is the sieve basis (L = basis dimension, p = covariate dimension).
lambda_double_prime (float) – Relaxation parameter controlling the constraint tolerance.
max_threshold_steps (int, default 25) – Maximum threshold search steps (metadata for alternative solvers).

Return type:

tuple[ndarray, dict[str, object]]

Returns:

m_hat (ndarray of shape (L, p)) – Optimal sparse projection matrix, one row per basis function.
metadata (dict) – Solver diagnostics including feasibility status, constraint violations, and per-row metadata.

Raises:

ValueError – If sigma_x_hat is not square, not symmetric, or not positive semidefinite; if cross_moment_hat has incompatible dimensions.
SparseDirectionInfeasibleError – If the linear program fails to find a feasible solution for any basis row.

Notes

Implements Eq. (4.3) from Ning, Peng, and Tao (2020). The optimization is solved row-by-row via linear programming (HiGHS). The resulting M orthogonalizes the basis against X: psi_tilde = psi - M X, enabling valid nonparametric inference in the presence of high-dimensional confounders.

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

hddid.diagnose_nonparametric_omega_f(score_payload, estimation_payload, nonparametric_payload)[source]

Return paper-difference Omega_f component diagnostics for a valid payload.

Return type:

dict[str, object]

Parameters:

score_payload (ScorePayload)
estimation_payload (EstimationPayload)
nonparametric_payload (NonparametricInferencePayload)

Exceptions

class hddid.InferenceComputationError(message, *, metadata=None)[source]

Base error for inference computation failures.

Parameters:

message (str)
metadata (dict[str, object] | None)

class hddid.InvalidInferenceInputError(message, *, metadata=None)[source]

Raised when inference inputs are invalid or inconsistent.

Parameters:

message (str)
metadata (dict[str, object] | None)

class hddid.MissingEvaluationGridError(message, *, metadata=None)[source]

Raised when a non-empty evaluation grid is required but missing.

Parameters:

message (str)
metadata (dict[str, object] | None)

class hddid.SingularCovarianceError(message, *, metadata=None)[source]

Raised when a covariance matrix is singular or rank-deficient.

Parameters:

message (str)
metadata (dict[str, object] | None)

class hddid.SparseDirectionInfeasibleError(message, *, metadata=None)[source]

Raised when the Eq. (11) or Eq. (12) LP is infeasible.

Parameters:

message (str)
metadata (dict[str, object] | None)

class hddid.NonpositiveVarianceError(message, *, metadata=None)[source]

Raised when the estimated variance is non-positive.

Parameters:

message (str)
metadata (dict[str, object] | None)

Payload Classes

class hddid.ParametricInferencePayload(xi, t_hat, w_hat, sigma_tilde_x_hat, omega_beta_hat, score_moment, asymptotic_variance_hat, standard_errors, confidence_interval, alpha, basis_family, basis_degree, oracle_lane, optimization_metadata)[source]

Debiased inference output for the parametric component beta, Eq. (4.1).

Contains the debiased point estimates t_hat, asymptotic standard errors, and confidence intervals for linear functionals xi’beta, constructed via the Eq. (4.2) sparse direction w.

Parameters:

xi (ndarray)
t_hat (ndarray)
w_hat (ndarray)
sigma_tilde_x_hat (ndarray)
omega_beta_hat (ndarray)
score_moment (ndarray)
asymptotic_variance_hat (ndarray)
standard_errors (ndarray)
confidence_interval (ConfidenceInterval)
alpha (float)
basis_family (str)
basis_degree (int)
oracle_lane (str)
optimization_metadata (dict[str, object])

xi

Target matrix specifying linear functionals of beta.

Type:: ndarray of float, shape (k, p)

t_hat

Debiased point estimates xi’beta - w’ score_moment.

Type:: ndarray of float, shape (k,)

w_hat

Sparse debiasing direction from Eq. (4.2) optimization.

Type:: ndarray of float, shape (k, p)

sigma_tilde_x_hat

Estimated covariance of the projected covariates.

Type:: ndarray of float, shape (p, p)

omega_beta_hat

Long-run variance matrix for the parametric score.

Type:: ndarray of float, shape (p, p)

score_moment

Sample mean of the residualized score epsilon * X_tilde.

Type:: ndarray of float, shape (p,)

asymptotic_variance_hat

Estimated asymptotic variance w’ Omega_beta w per target.

Type:: ndarray of float, shape (k,)

standard_errors

Standard errors sqrt(asymptotic_variance / n).

Type:: ndarray of float, shape (k,)

confidence_interval

Two-sided confidence intervals for each target.

Type:: ConfidenceInterval

alpha

Significance level for the confidence intervals.

Type:: float

basis_family

Sieve basis family.

Type:: str

basis_degree

Sieve truncation parameter.

Type:: int

oracle_lane

Computational lane identifier.

Type:: str

optimization_metadata

Solver diagnostics for the Eq. (4.2) direction problem.

Type:: dict

class hddid.NonparametricInferencePayload(m_hat, sigma_x_hat, cross_moment_hat, orthogonal_basis_valid, sigma_f_hat, omega_f_hat, v_f_hat, score_moment, bar_gamma_hat, evaluation_basis, bar_f_at_z0, sigma_z_hat, covariance_at_grid, uniform_standardization, pointwise_confidence_interval, uniform_band, alpha, basis_family, basis_degree, oracle_lane, optimization_metadata)[source]

Inference output for the nonparametric function f(z), Eq. (4.3).

Contains the debiased sieve estimates bar_gamma, pointwise confidence intervals, and uniform confidence bands for f evaluated at the z0 grid, using the Eq. (4.3) sparse projection M to orthogonalize the basis against high-dimensional covariates.

Parameters:

m_hat (ndarray)
sigma_x_hat (ndarray)
cross_moment_hat (ndarray)
orthogonal_basis_valid (ndarray)
sigma_f_hat (ndarray)
omega_f_hat (ndarray)
v_f_hat (ndarray)
score_moment (ndarray)
bar_gamma_hat (ndarray)
evaluation_basis (ndarray)
bar_f_at_z0 (ndarray)
sigma_z_hat (ndarray)
covariance_at_grid (ndarray)
uniform_standardization (ndarray)
pointwise_confidence_interval (ConfidenceInterval)
uniform_band (UniformBand)
alpha (float)
basis_family (str)
basis_degree (int)
oracle_lane (str)
optimization_metadata (dict[str, object])

m_hat

Sparse projection matrix from Eq. (4.3) optimization.

Type:: ndarray of float, shape (L, p)

sigma_x_hat

Estimated covariate covariance X’X / n.

Type:: ndarray of float, shape (p, p)

cross_moment_hat

Cross-moment psi’X / n between basis and covariates.

Type:: ndarray of float, shape (L, p)

orthogonal_basis_valid

Orthogonalized basis psi_tilde = psi - M X on valid obs.

Type:: ndarray of float, shape (n_valid, L)

sigma_f_hat

Covariance of the orthogonalized basis.

Type:: ndarray of float, shape (L, L)

omega_f_hat

Long-run variance for the nonparametric score.

Type:: ndarray of float, shape (L, L)

v_f_hat

Sandwich matrix Sigma_f^{-1} Omega_f Sigma_f^{-1}.

Type:: ndarray of float, shape (L, L)

score_moment

Sample mean of the orthogonalized basis score.

Type:: ndarray of float, shape (L,)

bar_gamma_hat

Debiased sieve coefficients gamma - Sigma_f^{-1} score.

Type:: ndarray of float, shape (L,)

evaluation_basis

Basis evaluated at the z0 grid.

Type:: ndarray of float, shape (G, L)

bar_f_at_z0

Debiased f estimates at the z0 grid.

Type:: ndarray of float, shape (G,)

sigma_z_hat

Pointwise standard errors at the z0 grid.

Type:: ndarray of float, shape (G,)

covariance_at_grid

Joint covariance of f estimates at the z0 grid.

Type:: ndarray of float, shape (G, G)

uniform_standardization

Standardization factors sqrt(diag(covariance_at_grid)).

Type:: ndarray of float, shape (G,)

pointwise_confidence_interval

Pointwise confidence intervals for f(z0).

Type:: ConfidenceInterval

uniform_band

Simultaneous confidence band over the z0 grid.

Type:: UniformBand

alpha

Significance level.

Type:: float

basis_family

Sieve basis family.

Type:: str

basis_degree

Sieve truncation parameter.

Type:: int

oracle_lane

Computational lane identifier.

Type:: str

optimization_metadata

Solver diagnostics for the Eq. (4.3) projection problem.

Type:: dict