Protocols¶
Protocol definitions for extensible components.
IdentificationScheme
¶
Bases: Protocol
Contract for structural identification schemes.
identify(L, var_names, posterior=None)
¶
Identify the structural shock matrix from a Cholesky factor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
L
|
ndarray
|
Lower-triangular Cholesky factor of the structural-shock
covariance, shape (chains, draws, n_vars, n_vars). Produced
by |
required |
var_names
|
list[str]
|
Endogenous variable names, in the order they appear in the underlying data. |
required |
posterior
|
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 |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Structural shock matrix array of shape (chains, draws, n_vars, n_vars). |
ndarray
|
Caller is responsible for wrapping into an xarray DataArray with |
ndarray
|
named coords. |
shock_coords(n_vars)
¶
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:
| Name | Type | Description | Default |
|---|---|---|---|
n_vars
|
int
|
Number of endogenous variables (i.e. width of the structural shock matrix). |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
A list of length |
Prior
¶
Bases: Protocol
Contract for prior specifications.
Sampler
¶
Bases: Protocol
Contract for posterior sampling strategies.
VolatilityProcess
¶
Bases: Protocol
Contract for volatility processes.
A VolatilityProcess owns the construction of the structural-shock covariance Σ_t — for constant adapters, Σ is shared across time; for stochastic adapters, Σ_t evolves. The seam's primary output is the lower-triangular Cholesky factor L_t such that Σ_t = L_t @ L_t.T. See docs/adr/0001-volatility-process-seam-exposes-cholesky-factor.md.
Adapters own their downstream computation: time-t query and
forward simulation for forecasts.
is_time_varying
instance-attribute
¶
Whether Σ_t evolves over time. False for homoscedastic adapters
(Constant); True for stochastic-volatility adapters. Drives
branching in FittedVAR.sigma and IdentifiedVAR.historical_decomposition
so neither has to string-sniff the adapter name.
build_pymc_latent(n_vars, T, data=None)
¶
Register volatility latent variables in the active PyMC model.
Returns the lower-triangular Cholesky factor as a PyTensor variable. For constant volatility, shape is (n_vars, n_vars). For stochastic volatility, shape is (T, n_vars, n_vars).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_vars
|
int
|
Number of endogenous variables. |
required |
T
|
int
|
Number of in-sample observations (after lag trimming). |
required |
data
|
ndarray | None
|
Optional per-variable series of shape |
None
|
cholesky_at(posterior, t)
¶
Posterior draws of the Cholesky factor at time t.
Returns shape (chains, draws, n_vars, n_vars). For constant
volatility, t is ignored. For stochastic volatility, indexes
into the time dimension; t=None defaults to the most recent
period.
cholesky_path(posterior, T)
¶
Posterior draws of the Cholesky factor path across all in-sample t.
Returns shape (chains, draws, T, n_vars, n_vars). For constant
volatility, broadcasts the time-invariant L across the requested
T. For stochastic volatility, indexes into the latent log-vol
posterior to construct L_t for each t.
forecast_cholesky_path(posterior, steps, rng)
¶
Posterior-predictive Cholesky factors for steps ahead.
Returns shape (chains, draws, steps, n_vars, n_vars). For constant
volatility, broadcasts the constant L across steps. For stochastic
volatility, simulates forward from posterior dynamics.