Quick start¶

Load one series¶

import calcfidata as cf

df = cf.load("30-year-fixed")
df.tail()
#             date  value     unit
# 2604  2026-05-08   6.93  percent
# 2605  2026-05-15   6.95  percent

Every series returns the same three columns: date (datetime), value (float), unit (str). Comment headers in the source CSV are stripped automatically.

List every available series¶

catalog = cf.list_series()
catalog.head()
#                slug                                    title  row_count
# 0     30-year-fixed              30-Year Fixed Mortgage Rate       2607
# 1     15-year-fixed              15-Year Fixed Mortgage Rate       1812
# 2       2y-treasury     2-Year Treasury Constant Maturity       6234
# ...

34 rows. See the full catalog for primary-source URLs.

Load several series joined on date¶

# Inflation comparison: CPI vs PCE
inflation = cf.multi(["cpi", "pce"], align_on="inner")
inflation.tail()
#               cpi    pce
# date
# 2026-03-01  319.8  127.4
# 2026-04-01  320.6  127.9

align_on="outer" keeps all dates (NaN where a series doesn't have an observation). "inner" keeps only dates where every series has a value. "left" keeps dates from the first slug.

Get the Frictionless metadata for any series¶

meta = cf.metadata("cpi")
meta["sources"][0]["title"]
# 'BLS via FRED (CPIAUCSL)'
meta["sources"][0]["path"]
# 'https://fred.stlouisfed.org/series/CPIAUCSL'

Includes the canonical primary source URL, the license, keywords, and the Frictionless schema for the CSV. Useful for citation generators or for auto-building source attribution tables.

A real example: mortgage cycle vs Fed Funds¶

import calcfidata as cf
import matplotlib.pyplot as plt

rates = cf.multi(["30-year-fixed", "fed-funds"], align_on="outer")
rates = rates.dropna()
ax = rates.plot(figsize=(10, 4))
ax.set_title("30-Year Fixed Mortgage vs Fed Funds")
ax.set_ylabel("Percent")
plt.tight_layout()
plt.savefig("mortgage-vs-fedfunds.png", dpi=120)

Cache behavior¶

Every loader function uses functools.lru_cache, so calling cf.load("cpi") twice in the same Python process hits the cache the second time. The cache holds up to 64 series per slot — sufficient for the full catalog. To force a re-fetch, restart your process.

For production pipelines, consider caching the raw CSV to local disk first and reading from there instead.