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)

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)\).

Carray-like of shape (n,) or (n, d_c)

Second-stage instrument block for estimating \(m_T(C)=E[b(A)\\mid C]\).

C_primearray-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_featuresint, default=300

Number of random Fourier features when feature_map='rff'.

gammafloat or ‘auto’, default=’auto’

RBF bandwidth parameter used by random Fourier features.

poly_degreeint, default=3

Polynomial degree when feature_map='polynomial'.

poly_include_biasbool, default=False

Whether to include the bias term in polynomial features.

ridge_alphafloat, default=1.0

Ridge penalty used in the conditional-mean regressions.

etafloat, 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_atolfloat, default=1e-10

Absolute tolerance for identifying near-null eigendirections of Sigma_s.

null_eig_rtolfloat, default=1e-8

Relative tolerance (scaled by max_eig_sigma_s) for near-null eigendirections.

null_leakage_tolfloat, default=1e-10

Threshold used to flag nullspace leakage from Sigma_t into the near-null eigenspace of Sigma_s.

random_stateint, default=123

Random seed used by random Fourier feature generation.

feature_buildercallable, optional

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

feature_matrixarray-like of shape (n, p), optional

Precomputed feature matrix for A. If provided, bypasses feature_map construction.

mask_sarray-like, optional

Optional subset selector for the S side. Can be a boolean mask, 0/1 mask, or integer index vector.

mask_tarray-like, optional

Optional subset selector for the T side. Same accepted formats as mask_s.

return_top_directionbool, default=False

If True, include the maximizing generalized-eigenvector direction and its induced norms in the output.

return_detailsbool, 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\).