User Guide#
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 read the Concepts pages in the order of the map above. Each one explains one stage and most include a short executed walkthrough you can paste and run.
When you need exact signatures, follow the reference link at the foot of each concept page. The Glossary, Models and Features, and Replication Gallery are reached from the documentation home and are useful once the workflow is familiar.
Concepts#
Data, preprocessing, features, windows, models, running, and evaluation, in order.