Documentation Map

Back to reference

Use this page as the inspection order for the current callable-first macroforecast documentation.

Quick Routing

Question	Open this page	What to verify there
What is the current package shape?	Workflow Contract	Module ownership, runner loop, and stage policies.
How do I set package-wide defaults?	Meta	Seed, worker count, error handling, default runner stage scopes, and metadata level.
Did we preserve old statistical functionality?	Legacy Callable Coverage	Covered callables, intentional removals, and remaining future work.
Which imports are public?	Public Python API	Top-level exports and module namespaces.
How do I load and shape data?	Data	Panel contract, metadata, custom loaders, FRED loaders, frequency policies.
Which FRED-family dataset should I use?	FRED Datasets	FRED-MD, FRED-QD, FRED-SD, combined loaders, and frequency conversion warnings.
How do I clean a panel?	Preprocessing	Transform codes, outliers, imputation, standardization, frame rules.
How do I smooth or filter one noisy macro series?	Filters	HP, Hamilton, Savitzky-Golay, wavelet-style components, and AlbaMA.
How do I inspect learned feature weights?	Feature Analysis	Effective windows and recent weight shares from adaptive feature weight matrices.
How do I create targets and predictors?	Feature Engineering	Target construction, lags, rolling features, factors, selection, runner-safe specs.
How do I define time windows?	Window	Train/validation/test windows, expanding/rolling/fixed policies, stage policies.
Which models are available?	Models	Model groups, parameter defaults, optional dependencies, model-owned search spaces.
How do I fit several member models as one model?	Model Ensemble	Bagging, subagging, random subspace, stacking, Super Learner, and Booging.
How does the runner combine everything?	Forecasting	Runner inputs, direct/recursive/path-average forecasts, forecast-output combinations.
How do I score and test forecasts?	Evaluation	Evaluation reports, metrics/tests split, benchmark/regime/decomposition tables.
How do I inspect model behavior?	Interpretation	Importance, SHAP, attribution, OLS-as-attention, VAR interpretation, neural attribution.
Which historical observations drove a forecast?	Dual Interpretation	Observation weights, observation contributions, concentration, short position, leverage, turnover, and historical episode groups.
How do I save outputs?	Output	Output bundles, artifact writing, manifests, hashes, compression.
How do I format paper/report tables?	Reporting	Accuracy/model-comparison/test presets, table formatting, LaTeX/HTML/Markdown rendering, figure-ready data.
How do I plug in my own loader, transform, model, test, diagnostic, or artifact?	Custom Extensions	Stage-local custom callable hooks and input/output contracts.
How do I know the formulas are not drifting?	Reference Verification	Reference anchors and expansion policy.

Recommended Review Sequence

Use this sequence when auditing the whole docs site.

1. Workflow Contract

2. Meta

3. Legacy Callable Coverage

4. Public Python API

5. Data

6. FRED Datasets

7. Preprocessing

8. Filters

9. Feature Engineering

10. Window

11. Models

12. Model Ensemble

13. Model Selection

14. Forecasting

15. Metrics

16. Tests

17. Evaluation

18. Feature Analysis

19. Forecast Analysis

20. Interpretation

21. Dual Interpretation

22. Output

23. Reporting

24. Custom Extensions

25. Reference Verification

Reference Page Format

Reference pages should use the same contract-first structure when a page documents callable functions. Exact sections can vary by module, but each public callable should make these items easy to find:

Section	Required content
Purpose	What the module owns and what it explicitly does not own.
Public Functions	Function list grouped by role, with one-line outputs and purpose.
Public Flow	Minimal executable call sequence when the module has a normal workflow.
Function Signature	Fully qualified callable name, arguments, defaults, and return type.
Function Input	Parameter name, type, default, allowed values, and meaning.
Function Defaults	Defaults that matter for reproducibility, especially hidden constants or metadata behavior.
Function Output	Return object, fields, table columns, and serialization helpers.
Metadata	Stage key and stored provenance when the function writes metadata.
Validation or notes	Error conditions and boundary cases where they are non-obvious.

Use display labels for user-facing choices when possible, and put stored enum values in code formatting. Avoid bare lists such as "raise" | "continue" without explaining the meaning of each choice.

Module Boundaries

Boundary	Rule
meta vs data pipeline	meta stores package defaults; it does not load, clean, summarize, or compare data.
data vs preprocessing	data creates canonical panels and metadata; preprocessing transforms values.
preprocessing vs feature_engineering	preprocessing cleans variables; feature_engineering creates targets and predictors.
filters vs feature_engineering	filters transforms one series; feature_engineering turns those filter outputs into panel feature columns.
feature generation vs feature analysis	feature_engineering creates AlbaMA feature columns and stores learned weights; feature_analysis summarizes those weights through effective windows and recent weight shares.
feature_engineering vs window	Feature functions build matrices; window decides which dates belong to train/validation/test.
models vs model_selection	Models own fit functions and search spaces; model_selection runs parameter search on supplied windows.
model_selection vs forecasting	model_selection picks model parameters; forecasting orchestrates repeated fits and predictions.
metrics vs tests vs evaluation	metrics score errors; tests run statistical tests; evaluation assembles reports and slices.
output vs reporting	output creates/writes artifacts; reporting formats presentation tables and figure data.
built-in stages vs custom extensions	Custom callables stay inside the owning stage and must return the same object shape that the next stage expects.
callable API vs future recipes	Current docs describe direct Python callables. YAML/recipe wrappers are intentionally deferred.

Current Review Focus

Page	Why it matters now
Legacy Callable Coverage	Confirms that intentional removals are not mistaken for missing work.
Reference Verification	Tracks the verification suite that should grow as paper-code checks are added.
Output and Reporting	These were recently split; check whether their responsibility boundary is clear.
Custom Extensions	Confirms that custom hooks enter the normal callable flow instead of creating a parallel registry.
Tests	Contains blocked_oob_reality_check() and exact model_confidence_set(), which close recent legacy gaps.