IdentificationScheme#

class impulso.protocols.IdentificationScheme(*args, **kwargs)[source]#

Bases: Protocol

Contract for structural identification schemes.

Optional capabilities — read by consumers with a getattr default, so minimal third-party schemes implementing only identify and shock_coords keep satisfying this Protocol under runtime checks (ADR-0013):

  • last_diagnostics: dict[str, float] — per-identify()-call diagnostic scalars under scheme-prefixed keys (acceptance rates, first-stage strength, cache-hit flags as 0.0/1.0). A single-call scratchpad, overwritten on each call; IdentifiedVAR.shock_matrix reads it immediately after identify and surfaces the entries onto the result’s attrs. Schemes with nothing to report omit it.

  • _samples_rotations — schemes that sample rotations inside identify (a fresh draw per call, as SignRestriction does) must set this truthy class attribute. Forecast-side scenario machinery reads it via getattr(scheme, “_samples_rotations”, False) and refuses time-varying volatility for such schemes — no single structural coordinate system would span the forecast steps otherwise. Deterministic schemes (Cholesky, ProxySVAR) omit it.

identify(L, var_names, posterior=None, data=None, n_lags=None)[source]#

Identify the structural shock matrix from a Cholesky factor.

Parameters:

  • L (ndarray) – Lower-triangular Cholesky factor of the structural-shock covariance, shape (chains, draws, n_vars, n_vars). Produced by volatility.cholesky_at(…).

  • var_names (list[str]) – Endogenous variable names, in the order they appear in the underlying data.

  • posterior (xr.Dataset | None) – Full posterior xarray Dataset. Optional; provided by the pipeline so schemes that need additional draws (e.g., SignRestriction with restriction_horizon > 0 needs B for the MA recursion) can reach for them. Schemes that only need L may ignore this argument. Schemes that need posterior for context but receive None should raise a clear ValueError.

  • data (VARData | None) – The VARData used at fit time. Optional; provided by the pipeline so schemes that need the observed sample — e.g. ProxySVAR, which reconstructs reduced-form residuals and aligns an instrument by date — can reach for it. Schemes that only need L may ignore this argument.

  • n_lags (int | None) – Lag order of the fitted VAR. Provided alongside data because residual reconstruction needs it.

Returns:

Structural shock matrix array of shape (chains, draws, n_vars, n_vars). Caller is responsible for wrapping into an xarray DataArray with named coords.

Return type:

ndarray

shock_coords(n_vars)[source]#

Return the labels for the shock coordinate of the structural matrix.

The pipeline calls this after identify to label the columns of the structural shock matrix when wrapping into an xarray DataArray.

Parameters:

n_vars (int) – Number of endogenous variables (i.e. width of the structural shock matrix).

Returns:

A list of length n_vars naming each shock column.

Return type:

list[str]