README.md

---
license: apache-2.0
tags:
  - time-series
  - forecasting
  - foundation-model
  - macroeconomics
  - fred-md
  - arxiv:2606.28670
library_name: tempopfn
pipeline_tag: time-series-forecasting
---

# MacroCast

**Paper:** Carriero, Pettenuzzo & Shekhar (2026), *MACROCAST: A Vintage-Consistent
Time Series Foundation Model for Real-Time Macroeconomic Forecasting* —
[arXiv:2606.28670](https://arxiv.org/abs/2606.28670)
([SSRN](https://ssrn.com/abstract=7004218)).

**MacroCast** is a compact (~1.2M-parameter) time-series foundation model for
**macroeconomic forecasting**. It forecasts a full panel of monthly
indicators in a **single forward pass** (no autoregressive windowing) and returns
**probabilistic** (9-quantile) forecasts.

It is trained in two stages:

1. Base model: A ~1.2M-parameter linear-RNN backbone (built on
   [TempoPFN](https://github.com/automl/TempoPFN), Apache-2.0), trained from
   scratch **entirely on synthetic data** (no real macro data).
2. **MacroCast** — Base model **fine-tuned** on FRED-MD via an expanding-window,
   real-time-vintage procedure, using a mixture of macro-calibrated synthetic
   panels (block-bootstrap, per-variable AR, Dynamic Factor Model, and BVAR).

## Vintages (real-time fine-tuning)
This repo ships **one checkpoint per fine-tuning vintage** (in `models/`). Each
checkpoint is MacroCast fine-tuned on only the FRED-MD data available *through that
cutoff* — e.g. the 2010 vintage has never seen post-2010 data — so you can choose how
much history the model has seen and run **leak-free real-time / backtesting**
experiments. The available vintages, their data cutoffs, and per-vintage variable
counts are listed in `manifest.json` (`default_year` is used when no year is given).

## Usage

**Install dependencies** (needs a **GPU**). On Colab/Jupyter prefix with `!`;
`torch` is already present on Colab, otherwise install the build:

```bash
pip install flash-linear-attention==0.5.0 transformers==5.8.1 einops gluonts huggingface_hub
```

```python
from huggingface_hub import snapshot_download
import sys

local = snapshot_download(repo_id="shubhranshu/MacroCast")
sys.path.insert(0, local)                 # for forecast.py
from forecast import MacroCastForecaster

# List vintages, then load MacroCast for one (year=None -> latest):
print(MacroCastForecaster.available_years(local))     # e.g. [1998, ..., 2023]
f = MacroCastForecaster.from_pretrained(local, year=2023)

# history: np.ndarray of shape [T, N]  (T monthly steps, N FRED-MD variables)
point, quantiles = f.predict(history, horizon=12, freq="M")
```

- `point`: `[horizon, N]` median (0.5-quantile) forecast.
- `quantiles`: `[horizon, N, 9]` forecasts for quantiles 0.1 … 0.9.


## Model details
- **Architecture**: GatedDeltaProduct linear-RNN, `embed=128`, 3 layers, ~1.2M params.
- **Objective**: 9-quantile (0.1…0.9) pinball loss.
- **Pre-training**: synthetic priors only (GP, kernel, Ornstein–Uhlenbeck,
  ForecastPFN, CauKer, sine/sawtooth/step, …) — no real macro data.
- **MacroCast fine-tuning**: FRED-MD real-time vintages expanded into a synthetic
  mixture — `real` + `block-bootstraps`, `arima` (per-variable AR), `dfm`
  (Dynamic Factor Model), and `bvar_clust` / `bvar_full` (Minnesota BVAR).

## Intended use and limitations
- Built for **monthly macroeconomic** panels. Feed transformed/stationary inputs.
- Forecasts are statistical outputs, **not financial or policy advice**.

## Citation
If you use MacroCast, please cite:

```bibtex
@misc{carriero2026macrocast,
  title         = {{MACROCAST}: A Vintage-Consistent Time Series Foundation Model for Real-Time Macroeconomic Forecasting},
  author        = {Carriero, Andrea and Pettenuzzo, Davide and Shekhar, Shubhranshu},
  year          = {2026},
  eprint        = {2606.28670},
  archivePrefix = {arXiv},
  primaryClass  = {econ.EM},
  url           = {https://arxiv.org/abs/2606.28670}
}
```

## Acknowledgements & license
Built on [TempoPFN](https://github.com/automl/TempoPFN) (Apache-2.0): the model
backbone, trainer, and synthetic-data generators are vendored from that project
and modified for macroeconomic forecasting. Released under Apache-2.0. Please
also cite TempoPFN (Moroshan et al., 2025, arXiv 2510.25502).