Treasury CMT Yield Curve Bootstrap

Bootstrap discount factors and zero-coupon yield curves from US Treasury CMT rates.

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Download Historical Data

Download the Treasury par yield curve data (1990-2023) from: https://home.treasury.gov/resource-center/data-chart-center/interest-rates/TextView?type=daily_treasury_yield_curve

Save as: data/par-yield-curve-rates-1990-2023.csv

3. Build Initial Dataset

# All data from 1990
python scripts/build_initial_treasury_file.py

# Or filter to recent years (recommended for faster processing)
python scripts/build_initial_treasury_file.py --start-date 2022-01-01

This creates Treasury_CMT_Data_Tool.xlsx with combined historical + current data.

4. Run Bootstrap

# Scheme 2 (piecewise linear forward - recommended)
python scripts/run_bootstrap.py --scheme 2

# Scheme 3 (monotone cubic forward - smoother) with Excel output
python scripts/run_bootstrap.py --scheme 3 --write-excel

Outputs:

• Treasury_CMT_Data_Tool_curves_S2_YYYY-YYYY.npz (compressed data)
• Treasury_CMT_Data_Tool_curves_S2_YYYY-YYYY.xlsx (human-readable)

5. Update Data (Ongoing)

python scripts/update_all_data.py --scheme 2

Refreshes Treasury CMT par rates and the SOFR/Fed-Funds short-rate history (data/short_rates/short_rate_combined.csv), then re-runs the bootstrap. The short-rate refresh matters for Schemes 2/3, which anchor to it — Scheme 1 doesn't use it. Running update_treasury_cmt.py alone updates the workbook but leaves the short-rate anchor stale for S2/S3; cmt_bootstrap.py will print a WARNING if that anchor falls more than 5 days behind the newest curve date. See Workflow 2 in the Bootstrap Guide for scheduling this as a daily cron/Task Scheduler job.

📊 Interactive Visualization

Explore bootstrapped yield curves with mathematically correct reconstruction:

# Run with sample data (2022-2026 included)
python -m streamlit run scripts/yield_curve_app.py

Why Curve Reconstruction Matters

Most yield curve tools use linear interpolation between tenor points - this is mathematically incorrect!

Our approach reconstructs continuous curves from bootstrap parameters:

• S1: Piecewise constant forwards → Exponential discount decay
• S2: Piecewise linear forwards → Smooth exponential decay
• S3: Monotone cubic forwards → Perfectly smooth curves

Features

Tab 1: Yield Curves

• Par, spot, and forward rates (smooth reconstruction)
• Discount factor curves (exponential decay)
• Spot-par spread analysis
• Data table with CSV export (expandable)

Scheme 3 shows perfectly smooth forward rates - true cubic interpolation, not linear approximation

Tab 2: Spread Analysis

• Compare any two tenors (e.g., 10Y-2Y inversion)
• Date range filtering
• Distribution histograms with statistics

Tab 3: Forward Projections

• Forward term structure: f(0, s, s+M)
• Multiple tenors (1Mo to 30Yr)
• Shows market rate expectations
• Progressive smoothing demonstration

Progressive smoothing: 1Mo forward is jagged, 10Yr forward is smooth - mathematics visualized

See Visualization Guide for complete documentation.

Volatility Analysis App

Span-weighted PCA and tail-distribution fitting on S1 forward rate changes.

python -m streamlit run scripts/vol_analysis_app.py

Loading Data

Unlike the yield curve app, this app does not auto-detect sample files — point it at an NPZ panel yourself:

• Click 📂 in the sidebar to open a native file browser, or
• Paste a path directly into the "NPZ file" field and press Enter

⚠️ Requires an S1 (piecewise-constant forward) bootstrap file specifically — the PCA and tail-fit math is derived for S1's step-function forwards; S2/S3 files will load but produce incorrect results.

Ready-to-use sample: data/samples/Treasury_CMT_Data_Tool_curves_S1_1990-2026.npz (Jan 1990 – Jul 2026, ships with the repo) — the full history gives the PCA and tail fits far more observations than the 2022-2026 sample.

