Duration Metrics
Calculates the duration of individual bonds at their yield to maturity. It has the option to calculate the following type of bond durations:
- Macaulay’s Duration: The weighted average time to receive the bond’s cash flows.
- Modified Duration: The Macaulay’s duration divided by 1 plus the per-period yield (YTM / 2).
- Effective Duration: The percentage change in the bond price for a 1% change in the yield to maturity.
- Dollar Duration: The modified duration multiplied by the bond price, divided by 100.
These duration measures can be used to estimate the sensitivity of a bond’s price to changes in interest rates as well as to compare the risk of different bonds. The modified duration is particularly useful for estimating the percentage change in the bond price for a 1% change in the yield to maturity. Note that it is a percentage sensitivity and therefore not the same as the dollar duration, the price value of a basis point (PVBP) or the dollar value of a 0.01% change (DV01), which are all expressed as a currency amount instead. The DV01 is part of collect_bond_statistics.
The formula is as follows (the default is the modified duration):
\[\operatorname{PV}(t) = \text{Cash Flow} (t) / (1 + \text{YTM} / 2) ^{2t},\;\; \text{with coupons of Coupon} / 2 \;\text{per}\; 100 \;\text{of par and the principal repaid with the last coupon}\] \[\text{Dirty Price} = \operatorname{SUM}(\operatorname{PV}(t)),\;\; \text{over the remaining payment times t in years on the actual coupon dates}\] \[\text{Macaulay's Duration} = \operatorname{SUM}(t \cdot \operatorname{PV}(t)) / \text{Dirty Price}\] \[\text{Modified Duration} = \text{Macaulay's Duration} / (1 + \text{YTM} / 2)\] \[\text{Effective Duration} = (\text{Dirty Price} (\text{YTM} - 0.01) - \text{Dirty Price} (\text{YTM} + 0.01)) / (2 \cdot \text{Dirty Price} \cdot 0.01)\] \[\text{Dollar Duration} = \text{Modified Duration} \cdot \text{Dirty Price} / 100\]Where YTM is the bond’s yield to maturity at its market price, compounded twice a year (see get_yield_to_maturity). The bonds are selected as in collect_bond_statistics.
Modified duration is the first estimate of interest rate risk: a modified duration of 7 means the price falls by about 7% if the yield rises by one percentage point. The estimate worsens for larger moves, which convexity corrects (see get_taylor_price_change), and it assumes the cash flows are fixed. For callable bonds the relevant measure is an effective duration from a model that values the embedded option, which this method does not include. For terms of your own, use the duration functions of bond_model.
Also known as: Macaulay duration, modified duration, bond price sensitivity.
Duration Metrics in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_duration as shown below.
from financetoolkit import FixedIncome
fixedincome = FixedIncome()
durations = fixedincome.get_duration(date="2026-11-05")
durations[["Security Type", "Coupon", "Maturity", "Price", "Modified Duration"]]
Or, after setting up the Finance Toolkit MCP, ask:
What was the modified duration of the benchmark 2- to 30-year US Treasuries on 5 November 2026?
Which returns:
| Security Type | Coupon | Maturity | Price | Modified Duration | |
|---|---|---|---|---|---|
| 91282CRU7 | Note | 0.0462 | 2028-10-31 | 100.312 | 1.8777 |
| 91282CLR0 | Note | 0.0412 | 2029-10-31 | 98.875 | 2.7748 |
| 91282CRT0 | Note | 0.0475 | 2031-10-31 | 100.688 | 4.3963 |
| 91282CRV5 | Note | 0.0488 | 2033-10-31 | 101.062 | 5.8687 |
| 91282CRF0 | Note | 0.0462 | 2036-08-15 | 98.4375 | 7.6914 |
| 912810RU4 | Bond | 0.0288 | 2046-11-15 | 70.0312 | 13.6289 |
| 912810UW6 | Bond | 0.0512 | 2056-08-15 | 98.125 | 14.8801 |
Parameters
get_duration accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
duration_type | str | The duration: “modified”, “macaulay”, “effective” or “dollar”. Defaults to “modified”. | "macaulay" |
bonds | list[str] | str | None | CUSIPs or ISINs, see collect_bond_statistics. Defaults to None. | None |
issuer | list[str] | str | None | Part of an issuer’s name, such as “Apple”. Defaults to None. | None |
etfs | list[str] | str | None | The bond ETFs to select bonds from, see get_bond_universe. Defaults to None. | None |
maturity_start | str | None | The earliest maturity (YYYY-MM-DD). Defaults to None. | None |
maturity_end | str | None | The latest maturity (YYYY-MM-DD). Defaults to None. | None |
date | str | None | The day of the Treasury prices (YYYY-MM-DD). Defaults to None, the latest day with prices. | "2025-03-31" |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the class. | 2 |