from ambric import Ambric
from ambric.utilities import generate_realistic_simulated_dataHow to use AMBRIC
Let’s import the package.
As a user, we have to bring a few things to the party. The first, of course, is data, which we will simulate.
Let’s set-up some simulated data. We’ll specify how many underlying factors are driving regional dynamics first.
n_factors = 2
df = generate_realistic_simulated_data(n_factors=n_factors, R=12)2026-11-17 22:53:46.111 | INFO | ambric.utilities:generate_realistic_simulated_data:130 - Simulating Data: T=130, R=12, J=4, Macro=2, Factors=2, lag=6
Data that are input into the model must have this structure:
df.sample(10)| datetime | value | region | measure | |
|---|---|---|---|---|
| 1177 | 1991-12-31 | -0.077809 | region_02 | regional_covar_01 |
| 784 | 2000-03-31 | NaN | region_06 | gva_q_on_4q |
| 2822 | 2013-03-31 | -0.153500 | region_05 | regional_covar_01 |
| 2493 | 1995-12-31 | 0.254217 | region_04 | regional_covar_03 |
| 2843 | 2018-06-30 | -0.266745 | region_05 | regional_covar_01 |
| 2461 | 2020-06-30 | -0.192657 | region_04 | regional_covar_02 |
| 3436 | 2004-03-31 | -0.061521 | region_06 | regional_covar_02 |
| 5563 | 2015-12-31 | 0.125899 | region_10 | regional_covar_02 |
| 1795 | 2016-06-30 | 0.133326 | region_03 | regional_covar_01 |
| 4445 | 1996-06-30 | 0.177914 | region_08 | regional_covar_02 |
The user must also specify the details of what the model will use. In particular, which regional variables, macroeconomic indicators (these should always have the aggregate region/top level geography as their region), and regional covariates to use. We’ll just use all of these:
aggregation_region = "uk"
region_names = [x for x in df["region"].unique() if x != aggregation_region]
macro_names = [x for x in df["measure"].unique() if "macro" in x]
region_covariate_names = [x for x in df["measure"].unique() if "regional_covar" in x]Growth rates must be decimals (0.005 for 0.5%). Rows can be in any order. The quarterly growth series for the aggregate region must be complete, with no missing quarters, and so must the macro series. Regional data need rows only where a value exists: annual regional growth is given at year-end quarters, and other quarters can be left out or set to nan.
In a typical use case, you will have non-nan quarters of quarterly growth at the aggregate region (eg the UK) for which the regional data are nan. Those nans in the time period between is what we are nowcasting.
If you know each region’s share of the national total (for example its share of output), pass it as region_weights, a dictionary keyed by region name. It centres the prior on the weights that turn regional growth into national growth. Without it, AMBRIC estimates the shares from the growth data, which is much less precise. How tightly the weights are held to these shares is set by region_weights_concentration (larger is tighter; the default is 500 for supplied shares and 50 for estimated ones). The simulated regions are equally sized, so here we say so:
region_weights = {region: 1.0 for region in region_names}Okay, we’re ready to build a AMBRIC model!
amb = Ambric(
df,
macro_names,
region_names,
region_covariate_names,
n_factors=n_factors,
region_weights=region_weights,
)
amb2026-11-17 22:53:46.176 | INFO | ambric:__init__:1143 - Initialising ambric model.
2026-11-17 22:53:46.202 | INFO | ambric.utilities:prep_data_for_model_run:443 - Prepping data for model run.
2026-11-17 22:53:46.232 | INFO | ambric.utilities:prep_data_for_model_run:541 - Per-region trailing NaN counts: [6 6 6 6 6 6 6 6 6 6 6 6]; using modal lag_qtrs=6
2026-11-17 22:53:46.243 | INFO | ambric.utilities:prep_data_for_model_run:560 - Input lengths after data prep:
2026-11-17 22:53:46.243 | INFO | ambric.utilities:prep_data_for_model_run:561 - Quarterly gva_q_on_q: T_max = 130
2026-11-17 22:53:46.244 | INFO | ambric.utilities:prep_data_for_model_run:562 - Annual gva_q_on_4q: T_max = 130
2026-11-17 22:53:46.244 | INFO | ambric.utilities:prep_data_for_model_run:563 - Macro series: 2
2026-11-17 22:53:46.245 | INFO | ambric.utilities:prep_data_for_model_run:564 - Regional covariate series: 4 per region
2026-11-17 22:53:46.249 | INFO | ambric:__init__:1257 - Prior centre for regional weights (supplied): region_00=0.083, region_01=0.083, region_02=0.083, region_03=0.083, region_04=0.083, region_05=0.083, region_06=0.083, region_07=0.083, region_08=0.083, region_09=0.083, region_10=0.083, region_11=0.083
------------ambric Model-------------
Model ID: 005057f5
Parameters:
Time periods (quarters), T=130
Earliest: 1990-March; Latest: 2022-June
Regions, R=12
Macroeconomic series, M=2
Regional indicators, J=4
n_factors=2
Model fitted: No
-------------------------------------
Printing the model shows its dimensions (quarters, regions, macro series, regional indicators and factors) and the period it covers. It also tells us it isn’t fitted, so let’s sort that. We recommend using at least 100k iterations.
n_iterations = 200000
n_posterior_samples = 3000
amb.fit(n_iterations, n_posterior_samples)2026-11-17 22:53:46.257 | INFO | ambric:fit:1364 -
[1/5] Extracting 2 factors from indicator panel...
2026-11-17 22:53:46.258 | INFO | ambric:extract_factors_from_panel:225 - Creating factors:
2026-11-17 22:53:46.259 | INFO | ambric:extract_factors_from_panel:226 - From 4 series per region, creating...
2026-11-17 22:53:46.260 | INFO | ambric:extract_factors_from_panel:227 - ...2 factors
2026-11-17 22:53:46.265 | INFO | ambric:extract_factors_from_panel:247 - FA: Extracted 2 factors. Approximate explained variance: 9.3%
2026-11-17 22:53:46.265 | DEBUG | ambric:extract_factors_from_panel:250 - Noise variances range: 0.784 - 0.999
2026-11-17 22:53:46.266 | INFO | ambric:fit:1372 -
[2/5] Training XGBoost on annual regional growth...
2026-11-17 22:53:46.267 | INFO | ambric:train_xgboost_annual:378 - XGBoost: Training on 360 region-year observations (6 features: 4 regional indicators + 2 macro).
2026-11-17 22:53:47.918 | INFO | ambric:train_xgboost_annual:453 - XGBoost: out-of-fold (leave-one-year-out) RMSE = 0.016617; in-sample RMSE = 0.008158
2026-11-17 22:53:47.920 | INFO | ambric:fit:1382 -
[3/5] Fitting MIDAS bridge equation...
2026-11-17 22:53:48.560 | DEBUG | ambric:fit_bridge_equation:670 - Bridge equation: Estimated Almon params theta=(-2.7804, 0.8280)
2026-11-17 22:53:48.561 | DEBUG | ambric:fit_bridge_equation:673 - Bridge equation: MIDAS weights = [0.6029, 0.0856, 0.0636, 0.2479] (Q1->Q4)
2026-11-17 22:53:48.567 | INFO | ambric:fit_bridge_equation:717 - Bridge: R² = 0.5454, RMSE = 0.013746 (fitted to the XGBoost predictions it was given; these are out-of-fold when they come from train_xgboost_annual)
2026-11-17 22:53:48.567 | DEBUG | ambric:fit_bridge_equation:722 - Bridge: delta (XGBoost loading) = 0.0819
2026-11-17 22:53:48.568 | DEBUG | ambric:fit_bridge_equation:723 - Bridge: intercept = 0.0005
2026-11-17 22:53:48.578 | DEBUG | ambric:fit_bridge_equation:752 - Bridge equation: Quarterly signal shape = (130, 12), mean = 0.000233, std = 0.005340
2026-11-17 22:53:48.579 | INFO | ambric:fit:1399 -
[4/5] Building AMBRIC Bayesian model...
2026-11-17 22:53:48.579 | INFO | ambric:build_ambric_model:854 - Building AMBRIC model:
2026-11-17 22:53:48.580 | DEBUG | ambric:build_ambric_model:855 - 2 factors, 2 macro series, 130 quarters, 12 regions
2026-11-17 22:53:48.581 | DEBUG | ambric:build_ambric_model:856 - Bridge signal: shape (130, 12)
/home/runner/work/ambric/ambric/.venv/lib/python3.14/site-packages/pymc/model/core.py:1316: ImputationWarning: Data in obs_annual contains missing values and will be automatically imputed from the sampling distribution.
warnings.warn(impute_message, ImputationWarning)
2026-11-17 22:53:48.819 | INFO | ambric:fit:1412 -
[5/5] Running variational inference (200000 iterations)...
/home/runner/work/ambric/ambric/.venv/lib/python3.14/site-packages/pytensor/link/c/cmodule.py:2986: UserWarning: PyTensor could not link to a BLAS installation. Operations that might benefit from BLAS will be severely degraded.
This usually happens when PyTensor is installed via pip. We recommend it be installed via conda/mamba/pixi instead.
Alternatively, you can use an experimental backend such as Numba or JAX that perform their own BLAS optimizations, by setting `pytensor.config.mode == 'NUMBA'` or passing `mode='NUMBA'` when compiling a PyTensor function.
For more options and details see https://pytensor.readthedocs.io/en/latest/troubleshooting.html#how-do-i-configure-test-my-blas-library
warnings.warn(
WARNING (pytensor.tensor.blas): Using NumPy C-API based implementation for BLAS functions.
WARNING (pytensor.tensor.blas): Using NumPy C-API based implementation for BLAS functions.
2026-11-17 22:55:41.206 | INFO | ambric.diagnostics:__call__:1450 - ADVI 10000/200000: mean loss = 5342.67
2026-11-17 22:55:51.389 | INFO | ambric.diagnostics:__call__:1453 - ADVI 20000/200000: mean loss = -5134.22 (improved by 10476.89 over last 10000 iterations)
2026-11-17 22:56:01.507 | INFO | ambric.diagnostics:__call__:1453 - ADVI 30000/200000: mean loss = -5346.93 (improved by 212.71 over last 10000 iterations)
2026-11-17 22:56:11.459 | INFO | ambric.diagnostics:__call__:1453 - ADVI 40000/200000: mean loss = -5399.08 (improved by 52.15 over last 10000 iterations)
2026-11-17 22:56:21.430 | INFO | ambric.diagnostics:__call__:1453 - ADVI 50000/200000: mean loss = -5431.11 (improved by 32.03 over last 10000 iterations)
2026-11-17 22:56:31.468 | INFO | ambric.diagnostics:__call__:1453 - ADVI 60000/200000: mean loss = -5454.99 (improved by 23.88 over last 10000 iterations)
2026-11-17 22:56:41.430 | INFO | ambric.diagnostics:__call__:1453 - ADVI 70000/200000: mean loss = -5473.65 (improved by 18.66 over last 10000 iterations)
2026-11-17 22:56:51.389 | INFO | ambric.diagnostics:__call__:1453 - ADVI 80000/200000: mean loss = -5487.76 (improved by 14.11 over last 10000 iterations)
2026-11-17 22:57:01.419 | INFO | ambric.diagnostics:__call__:1453 - ADVI 90000/200000: mean loss = -5499.22 (improved by 11.47 over last 10000 iterations)
2026-11-17 22:57:11.515 | INFO | ambric.diagnostics:__call__:1453 - ADVI 100000/200000: mean loss = -5508.41 (improved by 9.19 over last 10000 iterations)
2026-11-17 22:57:21.538 | INFO | ambric.diagnostics:__call__:1453 - ADVI 110000/200000: mean loss = -5515.04 (improved by 6.62 over last 10000 iterations)
2026-11-17 22:57:31.531 | INFO | ambric.diagnostics:__call__:1453 - ADVI 120000/200000: mean loss = -5520.50 (improved by 5.46 over last 10000 iterations)
2026-11-17 22:57:41.500 | INFO | ambric.diagnostics:__call__:1453 - ADVI 130000/200000: mean loss = -5524.74 (improved by 4.24 over last 10000 iterations)
2026-11-17 22:57:51.491 | INFO | ambric.diagnostics:__call__:1453 - ADVI 140000/200000: mean loss = -5528.77 (improved by 4.03 over last 10000 iterations)
2026-11-17 22:58:01.512 | INFO | ambric.diagnostics:__call__:1453 - ADVI 150000/200000: mean loss = -5530.86 (improved by 2.09 over last 10000 iterations)
2026-11-17 22:58:11.507 | INFO | ambric.diagnostics:__call__:1453 - ADVI 160000/200000: mean loss = -5533.08 (improved by 2.22 over last 10000 iterations)
2026-11-17 22:58:21.475 | INFO | ambric.diagnostics:__call__:1453 - ADVI 170000/200000: mean loss = -5534.37 (improved by 1.30 over last 10000 iterations)
2026-11-17 22:58:31.475 | INFO | ambric.diagnostics:__call__:1453 - ADVI 180000/200000: mean loss = -5535.90 (improved by 1.53 over last 10000 iterations)
2026-11-17 22:58:41.450 | INFO | ambric.diagnostics:__call__:1453 - ADVI 190000/200000: mean loss = -5537.16 (improved by 1.25 over last 10000 iterations)
2026-11-17 22:58:51.478 | INFO | ambric.diagnostics:__call__:1453 - ADVI 200000/200000: mean loss = -5538.39 (improved by 1.23 over last 10000 iterations)
Finished [100%]: Average Loss = -5,538.4
2026-11-17 22:59:05.577 | WARNING | ambric:fit:1449 - ADVI has NOT converged after 200000 iterations: mean loss changed by -1.23 (standard error 0.35) between the last two windows of 10000 iterations; converged means a fall of at most 1.0, measured to that precision. Estimates may be unreliable; increase n_model_fit_iterations.
ADVI has NOT converged after 200000 iterations: mean loss changed by -1.23 (standard error 0.35) between the last two windows of 10000 iterations; converged means a fall of at most 1.0, measured to that precision. Estimates may be unreliable; increase n_model_fit_iterations.
------------ambric Model-------------
Model ID: 005057f5
Parameters:
Time periods (quarters), T=130
Earliest: 1990-March; Latest: 2022-June
Regions, R=12
Macroeconomic series, M=2
Regional indicators, J=4
n_factors=2
Bridge R²=0.5454, Model fitted: Yes
Posterior samples: 3000
ADVI iterations: 200000
ADVI converged: No
-------------------------------------
That’s it! It’s done. While fitting, the log reports how the ADVI loss is improving, and warns at the end if it was still falling, which means more iterations are needed. You can also look at the loss path directly:
amb.plot_advi_convergence()fit() has a few other options:
xgb_params: a dictionary of XGBoost hyperparameters, overriding the defaults.bridge_use_almon: whether the MIDAS bridge equation estimates Almon polynomial weights across the quarters (True, the default) or uses equal weights.bridge_ridge_alpha: the ridge penalty in the bridge equation (default 1.0).advi_log_every: how many iterations between log lines reporting the ADVI loss (default: a twentieth of the run).advi_convergence_tolerance: the largest fall in mean loss between the last two 5% windows of the run that still counts as converged (default 1.0).
Now let’s look at some results.
First, our regional estimates of quarterly growth must be consistent with the observed national growth. We can check the implied vs the true growth at the national level.
amb.plot_national_quarterly_vs_implied()2026-11-17 22:59:09.598 | INFO | ambric.diagnostics:rmse_national_quarterly:118 - UK Quarterly RMSE (true vs implied): 0.0007
2026-11-17 22:59:09.836 | INFO | ambric:plot_national_quarterly_vs_implied:1583 - Plotted national quarterly growth rates vs implied estimates from the model.
Next let’s look at what the regional growth (q on 4 q earlier) looks like for all regions.
amb.plot_regional_annual_estimate()2026-11-17 22:59:10.054 | INFO | ambric.diagnostics:rmse_regions_annual:98 - RMSE (true vs estimated) per region (annual):
2026-11-17 22:59:10.055 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 1: 0.0091
2026-11-17 22:59:10.055 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 2: 0.0090
2026-11-17 22:59:10.056 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 3: 0.0099
2026-11-17 22:59:10.057 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 4: 0.0131
2026-11-17 22:59:10.057 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 5: 0.0081
2026-11-17 22:59:10.058 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 6: 0.0100
2026-11-17 22:59:10.060 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 7: 0.0085
2026-11-17 22:59:10.060 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 8: 0.0119
2026-11-17 22:59:10.061 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 9: 0.0080
2026-11-17 22:59:10.062 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 10: 0.0057
2026-11-17 22:59:10.062 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 11: 0.0064
2026-11-17 22:59:10.063 | INFO | ambric.diagnostics:rmse_regions_annual:100 - Region 12: 0.0092
2026-11-17 22:59:10.063 | INFO | ambric.diagnostics:rmse_regions_annual:101 - Average: 0.0091
2026-11-17 22:59:12.650 | INFO | ambric:plot_regional_annual_estimate:1609 - Plotted regional annual growth rates vs estimated from the model.
We can also look at the underlying quarterly regional growth estimates (the latent \(y_{t,r}\)):
amb.plot_estimated_regional_quarterly()And, if we want tables of the nowcasts, there’s a built-in for that at either q-on-4q (these tables are in percent, so 0.5 means 0.5%)
amb.point_estimates_q_on_4q().iloc[-3:, :]| region_00 | region_01 | region_02 | region_03 | region_04 | region_05 | region_06 | region_07 | region_08 | region_09 | region_10 | region_11 | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| datetime | ||||||||||||
| 2021-12-31 | -2.60 | -3.00 | -3.09 | -3.10 | -2.91 | -3.28 | -3.13 | -3.34 | -3.36 | -3.41 | -3.50 | -3.11 |
| 2022-03-31 | -2.34 | -2.94 | -2.84 | -3.07 | -2.70 | -3.05 | -2.98 | -3.09 | -3.24 | -3.25 | -3.38 | -3.01 |
| 2022-06-30 | -2.14 | -2.87 | -2.65 | -2.99 | -2.54 | -2.88 | -2.85 | -2.93 | -3.13 | -3.13 | -3.25 | -2.92 |
or q-on-q:
amb.point_estimates_q_on_q().iloc[-3:, :]| region_00 | region_01 | region_02 | region_03 | region_04 | region_05 | region_06 | region_07 | region_08 | region_09 | region_10 | region_11 | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| datetime | ||||||||||||
| 2021-12-31 | -0.46 | -0.63 | -0.55 | -0.67 | -0.57 | -0.58 | -0.62 | -0.63 | -0.67 | -0.71 | -0.73 | -0.65 |
| 2022-03-31 | -0.53 | -0.78 | -0.74 | -0.73 | -0.71 | -0.85 | -0.81 | -0.89 | -0.89 | -0.85 | -0.86 | -0.84 |
| 2022-06-30 | -0.57 | -0.79 | -0.70 | -0.80 | -0.65 | -0.80 | -0.74 | -0.79 | -0.86 | -0.83 | -0.85 | -0.80 |
These can be turned into a regional index, set to 100 in the quarter before the sample starts:
amb.to_index_q_on_q().iloc[-3:, :]| region_00 | region_01 | region_02 | region_03 | region_04 | region_05 | region_06 | region_07 | region_08 | region_09 | region_10 | region_11 | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| datetime | ||||||||||||
| 2021-12-31 | 133.408592 | 97.190747 | 114.102119 | 90.863811 | 117.671828 | 108.169243 | 106.120098 | 104.973917 | 98.051791 | 91.638242 | 86.178430 | 93.856315 |
| 2022-03-31 | 132.699948 | 96.430230 | 113.261228 | 90.202666 | 116.837755 | 107.247808 | 105.258969 | 104.042089 | 97.179307 | 90.855988 | 85.441226 | 93.068728 |
| 2022-06-30 | 131.942724 | 95.668628 | 112.473008 | 89.480956 | 116.080017 | 106.394068 | 104.478409 | 103.220620 | 96.346019 | 90.100062 | 84.711512 | 92.324530 |
For a less granular binned signal, economic_pulse_indicator() classifies each period into growth bands rather than just recession/expansion:
amb.economic_pulse_indicator().set_index(["region", "datetime"]).unstack(0).tail()2026-11-17 22:59:15.051 | DEBUG | pydemetra._java:start_jvm:134 - Starting JVM with 13 JARs, max_heap=512m
WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::arrayBaseOffset has been called by com.google.protobuf.UnsafeUtil$MemoryAccessor (file:/home/runner/work/ambric/ambric/.venv/lib/python3.14/site-packages/pydemetra/_jars/protobuf-java-4.33.1.jar)
WARNING: Please consider reporting this to the maintainers of class com.google.protobuf.UnsafeUtil$MemoryAccessor
WARNING: sun.misc.Unsafe::arrayBaseOffset will be removed in a future release
| classification | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| region | region_00 | region_01 | region_02 | region_03 | region_04 | region_05 | region_06 | region_07 | region_08 | region_09 | region_10 | region_11 |
| datetime | ||||||||||||
| 2021-06-30 | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | strong contraction | contraction |
| 2021-09-30 | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction |
| 2021-12-31 | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction |
| 2022-03-31 | contraction | contraction | contraction | contraction | contraction | contraction | contraction | contraction | strong contraction | contraction | strong contraction | contraction |
| 2022-06-30 | contraction | contraction | contraction | contraction | contraction | strong contraction | contraction | strong contraction | strong contraction | strong contraction | strong contraction | strong contraction |
There is also access to all of the internal data generated when the model runs. The raw Bayesian samples can be retrieved using amb.trace, while the full set of predictions and outturns are available through amb.populate_results():
amb.populate_results()| datetime | value | region | measure | type | |
|---|---|---|---|---|---|
| 0 | 1990-03-31 | 0.000348 | uk | gva_q_on_q | outturn |
| 1 | 1990-06-30 | -0.001297 | uk | gva_q_on_q | outturn |
| 2 | 1990-09-30 | -0.002929 | uk | gva_q_on_q | outturn |
| 3 | 1990-12-31 | -0.003043 | uk | gva_q_on_q | outturn |
| 4 | 1991-03-31 | -0.001388 | uk | gva_q_on_q | outturn |
| ... | ... | ... | ... | ... | ... |
| 1555 | 2021-06-30 | -0.007193 | region_11 | q_on_q | nowcast |
| 1556 | 2021-09-30 | -0.006278 | region_11 | q_on_q | nowcast |
| 1557 | 2021-12-31 | -0.006451 | region_11 | q_on_q | nowcast |
| 1558 | 2022-03-31 | -0.008391 | region_11 | q_on_q | nowcast |
| 1559 | 2022-06-30 | -0.007996 | region_11 | q_on_q | nowcast |
4868 rows × 5 columns
Factor and macro loadings
AMBRIC’s hierarchical loadings — \(\Lambda\) for the regional factors, \(\Gamma\) for the macro covariates, and \(\delta_r\) for the XGBoost bridge signal (see the README for the full specification) — can be inspected after fitting.
amb.assemble_loadings_data().head()2026-11-17 22:59:23.631 | INFO | ambric.diagnostics:assemble_loadings_data:693 - Assembled loadings data: 60 rows across 12 regions, broad types: ['factors', 'macro', 'boost_signal'], scaled by variable stds
| region | loading_name | broad_type | mean | hdi_low | hdi_high | scaled | |
|---|---|---|---|---|---|---|---|
| 0 | region_00 | factor_0 | factors | -0.000878 | -0.002152 | 0.000355 | True |
| 1 | region_00 | factor_1 | factors | 0.000310 | -0.001146 | 0.001824 | True |
| 2 | region_01 | factor_0 | factors | -0.000877 | -0.002154 | 0.000292 | True |
| 3 | region_01 | factor_1 | factors | 0.000280 | -0.001072 | 0.001804 | True |
| 4 | region_02 | factor_0 | factors | -0.000865 | -0.002140 | 0.000374 | True |
amb.plot_loadings_by_region()2026-11-17 22:59:23.655 | INFO | ambric.diagnostics:assemble_loadings_data:693 - Assembled loadings data: 60 rows across 12 regions, broad types: ['factors', 'macro', 'boost_signal'], scaled by variable stds
2026-11-17 22:59:24.845 | INFO | ambric:plot_loadings_by_region:1757 - Plotted loadings by region.
amb.plot_loadings_aggregate()2026-11-17 22:59:24.866 | INFO | ambric.diagnostics:assemble_loadings_data:693 - Assembled loadings data: 60 rows across 12 regions, broad types: ['factors', 'macro', 'boost_signal'], scaled by variable stds
2026-11-17 22:59:25.560 | INFO | ambric:plot_loadings_aggregate:1782 - Plotted loadings in aggregate by broad type.
If you want to persist the fitted posterior to disk for reuse, call amb.save_trace('path/to/folder'). This writes model_trace_<model id>.nc into that folder, where the model id is the one shown when the model is printed.
Published quarterly regional data
Some regions publish quarterly growth (for example Scotland’s quarterly GDP), which is more timely than the annual regional release. Add it to the long dataframe as another measure, with the same datetime | measure | region | value columns and decimal growth rates, and pass the measure’s name as region_q_on_q_measure. Coverage can be partial: you can supply some regions and some quarters. Where a value is supplied, the model’s quarterly growth for that region and quarter is fixed to it, and it informs the other regions and quarters through the national and annual constraints and the model’s dynamics.
The simulated data don’t include a quarterly regional series, so the example below (not run here) uses the simulation’s true quarterly growth for the first region as if it were published:
import pandas as pd
df_sim, truth = generate_realistic_simulated_data(
n_factors=n_factors, R=12, return_truth=True
)
df_published_qoq = pd.DataFrame(
{
"datetime": truth["datetime"],
"measure": "region_q_on_q",
"region": "region_00",
"value": truth["y_reg_true"][:, 0],
}
)
df_with_qoq = pd.concat([df_sim, df_published_qoq], ignore_index=True)
amb_qoq = Ambric(
df_with_qoq,
macro_names,
region_names,
region_covariate_names,
n_factors=n_factors,
region_weights=region_weights,
region_q_on_q_measure="region_q_on_q",
)
amb_qoq.fit(n_iterations, n_posterior_samples)Evaluating nowcasts out of sample
run_out_of_sample_exercise() replays history to see how well the model would have done in real time. It starts from the first init_chunk_size quarters and moves forward step_size quarters at a time. At each step it hides the annual regional data for the last lag_qtrs quarters (the publication lag), fits the model, and keeps the nowcasts for those quarters alongside the outturns. If region_q_on_q_measure is given, published quarterly values for the last lag_qtrs_qoq quarters are hidden too. Each step is a full model fit, so this takes a while; the example is not run here.
from ambric import run_out_of_sample_exercise
from ambric.diagnostics import (
oos_q_on_4q_performance_table,
plot_out_of_sample_nowcasts,
plot_out_of_sample_rmse,
)
df_results = run_out_of_sample_exercise(
df,
macro_names,
region_names,
region_covariate_names,
n_factors=n_factors,
region_weights=region_weights,
init_chunk_size=100,
step_size=4,
)The results are in long format, with a quarters_to_publication column giving how far each nowcast was from the release of its outturn. They can be summarised by the root mean squared error at each horizon, the nowcasts against the outturns, and how often the nowcast got the direction of annual growth right:
plot_out_of_sample_rmse(df_results, region_measure="gva_q_on_4q")
plot_out_of_sample_nowcasts(df_results, region_measure="gva_q_on_4q")
oos_q_on_4q_performance_table(df_results, region_measure="gva_q_on_4q")