To generate your own S1 file:

python scripts/run_bootstrap.py --scheme 1 --write-excel

This produces Treasury_CMT_Data_Tool_curves_S1_<start>-<end>.npz (see Output Files).

Features

Tab 1 — PCA: Waterfall scree plot of variance explained, interactive PC loadings chart, and variance table. Variance threshold (90/95/99%) selector highlights the minimum PC count needed.

Tab 2 — Tail Distribution & ALCO Scenarios:

• Corrected F(k, ν) QQ plots for both k=5 (reduced-rank) and k=14 (full-rank) fits, with the C vs Σ inflation factor c=(ν-2)/ν applied throughout.
• Seven preset ALCO stress scenarios (parallel, bear/bull steepen/flatten, bell, bowl) all calibrated to the same d² as a parallel +100 bp/quarter shock. Five anchor sliders (3Mo/5Yr/10Yr/20Yr/30Yr) control custom scenarios; the remaining nine tenors are linearly interpolated and shown in gray.
• Severity score = P(D² ≤ d²_scenario) under the fitted distribution.

Bootstrap Bench (Standalone Web Tool)

A single-file, client-side what-if tool for Scheme 3 bootstrapping — no Python, no server. Move par-rate sliders and a short-rate anchor (r0) and it redraws the implied instantaneous forward, spot, and discount curves out to 360 months live, with a round-trip fit check. Also includes a paste-in importer for Treasury.gov's daily par yield table, and an "Export 30Y forward curves" button that produces an .xlsx workbook of forward-implied par yield / spot / discount grids (quarterly, 0–30Y, with flat-forward extrapolation past 30Y).

# Open directly in a browser -- no install, no build step
open web/bootstrap-bench/index.html

See web/bootstrap-bench/README.md for details, including how to import it into CodeSandbox or another static host.

Note: the bootstrap math here is a JS port of src/cmt_bootstrap.py's Scheme 2/3 logic (verified to match to 10 decimal places at the time of writing) — kept in this repo specifically so it stays visible next to the Python it mirrors. If cmt_bootstrap.py's Scheme 2/3 math changes, re-verify this file against it.

Project Structure

cmt-yield-curve-bootstrap/
├── README.md                          # This file
├── LICENSE
├── requirements.txt                   # Python dependencies
├── RELEASE_NOTES.md                   # Per-release changelog
├── INSTALLATION_GUIDE.md              # Setup + troubleshooting
├── .gitignore
│
├── src/
│   ├── cmt_bootstrap.py               # Core bootstrap algorithms
│   └── vol_analysis.py                # Span-weighted PCA + F(k,ν) tail fit
│
├── scripts/
│   ├── run_bootstrap.py              # Wrapper to run bootstrap on Excel file
│   ├── update_short_rates.py         # Combine SOFR/Fed Funds histories
│   ├── update_treasury_cmt.py        # Fetch latest CMT rates from Treasury API
│   ├── update_all_data.py            # Daily entrypoint: chains the two updaters above + bootstrap
│   ├── build_initial_treasury_file.py # One-time: build complete historical dataset
│   ├── yield_curve_app.py            # Streamlit: curve visualization
│   └── vol_analysis_app.py           # Streamlit: PCA + tail-risk / ALCO scenarios
│
├── data/
│   ├── Treasury_CMT_Data_Tool.xlsx   # Main data file (generated by build script)
│   ├── par-yield-curve-rates-1990-2023.csv  # Historical data (download from Treasury)
│   ├── samples/                      # Ready-to-use bootstrapped NPZ files (S1/S2/S3)
│   └── short_rates/
│       ├── fed_funds_1954_2018.csv   # FRED DFF series (included)
│       └── sofr_manual.csv           # SOFR baseline (included)
│       # short_rate_combined.csv     # Generated by update_short_rates.py
│
├── docs/
│   ├── USER_GUIDE.md                 # Detailed usage guide
│   ├── BOOTSTRAP_GUIDE.md            # Bootstrap methodology
│   ├── VISUALIZATION_GUIDE.md        # Yield curve app usage guide
│   ├── CURVE_RECONSTRUCTION.md       # Curve reconstruction math
│   └── images/                       # Screenshots used in this README
│
└── web/
    └── bootstrap-bench/
        ├── index.html                 # Standalone what-if tool (see above)
        └── README.md                  # Tool-specific docs + hosting notes

