fred-loader 0.1.0__py3-none-any.whl

fred_loader/__init__.py

@@ -0,0 +1,96 @@
+"""A readable Python interface to the FRED macro data API."""
+
+from .load import pull_fred
+from .macro_scores import available_scores, list_scored_columns, score
+from .utils import Config, available, info, resolve_series, search
+
+# Categories
+from .series import INFLATION, OUTPUT, LABOR, RATES, MONEY, HOUSING, CONSUMER
+from .series import TRADE, FINANCIAL, FISCAL, COMMODITIES, INEQUALITY, SEP, DEMOGRAPHICS
+from .series import ALL_SERIES, CATEGORIES, SUBCATEGORIES
+
+# Subcategories (importable directly, per the series catalog docs)
+from .series import CPI, PCE, PPI, IMPORT_EXPORT_PRICES, INFLATION_EXPECTATIONS
+from .series import GDP, PRODUCTION, BUSINESS_SURVEYS
+from .series import EMPLOYMENT, UNEMPLOYMENT, JOLTS, PRODUCTIVITY
+from .series import FED_FUNDS, OVERNIGHT_RATES, TREASURIES, YIELD_SPREADS
+from .series import CREDIT_SPREADS, OTHER_RATES
+from .series import MONEY_SUPPLY, BANK_CREDIT, CONSUMER_CREDIT
+from .series import HOME_PRICES, HOUSING_ACTIVITY, HOUSING_INVENTORY
+from .series import CONSUMER_SPENDING, CONSUMER_INCOME
+from .series import TRADE_BALANCE, DOLLAR_INDICES, EXCHANGE_RATES
+from .series import EQUITY_MARKETS, VOLATILITY, FINANCIAL_CONDITIONS
+from .series import FEDERAL_DEBT, FEDERAL_BUDGET
+from .series import ENERGY, METALS, AGRICULTURE, COMMODITY_INDICES
+
+__all__ = [
+    # Entry points and configuration
+    "pull_fred",
+    "Config",
+    "score",
+    "available_scores",
+    "list_scored_columns",
+    # Discovery: browse and search the catalog without reading series.py
+    "available",
+    "search",
+    "info",
+    "resolve_series",
+    # Composites and lookups
+    "ALL_SERIES",
+    "CATEGORIES",
+    "SUBCATEGORIES",
+    # Categories
+    "INFLATION",
+    "OUTPUT",
+    "LABOR",
+    "RATES",
+    "MONEY",
+    "HOUSING",
+    "CONSUMER",
+    "TRADE",
+    "FINANCIAL",
+    "FISCAL",
+    "COMMODITIES",
+    "INEQUALITY",
+    "SEP",
+    "DEMOGRAPHICS",
+    # Subcategories
+    "CPI",
+    "PCE",
+    "PPI",
+    "IMPORT_EXPORT_PRICES",
+    "INFLATION_EXPECTATIONS",
+    "GDP",
+    "PRODUCTION",
+    "BUSINESS_SURVEYS",
+    "EMPLOYMENT",
+    "UNEMPLOYMENT",
+    "JOLTS",
+    "PRODUCTIVITY",
+    "FED_FUNDS",
+    "OVERNIGHT_RATES",
+    "TREASURIES",
+    "YIELD_SPREADS",
+    "CREDIT_SPREADS",
+    "OTHER_RATES",
+    "MONEY_SUPPLY",
+    "BANK_CREDIT",
+    "CONSUMER_CREDIT",
+    "HOME_PRICES",
+    "HOUSING_ACTIVITY",
+    "HOUSING_INVENTORY",
+    "CONSUMER_SPENDING",
+    "CONSUMER_INCOME",
+    "TRADE_BALANCE",
+    "DOLLAR_INDICES",
+    "EXCHANGE_RATES",
+    "EQUITY_MARKETS",
+    "VOLATILITY",
+    "FINANCIAL_CONDITIONS",
+    "FEDERAL_DEBT",
+    "FEDERAL_BUDGET",
+    "ENERGY",
+    "METALS",
+    "AGRICULTURE",
+    "COMMODITY_INDICES",
+]

fred_loader/load.py

