macroforecast 0.1.0__tar.gz

macroforecast-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# macrocast cache
+.macrocast/
+
+# Data (downloaded, not committed)
+data_cache/
+*.csv.gz
+
+# R
+macrocastR/.Rproj.user
+macrocastR/src/*.o
+macrocastR/src/*.so
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.local
+
+# Claude Code local settings
+.claude/settings.local.json
+.claude/session-*.md
+
+# mkdocs build output
+site/
+
+# Notebook outputs (examples/results/ is gitignored)
+examples/results/
+.worktrees/

macroforecast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

macroforecast-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: macroforecast
+Version: 0.1.0
+Summary: Decomposing ML Forecast Gains in Macroeconomic Forecasting
+Project-URL: Documentation, https://macroforecast.github.io/macroforecast
+Project-URL: Repository, https://github.com/macroforecast/macroforecast
+Project-URL: Issues, https://github.com/macroforecast/macroforecast/issues
+Author: Chan
+License: MIT
+License-File: LICENSE
+Keywords: FRED,forecasting,machine-learning,macroeconomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: joblib>=1.3
+Requires-Dist: numpy>=1.24
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.11
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: tqdm>=4.65
+Provides-Extra: all
+Requires-Dist: beautifulsoup4>=4.12.0; extra == 'all'
+Requires-Dist: chromadb>=0.4.0; extra == 'all'
+Requires-Dist: einops>=0.8.2; extra == 'all'
+Requires-Dist: lightgbm>=4.0; extra == 'all'
+Requires-Dist: matplotlib>=3.7; extra == 'all'
+Requires-Dist: mcp[cli]>=1.2.0; extra == 'all'
+Requires-Dist: mkdocs-material>=9.4; extra == 'all'
+Requires-Dist: mkdocstrings[python]>=0.23; extra == 'all'
+Requires-Dist: mypy>=1.5; extra == 'all'
+Requires-Dist: pre-commit>=3.4; extra == 'all'
+Requires-Dist: pyarrow>=14.0; extra == 'all'
+Requires-Dist: pymupdf>=1.23.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.1; extra == 'all'
+Requires-Dist: pytest>=7.4; extra == 'all'
+Requires-Dist: ruff>=0.4; extra == 'all'
+Requires-Dist: seaborn>=0.13; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Requires-Dist: xgboost>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pre-commit>=3.4; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.4; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.23; extra == 'docs'
+Provides-Extra: ml
+Requires-Dist: lightgbm>=4.0; extra == 'ml'
+Requires-Dist: pyarrow>=14.0; extra == 'ml'
+Requires-Dist: torch>=2.0; extra == 'ml'
+Requires-Dist: xgboost>=2.0; extra == 'ml'
+Provides-Extra: rag
+Requires-Dist: beautifulsoup4>=4.12.0; extra == 'rag'
+Requires-Dist: chromadb>=0.4.0; extra == 'rag'
+Requires-Dist: einops>=0.8.2; extra == 'rag'
+Requires-Dist: mcp[cli]>=1.2.0; extra == 'rag'
+Requires-Dist: pymupdf>=1.23.0; extra == 'rag'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'rag'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Requires-Dist: seaborn>=0.13; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# macroforecast
+
+Decomposing ML Forecast Gains in Macroeconomic Forecasting.
+
+An open-source Python (+ R) framework for systematic evaluation of machine learning methods in macroeconomic forecasting, with built-in support for the FRED-MD, FRED-QD, and FRED-SD database ecosystem.
+
+[![CI](https://github.com/macroforecast/macroforecast/actions/workflows/ci.yml/badge.svg)](https://github.com/macroforecast/macroforecast/actions/workflows/ci.yml)
+[![Docs](https://github.com/macroforecast/macroforecast/actions/workflows/docs.yml/badge.svg)](https://macroforecast.github.io/macroforecast)
+[![PyPI](https://img.shields.io/pypi/v/macroforecast)](https://pypi.org/project/macroforecast/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## Status
+
+| Layer | Version | Status |
+|-------|---------|--------|
+| Data (FRED-MD/QD/SD) | v0.1.0 | Complete |
+| Forecasting Pipeline | v0.2.0 | Complete |
+| Evaluation | v0.3.0 | Complete |
+
+---
+
+## Installation
+
+```bash
+pip install macroforecast
+# or with all extras
+pip install macroforecast[all]
+```
+
+---
+
+## Quick Start
+
+```python
+import macroforecast as mc
+
+# Load and transform FRED-MD (latest vintage, cached locally)
+md = mc.load_fred_md()
+md_t = md.transform()
+
+print(md_t)
+# MacroFrame(dataset='FRED-MD', vintage='current', T=790, N=128,
+#            period=1959-01-01 to 2024-10-01, status=transformed)
+
+# Subset by variable group
+output = md_t.group("output_income")   # INDPRO, RPI, ...
+prices = md_t.group("prices")          # CPI, PPI, ...
+
+# Check missing values
+report = md.missing_report()
+print(report[["n_leading", "n_trailing", "n_intermittent"]].head())
+
+# Method chaining
+md_ready = (
+    mc.load_fred_md()
+    .trim(start="1970-01", end="2023-12")
+    .handle_missing("trim_start")
+    .transform()
+)
+
+# Load a specific vintage
+md_2020 = mc.load_fred_md(vintage="2020-01")
+
+# FRED-QD (quarterly)
+qd = mc.load_fred_qd()
+
+# FRED-SD (state-level)
+sd = mc.load_fred_sd(states=["CA", "TX"], variables=["UR"])
+```
+
+---
+
+## Documentation
+
+Full documentation is available at [macroforecast.github.io/macroforecast](https://macroforecast.github.io/macroforecast).
+
+---
+
+## License
+
+MIT

macroforecast-0.1.0/README.md

@@ -0,0 +1,83 @@
+# macroforecast
+
+Decomposing ML Forecast Gains in Macroeconomic Forecasting.
+
+An open-source Python (+ R) framework for systematic evaluation of machine learning methods in macroeconomic forecasting, with built-in support for the FRED-MD, FRED-QD, and FRED-SD database ecosystem.
+
+[![CI](https://github.com/macroforecast/macroforecast/actions/workflows/ci.yml/badge.svg)](https://github.com/macroforecast/macroforecast/actions/workflows/ci.yml)
+[![Docs](https://github.com/macroforecast/macroforecast/actions/workflows/docs.yml/badge.svg)](https://macroforecast.github.io/macroforecast)
+[![PyPI](https://img.shields.io/pypi/v/macroforecast)](https://pypi.org/project/macroforecast/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## Status
+
+| Layer | Version | Status |
+|-------|---------|--------|
+| Data (FRED-MD/QD/SD) | v0.1.0 | Complete |
+| Forecasting Pipeline | v0.2.0 | Complete |
+| Evaluation | v0.3.0 | Complete |
+
+---
+
+## Installation
+
+```bash
+pip install macroforecast
+# or with all extras
+pip install macroforecast[all]
+```
+
+---
+
+## Quick Start
+
+```python
+import macroforecast as mc
+
+# Load and transform FRED-MD (latest vintage, cached locally)
+md = mc.load_fred_md()
+md_t = md.transform()
+
+print(md_t)
+# MacroFrame(dataset='FRED-MD', vintage='current', T=790, N=128,
+#            period=1959-01-01 to 2024-10-01, status=transformed)
+
+# Subset by variable group
+output = md_t.group("output_income")   # INDPRO, RPI, ...
+prices = md_t.group("prices")          # CPI, PPI, ...
+
+# Check missing values
+report = md.missing_report()
+print(report[["n_leading", "n_trailing", "n_intermittent"]].head())
+
+# Method chaining
+md_ready = (
+    mc.load_fred_md()
+    .trim(start="1970-01", end="2023-12")
+    .handle_missing("trim_start")
+    .transform()
+)
+
+# Load a specific vintage
+md_2020 = mc.load_fred_md(vintage="2020-01")
+
+# FRED-QD (quarterly)
+qd = mc.load_fred_qd()
+
+# FRED-SD (state-level)
+sd = mc.load_fred_sd(states=["CA", "TX"], variables=["UR"])
+```
+
+---
+
+## Documentation
+
+Full documentation is available at [macroforecast.github.io/macroforecast](https://macroforecast.github.io/macroforecast).
+
+---
+
+## License
+
+MIT

macroforecast-0.1.0/macroforecast/__init__.py

@@ -0,0 +1,85 @@
+"""macroforecast: Decomposing ML Forecast Gains in Macroeconomic Forecasting.
+
+Modules
+-------
+* ``macroforecast.data``           — FRED-MD/QD/SD loaders + MacroFrame
+* ``macroforecast.preprocessing``  — tcode transforms, MARX/MAF, panel preprocessing
+* ``macroforecast.pipeline``       — ForecastExperiment, models, features
+* ``macroforecast.evaluation``     — MSFE, MCS, DM, CW statistical tests
+* ``macroforecast.interpretation`` — dual weights, PBSV, variable importance
+* ``macroforecast.viz``            — visualization
+* ``macroforecast.utils``          — registry, LaTeX export, cache
+* ``macroforecast.replication``    — paper-specific helpers (CLSS 2021 etc.)
+
+Quick start::
+
+    from macroforecast import load_fred_md, ForecastExperiment
+"""
+
+__version__ = "0.1.0"
+
+from macroforecast.data import (
+    MacroFrame,
+    MacroFrameMetadata,
+    MergeResult,
+    RealTimePanel,
+    VariableMetadata,
+    list_available_vintages,
+    load_fred_md,
+    load_fred_qd,
+    load_fred_sd,
+    load_vintage_panel,
+    merge_macro_frames,
+)
+from macroforecast.pipeline import (
+    FeatureSpec,
+    ForecastExperiment,
+    ForecastRecord,
+    ModelSpec,
+    ResultSet,
+)
+from macroforecast.preprocessing import (
+    TransformCode,
+    apply_hamilton_filter,
+    apply_maf,
+    apply_marx,
+    apply_pca,
+    apply_tcode,
+    apply_tcodes,
+    apply_x_factors,
+    classify_missing,
+    handle_missing,
+)
+
+__all__ = [
+    "__version__",
+    # data
+    "load_fred_md",
+    "load_fred_qd",
+    "load_fred_sd",
+    "MacroFrame",
+    "MacroFrameMetadata",
+    "VariableMetadata",
+    "list_available_vintages",
+    "load_vintage_panel",
+    "RealTimePanel",
+    "merge_macro_frames",
+    "MergeResult",
+    # preprocessing
+    "TransformCode",
+    "apply_tcode",
+    "apply_tcodes",
+    "apply_marx",
+    "apply_maf",
+    "apply_x_factors",
+    "apply_pca",
+    "apply_hamilton_filter",
+    "classify_missing",
+    "handle_missing",
+    # pipeline
+    "ForecastExperiment",
+    "ModelSpec",
+    "FeatureSpec",
+    "ResultSet",
+    "ForecastRecord",
+]

macroforecast-0.1.0/macroforecast/cli.py

@@ -0,0 +1,293 @@
+"""macroforecast command-line interface.
+
+Usage
+-----
+    macroforecast --help
+    macroforecast run experiment.yaml
+    macroforecast init [--output experiment.yaml]
+    macroforecast info experiment.yaml
+
+Commands
+--------
+run     Execute a forecast experiment from a YAML config file.
+init    Write a default YAML config template to disk.
+info    Print a summary of the resolved config without running.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+logger = logging.getLogger("macroforecast")
+
+
+# ---------------------------------------------------------------------------
+# Logging setup
+# ---------------------------------------------------------------------------
+
+
+def _setup_logging(verbose: bool = False) -> None:
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        format="%(asctime)s  %(levelname)-8s  %(name)s — %(message)s",
+        datefmt="%H:%M:%S",
+        level=level,
+    )
+
+
+# ---------------------------------------------------------------------------
+# run
+# ---------------------------------------------------------------------------
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    """Execute a forecast experiment defined in a YAML config file."""
+    from macroforecast.config import load_config
+    from macroforecast.pipeline.experiment import ForecastExperiment
+
+    try:
+        cfg = load_config(args.config)
+    except (FileNotFoundError, ValueError) as exc:
+        logger.error("Config error: %s", exc)
+        return 1
+
+    logger.info("Experiment: %s", cfg.experiment_id)
+    logger.info(
+        "Dataset:    %s  (target=%s, vintage=%s)",
+        cfg.data.dataset,
+        cfg.data.target,
+        cfg.data.vintage or "current",
+    )
+    logger.info("Models:     %d configured", len(cfg.model_specs))
+    logger.info("Horizons:   %s", cfg.horizons)
+    logger.info("Window:     %s", cfg.window.value)
+    logger.info("OOS range:  %s → %s", cfg.oos_start or "auto", cfg.oos_end or "end")
+
+    # Load data
+    try:
+        panel, target = _load_data(cfg)
+    except Exception as exc:
+        logger.error("Data loading failed: %s", exc)
+        return 1
+
+    output_dir = cfg.output_dir / cfg.experiment_id
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    exp = ForecastExperiment(
+        panel=panel,
+        target=target,
+        horizons=cfg.horizons,
+        model_specs=cfg.model_specs,
+        feature_spec=cfg.feature_spec,
+        window=cfg.window,
+        rolling_size=cfg.rolling_size,
+        oos_start=cfg.oos_start,
+        oos_end=cfg.oos_end,
+        n_jobs=cfg.n_jobs,
+        experiment_id=cfg.experiment_id,
+        output_dir=output_dir,
+    )
+
+    logger.info("Running experiment...")
+    rs = exp.run()
+
+    logger.info("Done. %d forecast records.", len(rs))
+
+    if args.summary:
+        _print_summary(rs)
+
+    return 0
+
+
+def _load_data(cfg):
+    """Load dataset and extract panel + target from MacroFrame."""
+    from macroforecast.data import load_fred_md, load_fred_qd
+
+    dataset = cfg.data.dataset.lower().replace("-", "_")
+    cache_dir = Path(cfg.data.cache_dir).expanduser() if cfg.data.cache_dir else None
+
+    if dataset == "fred_md":
+        mf = load_fred_md(vintage=cfg.data.vintage, cache_dir=cache_dir)
+    elif dataset == "fred_qd":
+        mf = load_fred_qd(vintage=cfg.data.vintage, cache_dir=cache_dir)
+    else:
+        raise ValueError(
+            f"Dataset '{cfg.data.dataset}' not supported via CLI. "
+            "Use fred_md or fred_qd.  For fred_sd, load programmatically."
+        )
+
+    # Apply stationarity transforms if needed
+    if not mf.metadata.is_transformed:
+        mf = mf.transform()
+
+    df = mf.data
+
+    if cfg.data.target not in df.columns:
+        raise ValueError(
+            f"Target '{cfg.data.target}' not found in dataset. "
+            f"Available columns: {list(df.columns[:10])} ..."
+        )
+
+    target = df[cfg.data.target]
+    panel = df.drop(columns=[cfg.data.target])
+
+    # Drop columns with all NaN
+    panel = panel.dropna(axis=1, how="all")
+
+    # Restrict to rows where target is observed
+    mask = target.notna()
+    panel = panel.loc[mask]
+    target = target.loc[mask]
+
+    return panel, target
+
+
+def _print_summary(rs) -> None:
+    """Print MSFE table to stdout."""
+    try:
+        summary = rs.msfe_by_model()
+        if summary.empty:
+            print("No results to summarise.")
+            return
+        print("\n--- MSFE Summary ---")
+        print(summary.to_string(index=False))
+    except Exception:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    """Write the default YAML config template."""
+    from macroforecast.config import DEFAULT_CONFIG_YAML
+
+    out_path = Path(args.output)
+    if out_path.exists() and not args.force:
+        logger.error("File already exists: %s. Use --force to overwrite.", out_path)
+        return 1
+
+    out_path.write_text(DEFAULT_CONFIG_YAML)
+    logger.info("Config template written to: %s", out_path)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# info
+# ---------------------------------------------------------------------------
+
+
+def _cmd_info(args: argparse.Namespace) -> int:
+    """Print a resolved config summary without running."""
+    from macroforecast.config import load_config
+
+    try:
+        cfg = load_config(args.config)
+    except (FileNotFoundError, ValueError) as exc:
+        logger.error("Config error: %s", exc)
+        return 1
+
+    print(f"Experiment ID:  {cfg.experiment_id}")
+    print(f"Output dir:     {cfg.output_dir}")
+    print(f"Dataset:        {cfg.data.dataset}")
+    print(f"Target:         {cfg.data.target}")
+    print(f"Vintage:        {cfg.data.vintage or 'current'}")
+    print(f"Horizons:       {cfg.horizons}")
+    print(f"Window:         {cfg.window.value}")
+    print(f"OOS start:      {cfg.oos_start or 'auto'}")
+    print(f"OOS end:        {cfg.oos_end or 'auto'}")
+    print(f"n_jobs:         {cfg.n_jobs}")
+    print(f"Models ({len(cfg.model_specs)}):")
+    for spec in cfg.model_specs:
+        print(f"  - {spec.model_id}")
+    print("Features:")
+    fs = cfg.feature_spec
+    print(
+        f"  factor_type={fs.factor_type!r}, n_factors={fs.n_factors}, "
+        f"n_lags={fs.n_lags}, lookback={fs.lookback}"
+    )
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="macroforecast",
+        description="macroforecast — Decomposing ML Forecast Gains",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable DEBUG logging."
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    subparsers.required = True
+
+    # run
+    run_parser = subparsers.add_parser(
+        "run", help="Run a forecast experiment from a YAML config."
+    )
+    run_parser.add_argument(
+        "config", metavar="CONFIG.yaml", help="Path to the YAML experiment config file."
+    )
+    run_parser.add_argument(
+        "--summary", action="store_true", help="Print MSFE summary table after the run."
+    )
+
+    # init
+    init_parser = subparsers.add_parser(
+        "init", help="Write a default YAML config template."
+    )
+    init_parser.add_argument(
+        "--output",
+        "-o",
+        default="experiment.yaml",
+        help="Output file path (default: experiment.yaml).",
+    )
+    init_parser.add_argument(
+        "--force", action="store_true", help="Overwrite existing file."
+    )
+
+    # info
+    info_parser = subparsers.add_parser("info", help="Print a resolved config summary.")
+    info_parser.add_argument(
+        "config", metavar="CONFIG.yaml", help="Path to the YAML config file."
+    )
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    _setup_logging(verbose=args.verbose)
+
+    dispatch = {
+        "run": _cmd_run,
+        "init": _cmd_init,
+        "info": _cmd_info,
+    }
+    handler = dispatch.get(args.command)
+    if handler is None:
+        parser.print_help()
+        return 1
+
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())