V1.1 Directory Structure:

cmt-yield-curve-bootstrap/
├── README.md                        ← UPDATE
├── LICENSE
├── requirements.txt                 ← UPDATED
├── .gitignore                      ← UPDATE
├── RELEASE_NOTES.md                ← NEW
│
├── src/
│   └── cmt_bootstrap.py
│
├── scripts/
│   ├── yield_curve_app.py          ← NEW
│   ├── curve_reconstruction.py     ← NEW
│   ├── build_initial_treasury_file.py
│   ├── update_treasury_cmt.py
│   ├── update_short_rates.py
│   └── run_bootstrap.py
│
├── data/
│   ├── samples/                    ← NEW
│   │   ├── README.md               ← NEW
│   │   ├── Treasury_CMT_curves_S1_2022_2026.npz  ← NEW
│   │   ├── Treasury_CMT_curves_S2_2022_2026.npz  ← NEW
│   │   └── Treasury_CMT_curves_S3_2022_2026.npz  ← NEW
│   └── short_rates/
│       ├── fed_funds_1954_2018.csv
│       └── sofr_manual.csv
│
└── docs/
    ├── USER_GUIDE.md
    ├── BOOTSTRAP_GUIDE.md
    ├── VISUALIZATION_GUIDE.md      ← NEW
    ├── CURVE_RECONSTRUCTION.md     ← NEW
    ├── INSTALLATION_GUIDE.md       ← NEW
    └── images/                     ← NEW
        ├── yield_curves_s1.png
        ├── yield_curves_s3.png
        ├── spread_analysis.png
        └── forward_projections.png

Bootstrap Schemes

Scheme 1: Piecewise constant instantaneous forward

• Simplest, fast
• Discontinuous forwards

Scheme 2: Piecewise linear instantaneous forward

• Good balance of speed and smoothness
• Recommended for most use cases

Scheme 3: Monotone cubic instantaneous forward

• Smoothest curves
• Slower computation
• Best for derivatives pricing

Output Files

NPZ File (Primary)

Compressed NumPy archive with:

• Par rates (input)
• Discount factors at each tenor
• Spot (zero) rates (continuous compounding)
• Forward rates at tenor endpoints
• Bootstrap parameters (scheme-dependent)
• Validation: implied par rates, round-trip errors

Excel File (Optional)

# Output to excel modifier
python scripts/run_bootstrap.py --scheme 2 --write-excel

Human-readable tables:

• Par Rates (input)
• Discount Factors
• Spot Rates (cc)
• Forward @ TenorEnd
• Par Rates (implied)
• Round-Trip Error (bp)
• Bootstrap parameters

Data Sources

CMT Rates: US Treasury Department

• Historical: CSV download (1990-2023)
• Recent: XML API (2024-present)

Short Rates (r₀ anchor):

• SOFR: 2018-present (preferred), fetched from the NY Fed markets API by scripts/update_short_rates.py
• Effective Fed Funds: 1954-2018 (fallback, static — included in data/short_rates/, no refresh needed)

Notes

• Par rates interpreted as swap/coupon-equivalent rates
• Missing tenors are skipped (no interpolation)
• Payment frequency: 24 per year (semi-monthly, configurable with --nu)
• All rates stored in decimal form (0.0555 = 5.55%)

References

• US Treasury: https://home.treasury.gov/
• FRED (Fed Funds): https://fred.stlouisfed.org/series/DFF
• NY Fed (SOFR): https://www.newyorkfed.org/markets/reference-rates/sofr

License

MIT License

---