@@ -0,0 +1,143 @@
+"""
+FRED Loader — Public API
+=========================
+
+Single entry point for pulling, resampling, and scoring FRED macro data.
+
+Quick start::
+
+    from fred_loader import pull_fred
+
+    # Full ~80-series macro dataset with scores
+    df = pull_fred("fred_master.csv", output_path="./data")
+
+Cherry-pick series categories::
+
+    from fred_loader import pull_fred, INFLATION, LABOR, RATES
+
+    df = pull_fred(
+        "policy_inputs.csv",
+        output_path="./data",
+        series={**INFLATION, **LABOR, **RATES},
+    )
+
+Available categories::
+
+    INFLATION  — CPI, PCE, breakevens, inflation expectations
+    OUTPUT     — GDP (nominal/real), industrial production, vehicle sales
+    LABOR      — unemployment, payrolls, claims, earnings, JOLTS, LFPR
+    RATES      — fed funds, Treasury curve, yield spreads, credit spreads, mortgage
+    MONEY      — M2, reserves, commercial loans, consumer credit
+    HOUSING    — Case-Shiller, starts, permits, existing sales, months of supply
+    CONSUMER   — Michigan sentiment, retail sales, PCE, savings rate
+    TRADE      — trade balance, trade-weighted dollar
+    FINANCIAL  — VIX, S&P 500, NFCI, St. Louis financial stress
+    FISCAL     — federal debt, surplus/deficit, monthly Treasury statement
+    INEQUALITY — Gini index
+    SEP        — FOMC dot-plot medians (fed funds, GDP, unemployment, PCE)
+"""
+
+import pandas as pd
+from .utils import Config, load_fred_master
+from .macro_scores import score
+
+# Re-export every category so users only need `from fred_loader import ...`
+from .series import (  # noqa: F401
+    INFLATION,
+    OUTPUT,
+    LABOR,
+    RATES,
+    MONEY,
+    HOUSING,
+    CONSUMER,
+    TRADE,
+    FINANCIAL,
+    FISCAL,
+    INEQUALITY,
+    SEP,
+    ALL_SERIES,
+    CATEGORIES,
+)
+
+
+def pull_fred(config: Config, apply_scores: bool = False) -> pd.DataFrame | None:
+    """
+    Pull FRED data, resample to a uniform frequency, and optionally score.
+
+    Parameters
+    ----------
+    filename : str
+        Name of the output CSV (e.g. ``"fred_master.csv"``).
+
+    output_path : str or Path, default ``"./data"``
+        Directory where the CSV will be written.
+
+    start : str, default ``"1990-01-01"``
+        Earliest observation date to request from FRED (``'YYYY-MM-DD'``).
+
+    resample_rule : str, default ``"W-FRI"``
+        Pandas offset alias that controls output frequency.
+        ``"W-FRI"`` = weekly ending Friday.  Other useful values:
+        ``"MS"`` (month start), ``"ME"`` (month end), ``"QE"`` (quarter end).
+
+    mean_freqs : set of str, optional
+        Native-frequency codes whose series are averaged when resampling
+        (e.g. ``{"D"}`` averages daily series into weekly buckets).
+        All other frequencies take the last observation per period.
+        Defaults to ``{"D"}``.
+
+    series : dict, optional
+        Custom series catalog.  Keys are FRED series IDs, values are
+        ``(friendly_name, native_frequency)`` tuples.  Build one by
+        merging category dicts::
+
+            from fred_loader import INFLATION, LABOR, RATES
+            series = {**INFLATION, **LABOR, **RATES}
+
+        When ``None`` (default), the full built-in catalog is used.
+
+    apply_scores : bool, default ``True``
+        When ``True``, run the macro scoring layer (derived series,
+        regime flags, continuous scores, and lead/lag signals).
+        Set ``False`` to get only the raw FRED data.
+
+    inflation_target : float, default ``2.0``
+        Fed inflation target (percent) used in Taylor rule, mandate
+        tension, and expectations-anchoring scores.
+
+    nairu : float, default ``4.0``
+        Natural rate of unemployment (percent) used in Taylor rule
+        and employment-pressure scores.
+
+    Returns
+    -------
+    pd.DataFrame
+        Wide DataFrame with one column per series (plus scored columns
+        if ``apply_scores=True``), indexed by date.
+    """
+    cfg = config if isinstance(config, Config) else None
+    if cfg is None:
+        print("Incorrect Configuration Format.")
+        return None
+    if cfg.SERIES != ALL_SERIES:
+        print("Custom series catalog provided. Pulling subset of FRED data.")
+
+    raw = load_fred_master(config=config)
+
+    if apply_scores:
+        output = score(
+            raw,
+            pi_star=config.INFLATION_TARGET,
+            u_star=config.NATURAL_RATE_UNEMPLOYMENT,
+        )
+    else:
+        output = raw
+    # ── Save ──────────────────────────────────────────────────────────────
+    # set reference to project root (for reproducibility across environments) and ensure output dir exists
+
+    config.OUTPUT_PATH.mkdir(parents=True, exist_ok=True)
+    out_file = config.OUTPUT_PATH / config.FILENAME
+    output.to_csv(out_file)
+
+    print(f"\nSaved → {out_file}")
+    return output