How to use AMBRIC

Let’s import the package.

from ambric import Ambric
from ambric.utilities import generate_realistic_simulated_data

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,
)
amb
2026-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:

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")