Fixed income lab · methodology

How it works

Every number in the lab comes from bondlab, a Python fixed income library, through the same API as the options tool. This page sets out what it computes and how, in the order the lab uses it.

The data

The curve is the U.S. Treasury's Daily Treasury Par Yield Curve: for each business day, par yields at fixed maturities from one month to 30 years. The Treasury reads them off its own fitted curve of recently auctioned securities. Every day since 2 January 1990 is stored, and a scheduled job loads each new day twice an evening, so the lab never waits on treasury.gov.

The set of published maturities has changed: no one-month bill before 2001, no 30-year bond from 2002 to early 2006, and new two-month, four-month and six-week bills since 2018. The lab builds each day from the maturities that day actually has and says which are missing. Choose a weekend or holiday and you get the last business day before it.

Building the curve

Each published yield becomes an instrument the curve must price exactly:

  • Six months or less: bills. One payment at maturity, the published yield read as a simple ACT/365 rate, which is how the Treasury quotes bills of up to half a year.
  • Longer: par bonds. A semiannual Treasury issued on the curve date with a coupon equal to its published yield, so it is worth exactly 100.

The curve is bootstrapped: solved one maturity at a time, shortest first, each discount factor chosen so its instrument reprices to the quote with the earlier ones already fixed. Between pillars the curve needs an interpolation rule, and the lab offers three:

SchemeWhat it does
Monotone convexHagan and West's method, the one the Treasury itself uses: forwards stay positive and continuous, with no overshoot between pillars.
Linear on zero ratesStraight lines between zero rates. Simple and local, but the forward curve jumps at every pillar.
Natural cubic splineA smooth curve through the zero rates. The forwards look smooth too, but they can overshoot and wiggle between pillars.

The chart also shows a Nelson-Siegel fit to the same day's continuously compounded zero rates. It is a four-parameter curve, a level, a slope and a hump that decays at rate λ:

z(t) = β₀ + β₁·(1 − e^(−λt))/(λt) + β₂·[(1 − e^(−λt))/(λt) − e^(−λt)]

All four parameters, λ included, are fitted by Levenberg-Marquardt least squares. Unlike the bootstrapped curve it does not pass through every point. The gap shows how much of the day's curve a smooth level-slope-curvature shape explains.

Pricing a bond

Two bonds are offered, and their conventions are stated, not hidden:

US TreasuryUSD corporate
CouponsSemiannualSemiannual
Accrual day countACT/ACT (ICMA)30/360
SettlementT+1T+2
CalendarSIFMA US bond market (Good Friday included)

The price can come from any one of three inputs, and the other two are solved from it:

  • Off the curve. Each cash flow is discounted at the curve's semiannual zero rate plus a spread.
  • From a yield. The street-convention yield to maturity, compounded semiannually.
  • From a price. The yield and the Z-spread are solved to match the clean price you give.
dirty price = Σ CFᵢ · DF(tᵢ)        DF(t) = (1 + (z(t) + s)/2)^(−2t)
clean price = dirty price − accrued interest

Durations come from the yield: Macaulay is the present-value-weighted average time of the payments, and modified is Macaulay / (1 + y/2). Convexity measures how much the price curves against the yield. DV01 is the price change for a 1 bp fall in yield, per 100 face. "Show your work" lists every cash flow with its discount factor and present value.

Key-rate durations

A parallel DV01 treats the curve as one number. Key-rate durations split it by maturity. Each pillar's zero rate is moved up and then down by 1 bp on its own and the curve is rebuilt. The bond's change in value is the central difference:

KRDₖ = −[P(zₖ + 1bp) − P(zₖ − 1bp)] / 2

The curve is re-fitted after each shock, so the shape of the bump between pillars is whatever the chosen interpolation implies, rather than Ho's imposed triangle. The two agree for a local scheme. The key-rate durations add up to about the parallel DV01, but not exactly, because several single-pillar shocks are not the same as one parallel shift.

Hedging

The position is the bond from "Price a bond". The hedges are Treasuries issued on the curve date at par, one per chosen maturity, priced off the same curve.

DV01 hedge: one bond, sized so a parallel 1 bp move leaves the total unchanged.

n = −DV01(position) / DV01(hedge)

Key-rate hedge: one hedge per chosen pillar. With A[t][h] the key-rate DV01 of hedge h at pillar t, and b[t] the position's, solve

A · n = −b

The hedged position then has zero DV01 at every chosen pillar. Unchosen pillars keep whatever exposure is left, and the lab shows it bar by bar. A set of hedges that cannot be solved, such as two hedges with the same exposure, is refused with the reason.

The rate tree

Callable and putable bonds are valued on a Kalotay-Williams-Fabozzi binomial tree of one-year rates. At each year the rates are spaced by the volatility:

r(i, j) = r(i, 0) · e^(2σj),   j = 0 … i

The lowest rate of each year is either typed in, as in the workbook, or calibrated so that the tree prices each par bond at exactly 100. The bond is then valued backward from maturity:

V(i, j) = ½ · [(V(i+1, j+1) + C) + (V(i+1, j) + C)] / (1 + r(i, j))
callable: V = min(V, call price)     putable: V = max(V, put price)

The exercise check starts from the first exercise year. The option's value is the straight bond's value minus the callable bond's. On the workbook's inputs the tree gives 99.8150, the workbook's own answer; on the final exam's NVIDIA callable it gives 982.2212.

The convertible tree

A convertible lets its holder swap the bond for shares. The stock follows a Cox-Ross-Rubinstein tree with annual steps:

u = e^σ,   d = 1/u,   p = (e^(r − q) − d) / (u − d)
hold    = (p · V_up + (1 − p) · V_down) / e^r + coupon
convert = conversion ratio × S  (+ coupon, if the terms pay it on conversion)
V       = max(hold, convert)

At maturity, holding is worth the face plus the last coupon. Today's node carries no coupon, because none is paid today. On the workbook's inputs the tree gives 1,504.0111, the workbook's answer.

The coursework models

The Basics area rebuilds the models from my fixed income derivatives course. Each opens on the workbook's own inputs and shows each workbook cell beside the number it gets. bondlab's tests check every one of those cells.

ModelWorkbook sheetMatches
Price, coupon and maturity effectsCoupon, MaturityTo 10⁻⁸
Price over time, yield changeTime path, Yield ChangeTo 10⁻⁸
Duration and convexityDuration and ConvexityTo 10⁻⁶
Duration's tangent lineTangencyTo 10⁻⁶
BootstrappingBootstrappingTo Goal Seek's precision (see below)
Callable bond on a rate treeBinomial Tree; final exam Q1To 10⁻⁸
Convertible bondConvertible BondTo 10⁻⁸

The workbook solved its bootstrapped spot rates with Goal Seek, which stops about 0.0001 percentage points short of the exact answer. bondlab solves exactly. Rebuilding the sheet also turned up one error in it. The three-year spot rate (the sixth semiannual period) reads a coupon from an empty cell (=E22/2 where =E13/2 was meant), which leaves the fourth coupon undiscounted and shows 6.7017% instead of 6.5543%. The lab gives the corrected value and says so beside it.

The workbook's Black-Scholes sheet is not repeated here: the options toolprices options with the same formula.

The engine

bondlab is written in Python with numpy and scipy, type-checked with mypy in strict mode, and tested against independent sources: the workbooks above, the Treasury's own published files, and textbook examples. Every formula in its code names its source. Conventions are never defaulted. A Treasury or a corporate bond is built from a named preset that writes its conventions out.

The lab sends what is on screen to the API and draws what comes back. The browser does no finance of its own, so every number on screen can be reproduced by calling bondlab directly.