macro-supply-signals

Pull and normalise macro-economic indicators relevant to supply-chain analysis. All signals are sourced from FRED (Federal Reserve Economic Data) and returned as clean pandas DataFrames.

Signals

Every signal is documented in the catalog with a title, description of supply-chain relevance, units, seasonal adjustment status, domain tags, and join hints.

Setup

Prerequisites: Python 3.9+

git clone https://github.com/ag7982/supply-chain-macro-economic-signals.git
cd supply-chain-macro-economic-signals
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"           # core + dev tools
pip install -e ".[dev,notebook]"  # also installs matplotlib for the quickstart notebook

API key: register for a free FRED API key at https://fred.stlouisfed.org/docs/api/api_key.html, then:

cp .env.example .env
# open .env and set FRED_API_KEY=your_key_here

Usage

Single signal — convenience functions

from macro_supply_signals.signals.inflation import get_cpi

df = get_cpi(start="2020-01-01")
print(df.tail())
#         date native_series_id    value  cpi_yoy  cpi_mom  ...  retrieved_at
# 2025-12-01  CPIAUCSL  326.031   3.0023   0.2978  ...  2026-05-01 12:00:00+00:00

Pass include_derived=False to get a slim frame with only the schema columns:

df = get_cpi(start="2020-01-01", include_derived=False)
# columns: date, native_series_id, value, retrieved_at, signal_id, frequency, source

Each function accepts optional start, end (ISO date strings), api_key, and include_derived parameters.

Available signal functions

from macro_supply_signals.signals.inflation import get_cpi
from macro_supply_signals.signals.ppi import get_ppi
from macro_supply_signals.signals.industrial import get_industrial_production
from macro_supply_signals.signals.energy import get_wti, get_brent
from macro_supply_signals.signals.fx import get_usd_index

Batch pulls — SignalClient

SignalClient is the recommended entry point when pulling more than one signal. It binds the API key once and supports aligned panel output.

from macro_supply_signals import SignalClient

client = SignalClient()  # reads FRED_API_KEY from environment

# Pull multiple signals — returns dict[signal_id, DataFrame]
frames = client.pull_many(
    ["inflation.cpi_headline", "energy.crude_wti"],
    start="2020-01-01",
)

# Align to month-end — returns a wide DataFrame with MultiIndex columns
panel = client.pull_many(
    ["inflation.cpi_headline", "energy.crude_wti"],
    start="2020-01-01",
    align="month_end",
)
# panel["inflation.cpi_headline"]["cpi_yoy"]  →  monthly CPI YoY series

No interpolation is applied — gaps remain NaN.

Pull by stable signal id (registry)

All convenience functions delegate to a central catalog. You can call the same logic by id directly:

from macro_supply_signals.catalog import fetch_signal, INFLATION_CPI_HEADLINE

df = fetch_signal(INFLATION_CPI_HEADLINE, start="2020-01-01")
# equivalent to get_cpi(start="2020-01-01")

Inspect the catalog

from macro_supply_signals.catalog import SIGNALS_BY_ID

for sid, spec in SIGNALS_BY_ID.items():
    print(spec.title, "|", spec.supply_chain_tags)
# CPI — Consumer Price Index (Headline) | ['input_costs', 'demand', 'contract_pricing']
# WTI Crude Oil Price                   | ['energy', 'transportation_cost', 'input_costs']
# ...

Output schema

Every DataFrame carries these columns:

Plus derived columns per signal family (cpi_yoy, cpi_mom, chg_1d, chg_30d, …), omitted when include_derived=False.

Project structure

macro_supply_signals/
├── __init__.py          # exports SignalClient
├── client.py            # SignalClient — pull(), pull_many(align=)
├── catalog.py           # SIGNALS_BY_ID, SignalSpec, fetch_signal(), stable id constants
├── sources/
│   └── fred.py          # FREDClient — wraps the FRED REST API
└── signals/
    ├── inflation.py     # get_cpi()
    ├── ppi.py           # get_ppi()
    ├── industrial.py    # get_industrial_production()
    ├── energy.py        # get_wti(), get_brent()
    └── fx.py            # get_usd_index()
notebooks/
└── 00_quickstart.ipynb  # end-to-end walkthrough of every public entry-point
scripts/
└── pull_cpi.py          # demo script — fetches CPI, prints summary, saves to data/cpi.csv
tests/
├── test_catalog.py      # registry and fetch_signal tests
├── test_client.py       # SignalClient integration tests
├── test_fred.py         # FREDClient unit tests
└── test_signals.py      # smoke tests for all signal functions

Running tests

pytest --cov=macro_supply_signals --cov-report=term-missing

All tests mock the FRED HTTP layer — no API key required.

Roadmap

• CI pipeline (GitHub Actions, Python 3.9 + 3.12)
• MIT license
• SignalClient with pull() and pull_many() (#7)
• Standard columns + retrieved_at + include_derived
• Baltic Dry Index (shipping) — requires scraping (#11)
• PyPI publish (#5)
• Scheduled pulls / incremental updates