nnpiv.diagnostics.relative_wellposedness_diagnostic

nnpiv.diagnostics.relative_wellposedness_diagnostic(A, C, C_prime, *, feature_map='rff', n_features=300, gamma='auto', poly_degree=3, poly_include_bias=False, ridge_alpha=1.0, eta=1e-06, eta_mode='sigma_i', null_eig_atol=1e-10, null_eig_rtol=1e-08, null_leakage_tol=1e-10, random_state=123, feature_builder=None, feature_matrix=None, mask_s=None, mask_t=None, return_top_direction=False, return_details=False)[source]

Compute the finite-dimensional relative well-posedness diagnostic kappa.

Parameters

  • A (array-like of shape (n,) or (n, d_a)) – First-stage endogenous block used to build featureized functions \(b(A)\).

  • C (array-like of shape (n,) or (n, d_c)) – Second-stage instrument block for estimating \(m_T(C)=E[b(A)\\mid C]\).

  • C_prime (array-like of shape (n,) or (n, d_cp)) – First-stage instrument block for estimating \(m_S(C')=E[b(A)\\mid C']\).

  • feature_map ({'rff', 'polynomial'} or callable, default='rff') – Feature construction for \(b(A)\). A callable must return one row per sample in A.

  • n_features (int, default=300) – Number of random Fourier features when feature_map='rff'.

  • gamma (float or 'auto', default='auto') – RBF bandwidth parameter used by random Fourier features.

  • poly_degree (int, default=3) – Polynomial degree when feature_map='polynomial'.

  • poly_include_bias (bool, default=False) – Whether to include the bias term in polynomial features.

  • ridge_alpha (float, default=1.0) – Ridge penalty used in the conditional-mean regressions.

  • eta (float, default=1e-6) – Stabilization magnitude in Sigma_S + eta * R. Must be positive.

  • eta_mode ({'sigma_i', 'identity'}, default='sigma_i') – Stabilizer choice. 'sigma_i' uses the empirical feature second moment Sigma_I; 'identity' uses I.

  • null_eig_atol (float, default=1e-10) – Absolute tolerance for identifying near-null eigendirections of Sigma_s.

  • null_eig_rtol (float, default=1e-8) – Relative tolerance (scaled by max_eig_sigma_s) for near-null eigendirections.

  • null_leakage_tol (float, default=1e-10) – Threshold used to flag nullspace leakage from Sigma_t into the near-null eigenspace of Sigma_s.

  • random_state (int, default=123) – Random seed used by random Fourier feature generation.

  • feature_builder (callable, optional) – Legacy alias for callable feature construction. If provided, called as feature_builder(A).

  • feature_matrix (array-like of shape (n, p), optional) – Precomputed feature matrix for A. If provided, bypasses feature_map construction.

  • mask_s (array-like, optional) – Optional subset selector for the S side. Can be a boolean mask, 0/1 mask, or integer index vector.

  • mask_t (array-like, optional) – Optional subset selector for the T side. Same accepted formats as mask_s.

  • return_top_direction (bool, default=False) – If True, include the maximizing generalized-eigenvector direction and its induced norms in the output.

  • return_details (bool, default=False) – If True, include intermediate matrices and fitted conditional means in the output.

Returns

Dictionary with diagnostic scalars including kappa2, kappa, stability flags, and metadata. Optional keys are added when return_top_direction and/or return_details are enabled.

Return type

dict

Notes

The core target is

\[\kappa_{J,\eta}^2 = \lambda_{\max}\!\left[ (\Sigma_S + \eta R)^{-1/2}\Sigma_T(\Sigma_S + \eta R)^{-1/2} \right],\]

where \(R\) is either I or \(\Sigma_I\).