User Guide#

Back to documentation home

This guide explains how macroforecast turns a forecasting study into one specification you can read from top to bottom. If you have ever hand-written a backtest loop and then struggled to keep preprocessing, feature construction, and evaluation in step, this is the part of the documentation that shows the alternative.

The package is built around a single idea. You declare each part of the experiment once, and the runner executes every combination and scores it. The map below shows those parts and the order in which a forecast flows through them, from raw data on the left to a scored report at the end.

The pipeline at a glance#

        flowchart TD
    A["load_fred_md / load_custom_csv"] --> B["DataBundle"]
    B --> C["data.spec → DataSpec"]
    C --> D["preprocess_spec<br/>t-codes · outliers · EM imputation"]
    D --> E["window.from_cutoffs<br/>estimation · validation · test · cadence"]
    E --> F["feature_spec<br/>lags · MARX · factors · Level"]
    F --> G["Arm<br/>model + preprocessing + features"]
    G --> H["pipeline_spec → PipelineSpec"]
    H --> I["run_pipeline → PipelineReport"]
    I --> R1[".accuracy<br/>relative RMSE"]
    I --> R2[".significance<br/>DM · Clark-West"]
    I --> R3[".mcs<br/>Model Confidence Set"]
    I --> R4[".forecasts<br/>full forecast frame"]

    classDef input fill:#e8f1fb,stroke:#3b7dd8,color:#13243b;
    classDef stage fill:#f4f6f8,stroke:#9aa7b4,color:#1d2733;
    classDef output fill:#eaf6ec,stroke:#43a05a,color:#10331b;
    class A,B,C input;
    class D,E,F,G,H,I stage;
    class R1,R2,R3,R4 output;

How the pieces fit#

A study starts with data. A loader returns a DataBundle, and data.spec records which series you forecast and over what sample. From there the workflow is a short chain. Preprocessing makes the series stationary and fills gaps, a window fixes the estimation, validation, and test split together with how often models refit, and feature engineering turns the cleaned panel into the lag, factor, and moving-average inputs a model consumes.

Those three choices plus a single model form an arm, which is one complete contender. You collect the arms, the targets, and an evaluation rule into a pipeline_spec, and running it executes every contender across every target and horizon. The result is a PipelineReport whose evaluation tables score each arm against a benchmark and report where the differences are statistically real.

Every stage is leak-aware. No observation dated after a forecast origin can enter the training data for that origin, and stateful steps such as imputation, factor extraction, and standardization are refit on the available rows at each origin rather than once on the full sample.

How to use this guide#

If you have not run the package yet, start with Getting Started for the shortest path from install to a first result. Then work through the stage pages below in the order of the map above. Each one explains one stage and most include a short executed walkthrough you can paste and run. Once the stages are familiar, or once you already have your own data and your own model in mind, go straight to Your Data, Your Model, One Table – a capstone tutorial that runs every stage above end to end on a custom CSV. Use Real-Time Vintages when the study must resolve one data snapshot per forecast origin.

When you need exact signatures, follow the reference link at the foot of each stage page. The Glossary, Models and Features, and Replication Gallery are reached from the documentation home and are useful once the workflow is familiar.