Source code for quantdata.fred.rates

"""
quantdata.fred.rates

Download SOFR, EFFR and Treasury rates from FRED.
Requires the ``FRED_API_KEY`` environment variable.
See https://fred.stlouisfed.org/docs/api/api_key.html
"""

from __future__ import annotations

import os
from datetime import date

import polars as pl
import requests
from cdxcore.err import verify

from quantdata import env

_fred_cache = env.locations.raw("fred")


def _fetch_fred_series(api_key: str, series_id: str, start: date, end: date) -> pl.DataFrame:
    url = "https://api.stlouisfed.org/fred/series/observations"
    params = {
        "series_id": series_id,
        "api_key": api_key,
        "file_type": "json",
        "observation_start": start.strftime("%Y-%m-%d"),
        "observation_end": end.strftime("%Y-%m-%d"),
    }
    r = requests.get(url, params=params, timeout=30)
    r.raise_for_status()
    obs = r.json().get("observations", [])

    if not obs:
        return pl.DataFrame(
            {"date": pl.Series([], dtype=pl.Date), series_id: pl.Series([], dtype=pl.Float64)}
        )

    df = pl.DataFrame(obs).select(
        pl.col("date").str.strptime(pl.Date, "%Y-%m-%d").alias("date"),
        pl.col("value").alias(series_id),
    )
    df = df.with_columns(
        pl.when(pl.col(series_id) == ".").then(None).otherwise(pl.col(series_id)).alias(series_id)
    ).with_columns(pl.col(series_id).cast(pl.Float64))
    return df


[docs] @_fred_cache.cache("0.2", uid=lambda start, end: f"fred/{start}_{end}") def load_fred_rates(start: str | date, end: str | date) -> pl.DataFrame: """ Download SOFR, EFFR, DGS1MO, DGS3MO, DGS6MO from FRED and return as unscaled floats. Adds ``on`` column defined as SOFR when available, otherwise EFFR, otherwise DGS1MO. Only returns dates that have at least one non-zero rate. All rate columns are forward-filled so there are no trailing nulls. Requires ``FRED_API_KEY`` environment variable. Parameters ---------- start : str | date end : str | date Returns ------- pl.DataFrame Columns: date, on, sofr, effr, dgs1mo, dgs3mo, dgs6mo (all Float32, unscaled e.g. 0.05 for 5%) """ start = start if not isinstance(start, str) else date.fromisoformat(start) end = end if not isinstance(end, str) else date.fromisoformat(end) api_key = os.environ.get("FRED_API_KEY") verify( api_key is not None, "Please set FRED_API_KEY in your environment. See https://fred.stlouisfed.org/docs/api/api_key.html", ) series = ["SOFR", "EFFR", "DGS1MO", "DGS3MO", "DGS6MO"] dfs = [_fetch_fred_series(api_key=api_key, series_id=s, start=start, end=end) for s in series] df = dfs[0] for other in dfs[1:]: df = df.join(other, on="date", how="full", coalesce=True) df = df.sort("date") rate_cols = ["sofr", "effr", "dgs1mo", "dgs3mo", "dgs6mo"] df = df.with_columns( (pl.col("SOFR") / 100.0).cast(pl.Float32).alias("sofr"), (pl.col("EFFR") / 100.0).cast(pl.Float32).alias("effr"), (pl.col("DGS1MO") / 100.0).cast(pl.Float32).alias("dgs1mo"), (pl.col("DGS3MO") / 100.0).cast(pl.Float32).alias("dgs3mo"), (pl.col("DGS6MO") / 100.0).cast(pl.Float32).alias("dgs6mo"), ).select(["date"] + rate_cols) df = df.filter(pl.sum_horizontal([pl.col(c).fill_null(0.0) for c in rate_cols]) != 0.0) df = df.with_columns( pl.when(pl.col("sofr").is_not_null()) .then(pl.col("sofr")) .when(pl.col("effr").is_not_null()) .then(pl.col("effr")) .otherwise(pl.col("dgs1mo")) .alias("on") ) df = df.with_columns([pl.col(c).forward_fill() for c in ["on"] + rate_cols]).sort("date") return df.select(["date", "on"] + rate_cols)