build_ambric_model()

Build the AMBRIC Bayesian state-space model.

Usage

build_ambric_model(
    y_uk,
    y_annual,
    factors,
    macro,
    bridge_signal,
    region_q_on_q=None,
    weight_prior_mean=None,
    weight_prior_concentration=50.0
)

The exogenous mean for latent regional growth is:

mu_exog[t,r] = alpha_r + Lambda[r] @ F[t] + Gamma[r] @ X[t] + delta_r * s[t,r]

where s[t,r] is the quarterly bridge signal from XGBoost + MIDAS and X[t] are the macro series, z-scored inside the model. delta_r has a hierarchical shrinkage prior centred at zero.

Growth rates are decimals (0.005 for 0.5%). Prior scales for the growth-unit parameters are in ambric.utilities.PRIOR_SCALES; each is sampled as a unit-scale *_raw variable and rescaled, so the named parameters in the posterior are in decimal growth units.

Parameters

y_uk: npt.NDArray[np.float64]

UK quarterly growth rates (decimal), shape (T,).

y_annual: npt.NDArray[np.float64]

Regional annual growth rates (decimal), shape (T, R).

factors: npt.NDArray[np.float64]

Extracted factors, shape (T, K).

macro: npt.NDArray[np.float64]

Macro UK series in any units, shape (T, M).

bridge_signal: npt.NDArray[np.float64]

Quarterly bridge signal, shape (T, R).

region_q_on_q: npt.NDArray[np.float64] | None = None

Optional published quarterly regional growth rates, shape (T, R) with NaN in unobserved cells. Values must be decimal growth rates (e.g. 0.005 for 0.5%). When supplied, y_reg is built as a hybrid pm.Deterministic: at every (t, r) with an observed value, y_reg[t, r] is hard-clamped to that value; at NaN cells, y_reg[t, r] equals the sampled latent y_reg_free[t, r]. The clamped values then propagate through the UK aggregation, annual aggregation, and AR(1) dynamics, informing unobserved neighbours rather than competing with them through a likelihood term. Defaults to None (no clamp — backwards compatible).

weight_prior_mean: npt.NDArray[np.float64] | None = None

Prior mean of the regional weights w that aggregate regional growth to national growth, shape (R,), summing to one. Defaults to equal weights.

weight_prior_concentration: float = 50.0

How tightly the prior holds w to its mean. w ~ Dirichlet(concentration * mean), so the prior standard deviation of w_r is sqrt(mean_r * (1 - mean_r) / (concentration + 1)).

Raises

ValueError

If weight_prior_mean has the wrong shape or weight_prior_concentration is not positive.

Returns

pm.model.core.Model

PyMC model object.