fred-loader 0.1.0__tar.gz

fred_loader-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Solberg
+
+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.

fred_loader-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: fred-loader
+Version: 0.1.0
+Summary: A Python wrapper around the Federal Reserve FRED API that abstracts away series IDs, resampling rules, and macro scoring behind a clean, human-readable interface.
+Author: Ian Solberg
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fredapi
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# FRED_Loader
+
+A Python wrapper around the Federal Reserve FRED API that abstracts away
+series IDs, resampling rules, and macro scoring behind a clean,
+human-readable interface. Installs as `fred-loader`, for anyone who pulls
+macroeconomic data into pandas.
+
+## Install
+
+```bash
+pip install fred-loader
+```
+
+Or from a checkout of this repository: `pip install -e .`.
+
+## Quickstart
+
+```python
+from fred_loader import Config, pull_fred
+
+cfg = Config(filename="fred_master.csv", output_path="./data")
+df = pull_fred(cfg)
+```
+
+Cherry-pick series categories:
+
+```python
+from fred_loader import INFLATION, LABOR, RATES, Config, pull_fred
+
+cfg = Config(
+    filename="policy_inputs.csv",
+    output_path="./data",
+    series={**INFLATION, **LABOR, **RATES},
+)
+df = pull_fred(cfg)
+```
+
+## Project structure
+
+```
+src/fred_loader/
+  __init__.py       # public API re-exports
+  utils.py          # Config
+  load.py           # pull_fred entry point
+  series.py         # series catalog: categories and subcategories
+  macro_scores.py   # scoring layer: score, available_scores
+```

fred_loader-0.1.0/README.md

@@ -0,0 +1,47 @@
+# FRED_Loader
+
+A Python wrapper around the Federal Reserve FRED API that abstracts away
+series IDs, resampling rules, and macro scoring behind a clean,
+human-readable interface. Installs as `fred-loader`, for anyone who pulls
+macroeconomic data into pandas.
+
+## Install
+
+```bash
+pip install fred-loader
+```
+
+Or from a checkout of this repository: `pip install -e .`.
+
+## Quickstart
+
+```python
+from fred_loader import Config, pull_fred
+
+cfg = Config(filename="fred_master.csv", output_path="./data")
+df = pull_fred(cfg)
+```
+
+Cherry-pick series categories:
+
+```python
+from fred_loader import INFLATION, LABOR, RATES, Config, pull_fred
+
+cfg = Config(
+    filename="policy_inputs.csv",
+    output_path="./data",
+    series={**INFLATION, **LABOR, **RATES},
+)
+df = pull_fred(cfg)
+```
+
+## Project structure
+
+```
+src/fred_loader/
+  __init__.py       # public API re-exports
+  utils.py          # Config
+  load.py           # pull_fred entry point
+  series.py         # series catalog: categories and subcategories
+  macro_scores.py   # scoring layer: score, available_scores
+```

fred_loader-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fred-loader"
+version = "0.1.0"
+description = "A Python wrapper around the Federal Reserve FRED API that abstracts away series IDs, resampling rules, and macro scoring behind a clean, human-readable interface."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ian Solberg" }]
+dependencies = [
+    "fredapi",
+    "pandas",
+    "numpy",
+    "python-dotenv",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

fred_loader-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fred_loader-0.1.0/src/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-0.1.0/src/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