nowcastbox 0.2.0

Nowcasting with dynamic factor models in Python.

NowcastBox estimates the present, the recent past and the near future of low-frequency macroeconomic variables (GDP) from large mixed-frequency panels with ragged edges. It covers the whole workflow in one library:

data -> transformations -> vintages -> factor selection -> estimation -> nowcast
     -> news decomposition -> density -> real-time evaluation -> diagnostics -> report

Status: 0.2.0. The API is tested on every commit (about 4,200 tests, 99 % branch coverage) but names may still change before 1.0.

Features

Innovations

What NowcastBox adds to the R package nowcasting and to statsmodels' DynamicFactorMQ:

Installation

pip install nowcastbox

Development version:

git clone https://github.com/NowcastBox/nowcastbox.git
cd nowcastbox
pip install -e ".[dev]"          # + tests, linters, notebooks tooling

Python ≥ 3.10. Core dependencies: numpy, pandas ≥ 2, scipy, numba, statsmodels, matplotlib, plotly, jinja2, pyyaml, requests, joblib. Extras: [data] (Parquet for vintage stores), [docs], [test]. With many CPU cores, small dense matrix work is often faster with one BLAS thread (OMP_NUM_THREADS=1), see the performance guide.

Quickstart

Nowcast Brazilian GDP growth from a dozen monthly indicators, as of 15 November 2024:

import nowcastbox as nb

COLUMNS = ["pib", "ibc_br", "pim_geral", "pmc_varejo", "pms_volume",
           "energia_consumo_total", "ipca", "selic", "focus_pib"]
ds = nb.load_brazil_nowcast(columns=COLUMNS, start="2012-01", end="2024-12")
panel = nb.prepare_panel(ds.data, ds.transform, keep="pib")   # stationary, cleaned
vintage = nb.pseudo_real_time(panel, delay=ds.delay, vintage="2024-11-15")

res = nb.MixedFreqDFM(n_factors=1).fit(vintage, target="pib")  # Bańbura-Modugno EM
print(res.summary())
res.nowcast.tail(3)          # observed, in_sample, out_of_sample, std, 68/90 % bands

old = nb.pseudo_real_time(panel, delay=ds.delay, vintage="2024-10-15")
news = res.news(old, vintage, target_period="2024Q4")         # what moved the nowcast?
news.to_frame(by="category")

One call does preprocessing, the Bai-Ng choice of the number of factors, estimation and a density nowcast:

quick = nb.nowcast(vintage, target="pib", method="em", density=True)
quick.nowcast.tail(2)[["out_of_sample", "lower_90", "median", "upper_90"]]

In production, describe the nowcast in YAML and run it from the command line; every run writes a versioned snapshot and news against the previous one:

nowcastbox init nowcast.yaml -t simulated     # example spec (also: brazil_pib, csv, connectors)
nowcastbox run nowcast.yaml                   # nowcast, news, density, report, snapshot
nowcastbox snapshots history ./snapshots      # nowcast path across runs

Datasets

Documentation and examples

• Documentation (MkDocs Material): getting started, a user guide with runnable examples on every page, theory pages (DFM, Kalman, EM, Mariano-Murasawa, Bai-Ng, news, density scoring, forecast evaluation), comparisons with R nowcasting and DynamicFactorMQ, validation reports and the API reference — mkdocs serve.
• 15 example notebooks in examples/notebooks (saved with outputs): quickstart, data preparation, a GRS (2008) approximation, Bai-Ng, the NY Fed EM with blocks, Brazilian vintages, news, a 2012–2025 pseudo real-time evaluation, live data, COVID robustness, the production pipeline, reports, density nowcasts, weekly data and the comparison with R/statsmodels.

Validation

The classical methods are checked against reference implementations run as black boxes (tests/reference_validation/, docs/validation):

Documented divergences (different defaults, starting values or stopping rules, and a few problems on the R side) are quantified in the validation pages. On the NY Fed EM, NowcastBox runs about 30× faster than R; an EM iteration at N = 200 is about 12× faster than DynamicFactorMQ.

Related work

NowcastBox is an independent, MIT-licensed implementation written from the academic literature. It is inspired by the R package nowcasting (de Valk, de Mattos & Ferreira, 2019, The R Journal), and relates to statsmodels.tsa.DynamicFactorMQ and the FRBNY Staff Nowcast code; these are used only as external benchmarks of results (the GPL code of the R package was never read).

Citation

If you use NowcastBox, please cite it (see CITATION.cff). The DOI 10.5281/zenodo.23102804 always resolves to the latest version; each release also has its own DOI on Zenodo.

@software{nowcastbox,
  author  = {Haase, Gustavo and Sanches, Alexandre Le{\~a}o},
  title   = {{NowcastBox}: Nowcasting with Dynamic Factor Models in Python},
  year    = {2026},
  version = {0.2.0},
  license = {MIT},
  doi     = {10.5281/zenodo.23102804},
  url     = {https://github.com/NowcastBox/nowcastbox}
}

Authors

• Gustavo Haase (gustavo.haase@gmail.com)
• Alexandre Leão Sanches (a.leaosanches@gmail.com)

Programa de Pós-Graduação em Economia — Universidade Católica de Brasília (UCB).

License

MIT. Bundled datasets keep the licenses of their sources (listed in each dataset's metadata and documentation page).