Financial Math Submodule

Provides a set of common routines in financial maths.

Quickstart

using ActuaryUtilities

cfs = [5, 5, 105]
times    = [1, 2, 3]

discount_rate = 0.03

present_value(discount_rate, cfs, times)           # 105.65
duration(Macaulay(), discount_rate, cfs, times)    #   2.86
duration(discount_rate, cfs, times)                #   2.78
convexity(discount_rate, cfs, times)               #  10.62

Floating-rate, multi-curve & portfolios

Macaulay/Modified duration are for fixed cashflows. For a floating-rate bond, a portfolio, or any curve-dependent contract, pass the contract directly — duration(Effective(), contract, curve, tenors) / duration(Spread(), …) / dv01(…) re-project the coupons and give the rate-vs-spread durations (years and DV01s); sensitivities(contract, curve, tenors) returns the full bundle, and sensitivities(contract, tenors; discount = (; rf, credit, ilp), index = …) does the multi-curve decomposition. See Key Rate Sensitivities.

Curve Transformations

FinanceModels.Yield.TenorShift lets you lazily transform any yield curve's zero rates via curve + (z, t) -> new_rate. This is useful for scenario analysis (parallel shifts, twists, stresses) without refitting.

Parallel shift

using ActuaryUtilities, FinanceModels, FinanceCore

base = Yield.Constant(Continuous(0.05))
shifted = base + (z, t) -> z + Continuous(0.01)   # +100 bp parallel

zero(shifted, 1.0)

Continuous(0.060000000000000005)

Periodic rate arithmetic

Rate arithmetic automatically handles compounding conversion — a Periodic(0.01, 1) bump converts to continuous internally:

shifted_p = base + (z, t) -> z + Periodic(0.01, 1)
zero(shifted_p, 5.0)   # ≈ Continuous(0.05 + log(1.01))

Continuous(0.059950330853168095)

Tenor-dependent twist

A steepener that fades at 30y:

twist = base + (z, t) -> z + Continuous(0.02 * max(0.0, 1.0 - t / 30.0))
(zero(twist, 1.0), zero(twist, 15.0), zero(twist, 30.0))

(Continuous(0.06933333333333333), Continuous(0.060000000000000005), Continuous(0.05))

PV comparison under stress

cfs = [5.0, 5.0, 5.0, 105.0]
times = [1.0, 2.0, 3.0, 4.0]

pv_base = present_value(base, cfs, times)
pv_shifted = present_value(shifted, cfs, times)
pct_change = (pv_shifted - pv_base) / pv_base * 100
(; pv_base = round(pv_base, digits=4), pv_shifted = round(pv_shifted, digits=4), pct_change = round(pct_change, digits=2))

(pv_base = 99.5506, pv_shifted = 95.9157, pct_change = -3.65)

Bootstrapped curve + stress

quotes = ZCBYield.([0.04, 0.05, 0.055, 0.06], [1.0, 3.0, 5.0, 10.0])
fitted = fit(Spline.Linear(), quotes, Fit.Bootstrap())
stressed = fitted + (z, t) -> z + Continuous(0.005)   # +50 bp

dur_base = duration(fitted, cfs, times)
dur_stressed = duration(stressed, cfs, times)
(; dur_base = round(dur_base, digits=4), dur_stressed = round(dur_stressed, digits=4))

(dur_base = 3.719, dur_stressed = 3.716)

Negative rates

Real-world EUR/JPY/CHF scenarios with negative base rates:

neg = Yield.Constant(Continuous(-0.01))
shifted_neg = neg + (z, t) -> z + Continuous(0.005)
(; rate = zero(shifted_neg, 5.0), df = round(discount(shifted_neg, 5.0), digits=6))

(rate = Continuous(-0.005), df = 1.025315)

API

Exported API

ActuaryUtilities.FinancialMath.CS01 — Type

CS01 <: Duration

Credit Spread 01. The dollar change in value for a 1 basis point parallel shift in the credit spread, holding the risk-free (base) curve constant.

Requires both a base curve and credit spread to be specified. For a flat additive decomposition, CS01 ≈ IR01 ≈ DV01.