FinanceModels.Yield API Reference

zero(curve,time)

Return the zero rate for the curve at the given time.

discount(yc, to)
discount(yc, from,to)

The discount factor for the yield curve yc for times from through to.

forward(yc, from, to)˚

The forward Rate implied by the yield curve yc between times from and to.

par(curve,time;frequency=2)

Calculate the par yield for maturity time for the given curve and frequency. Returns a Rate object with periodicity corresponding to the frequency. The exception to this is if time is less than what the payments allowed by frequency (e.g. a time 0.5 but with frequency 1) will effectively assume frequency equal to 1 over time.

Examples

julia> c = Yield.Constant(0.04);

julia> par(c,4)
Rate{Float64, Periodic}(0.03960780543711406, Periodic(2))

julia> par(c,4;frequency=1)
Rate{Float64, Periodic}(0.040000000000000036, Periodic(1))

julia> par(c,0.6;frequency=4)
Rate{Float64, Periodic}(0.039413626195875295, Periodic(4))

julia> par(c,0.2;frequency=4)
Rate{Float64, Periodic}(0.039374942589460726, Periodic(5))

julia> par(c,2.5)
Rate{Float64, Periodic}(0.03960780543711406, Periodic(2))

AbstractYieldShift <: AbstractYieldModel

Supertype for lazy zero-rate shift models: a curve produced by transforming a base yield curve's zero rate via a user-supplied rule.

Two concrete subtypes:

• TenorShift — shift depends only on the tenor t. Use for parallel bumps, twists, butterflies — static curve transformations.
• ProjectedShift — shift depends on the tenor t and on a second time axis τ (projection / as-of / valuation-date time). Use for phase-in profiles (BMA SBA, IFRS17 macro scenarios) and any shift whose shape evolves across a projection horizon.

Both subtypes implement the standard AbstractYieldModel interface (zero, discount, forward, pv).

CairnsPritchard(c₁, c₂, b₀, b₁, b₂)
CairnsPritchard(c₁=0.5, c₂=3.0) # used in fitting

A Cairns-Pritchard yield curve model with 2 exponential components.

The continuous zero rate at time t is:

$r(t) = b₀ + b₁ \exp(-c₁ t) + b₂ \exp(-c₂ t)$

This is a generalization of Nelson-Siegel with independent decay rates per exponential component. Parameters and default fitting bounds:

• c₁ decay rate for first component: 0.001 .. 10.0
• c₂ decay rate for second component: 0.001 .. 10.0
• b₀ long-term rate level: -1.0 .. 1.0
• b₁ first exponential coefficient: -10.0 .. 10.0
• b₂ second exponential coefficient: -10.0 .. 10.0

See also CairnsPritchardExtended for a 3-component variant.

References

• Cairns, A.J.G. (1998). "Descriptive Bond-Yield and Forward-Rate Models for the British Government Securities Market". British Actuarial Journal, 4(2), 265-321.

CairnsPritchardExtended(c₁, c₂, c₃, b₀, b₁, b₂, b₃)
CairnsPritchardExtended(c₁=0.5, c₂=2.0, c₃=5.0) # used in fitting

A Cairns-Pritchard yield curve model with 3 exponential components.

The continuous zero rate at time t is:

$r(t) = b₀ + b₁ \exp(-c₁ t) + b₂ \exp(-c₂ t) + b₃ \exp(-c₃ t)$

Parameters and default fitting bounds:

• c₁ decay rate for first component: 0.001 .. 10.0
• c₂ decay rate for second component: 0.001 .. 10.0
• c₃ decay rate for third component: 0.001 .. 10.0
• b₀ long-term rate level: -1.0 .. 1.0
• b₁ first exponential coefficient: -10.0 .. 10.0
• b₂ second exponential coefficient: -10.0 .. 10.0
• b₃ third exponential coefficient: -10.0 .. 10.0

See also CairnsPritchard for a 2-component variant.

References

• Cairns, A.J.G. (1998). "Descriptive Bond-Yield and Forward-Rate Models for the British Government Securities Market". British Actuarial Journal, 4(2), 265-321.

CompositeYield(curve1,curve2,operation)

Combines two yield curves by applying operation to their continuous zero rates.

Given discount factors DF₁(t) and DF₂(t), the continuous zero rates are z₁ = -log(DF₁)/t and z₂ = -log(DF₂)/t, and the composite discount factor is exp(-op(z₁, z₂) * t).

For addition (+), this gives DF(t) = DF₁(t) × DF₂(t) (the no-arbitrage spread relationship). For subtraction (-), this gives DF(t) = DF₁(t) / DF₂(t).

Created via + and - on AbstractYieldModel objects. For scalar multiplication/division, see ScaledYield.

Composition is performed in continuous-zero-rate space: a +/- composite reads each component's zero rate, combines them, and applies a single exp to form the discount factor — it no longer pays the log/exp round-trip that earlier versions did. Composing many curves in a hot loop is still marginally slower than pre-fitting a single combined curve, but the gap is small.

Curves can be added or subtracted together, but note that this is not always the same thing as adding or subtracting spreads with rates. If spreads and base rates are expressed as zero rates, then the curve addition/subtraction has the same effect as re-fitting the yield model with the rate+spread inputs added together first. Non-zero rates (e.g. par rates) do not have this same property.

Examples

rates = [0.01, 0.01, 0.03, 0.05, 0.07, 0.16, 0.35, 0.92, 1.40, 1.74, 2.31, 2.41] ./ 100
spreads = [0.01, 0.01, 0.03, 0.05, 0.07, 0.16, 0.35, 0.92, 1.40, 1.74, 2.31, 2.41] ./ 100
mats = [1 / 12, 2 / 12, 3 / 12, 6 / 12, 1, 2, 3, 5, 7, 10, 20, 30]


### Zero coupon rates/spreads

q_rf_z = ZCBYield.(rates,mats)
q_s_z = ZCBYield.(spreads,mats)
q_y_z = ZCBYield.(rates + spreads,mats)

c_rf_z = fit(Spline.Linear(),q_rf_z,Fit.Bootstrap())
c_s_z = fit(Spline.Linear(),q_s_z,Fit.Bootstrap())
c_y_z = fit(Spline.Linear(),q_y_z,Fit.Bootstrap())

# adding curves when the spreads were zero spreads works
@test discount(c_rf_z+c_s_z,20) ≈ discount(c_y_z,20)


### Par coupon rates/spreads

q_rf = CMTYield.(rates,mats)
q_s = CMTYield.(spreads,mats)
q_y = CMTYield.(rates + spreads,mats)

c_rf = fit(Spline.Linear(),q_rf,Fit.Bootstrap())
c_s = fit(Spline.Linear(),q_s,Fit.Bootstrap())
c_y = fit(Spline.Linear(),q_y,Fit.Bootstrap())

# adding curves when the spreads were par spreads does not work
@test !(discount(c_rf+c_s,20) ≈ discount(c_y,20))

Constant(rate)

A yield curve representing a flat term structure. rate can be a Rate object or a Real object.

If fiting with the default FinanceModels.jl settings, the solver will attempt to fit a discount rate with the range of: -1.0 .. 1.0

ForwardStarting(curve,forwardstart)

Rebase a curve so that discount/accumulation/etc. are re-based so that time zero from the new curves perspective is the given forwardstart time.

Examples

julia> zero = [5.0, 5.8, 6.4, 6.8] ./ 100
julia> maturity = [0.5, 1.0, 1.5, 2.0]
julia> curve = ZeroRateCurve(zero, maturity)
julia> fwd = Yield.ForwardStarting(curve, 1.0)

julia> discount(curve,1,2)
0.9275624570410582

julia> discount(fwd,1) # `curve` has effectively been reindexed to `1.0`
0.9275624570410582

Extended Help

While ForwardStarting could be nested so that, e.g. the third period's curve is the one-period forward of the second period's curve, it will be more efficient to reuse the initial curve from a runtime and compiler perspective.

ForwardStarting is not used to construct a curve based on forward rates.

MonotoneConvex(rates, times)

A Monotone Convex yield curve model implementing the Hagan-West interpolation method.

This interpolation method guarantees:

• Continuous forward rates
• Positive forward rates (when input rates imply positive forwards)
• Monotone convex forward curves that match discrete forward rates at knot points

The implementation follows the Hagan-West method as described in WILMOTT magazine.

Examples

prices = [0.98, 0.955, 0.92, 0.88, 0.830]
times = [1, 2, 3, 4, 5]
rates = @. -log(prices) / times

c = Yield.MonotoneConvex(rates, times)
zero(c, 2.5)  # Get the zero rate at t=2.5
discount(c, 2.5)  # Get the discount factor at t=2.5

References

• Hagan & West, "Interpolation Methods for Curve Construction", WILMOTT magazine
• Dehlbom, "Interpolation of the yield curve" (http://uu.diva-portal.org/smash/get/diva2:1477828/FULLTEXT01.pdf)

NelsonSiegel(β₀, β₁, β₂, τ₁)
NelsonSiegel(τ₁=1.0) # used in fitting

A Nelson-Siegel yield curve model Parameters of Nelson and Siegel (1987) parametric model, along with default parameter ranges used in the fitting:

• β₀ represents a long-term interest rate: -10.0 .. 10.0
• β₁ represents a time-decay component: -10.0 .. 10.0
• β₂ represents a hump: -10.0 .. 10.0
• τ₁ controls the location of the hump: 0.0 .. 100.0

Examples

julia> β₀, β₁, β₂, τ₁ = 0.6, -1.2, -1.9, 3.0
julia> nsm = Yield.NelsonSiegel(β₀, β₁, β₂, τ₁)

# Extended Help

NelsonSiegel has generally been replaced by NelsonSiegelSvensson, which is a more flexible model.

## References
- https://onriskandreturn.com/2019/12/01/nelson-siegel-yield-curve-model/
- https://www.bis.org/publ/bppdf/bispap25.pdf

NelsonSiegelSvensson(τ₁, τ₂, β₀, β₁, β₂, β₃)
NelsonSiegelSvensson(τ₁=1.0, τ₂=1.0)

Return the NelsonSiegelSvensson yield curve. The rates should be continuous zero spot rates. If rates are not Rates, then they will be interpreted as Continuous Rates.

Parameters of Svensson (1994) parametric model, along with the default parameter bounds used in the fit routine:

• τ₁ controls the location of the hump: 0.0 .. 100.0
• τ₁ controls the location of the second hump: 0.0 .. 100.0
• β₀ represents a long-term interest rate: -10.0 .. 10.0
• β₁ represents a time-decay component: -10.0 .. 10.0
• β₂ represents a hump: -10.0 .. 10.0
• β₃ represents a second hump: -10.0 .. 10.0

Examples

julia> β₀, β₁, β₂, β₃, τ₁, τ₂ = 0.6, -1.2, -2.1, 3.0, 1.5
julia> nssm = NelsonSiegelSvensson.NelsonSiegelSvensson.(β₀, β₁, β₂, β₃, τ₁, τ₂)

# Extended Help

Nelson-Siegel-Svensson Pros:

- Simplicity: With only six parameters, the model is quite parsimonious and easy to estimate. It's also easier to interpret and communicate than more complex models.
- Economic Interpretability: Each of the model's components can be given an economic interpretation, with parameters representing long term rate, short term rate, the rates of decay towards the long term rate, and humps in the yield curve.

Nelson-Siegel-Svensson Cons:

- Unusual Curves: NSS makes some assumptions about the shape of the yield curve (e.g. generally has a hump in short to medium term maturities). It might not be the best choice for fitting unusual curves.
- Arbitrage Opportunities: The NSS model does not guarantee absence of arbitrage opportunities. More sophisticated models, like the ones based on no-arbitrage conditions, might provide better pricing accuracy in some contexts.
- Sensitivity: Similar inputs may produce different parameters due to the highly convex, non-linear region to solve for the parameters. Entities like the ECB will partially mitigate this by using the prior business day's parameters as the starting point for the current day's yield curve.

## References
- https://onriskandreturn.com/2019/12/01/nelson-siegel-yield-curve-model/
- https://www.bis.org/publ/bppdf/bispap25.pdf

ProjectedShift(base, rule, time)

Lazy zero-rate transformation that depends on the tenor t and a second time axis τ:

z_new(t) = rule(τ, z_base(t), t)

τ (stored as the .time field) is the projection time — the as-of or valuation-date offset at which this curve is being evaluated. It is distinct from the tenor t, which is time-to-maturity from τ.

The rule function must have the signature (τ, z::Rate, t) -> Rate. The return value is type-asserted as Rate so that compounding convention is always carried explicitly; rules returning a plain Real will raise a TypeError at call time.

Use this for shifts whose shape evolves across a projection horizon — phase-in profiles (BMA SBA, IFRS17 macro scenarios), runoff schedules, calendar-rolling shocks. For static, tenor-only shifts, see TenorShift.

Constructing

There is no + operator sugar — ProjectedShift needs an explicit τ, which fixing at composition time would defeat the purpose of storing the rule as a year-independent first-class value. Always use the direct constructor:

base = Yield.Constant(0.05)

# −150 bp parallel shift, phased in linearly over 10 projection years.
phase_in = (τ, z, _) -> z + Continuous(-0.015 * min(τ, 10) / 10)

# Curve as seen at projection year 3 (30% phased in → -45 bp).
c3 = ProjectedShift(base, phase_in, 3.0)

# Curve as seen at projection year 10 (fully phased in → -150 bp).
c10 = ProjectedShift(base, phase_in, 10.0)

The intended pattern: store rule once as a first-class value, then call ProjectedShift(base, rule, τ) at each τ in a projection loop.

See also: TenorShift, AbstractYieldShift.

ScaledYield(curve, factor)

A yield model that scales the continuous zero rates of curve by a Real scalar factor.

Created via curve * scalar or curve / scalar. For example, curve * 0.79 scales all continuous zero rates by 0.79, which is useful for after-tax yield calculations.

Yield.SmithWilson(u, qb; ufr=ufr, α=α)
Yield.SmithWilson(;ufr=ufr, α=α)

Create a yield curve object that implements the Smith-Wilson interpolation/extrapolation scheme.

To calibrate a curve, you generally want to construct the object without the u and qb arguments and call fit in conjunction with Quotes (fit requires no third parameter for SmithWilson curves). See Examples for what this looks like. Positional arguments to construct a curve:

• A curve can be with u is the timepoints coming from the calibration, and qb is the internal parameterization of the curve that ensures that the calibration is correct. Users may prefer the other constructors but this mathematical constructor is also available.

Required keyword arguments:

• ufr is the Ultimate Forward Rate, the forward interest rate to which the yield curve tends, in continuous compounding convention.
• α is the parameter that governs the speed of convergence towards the Ultimate Forward Rate. It can be typed with \alpha[TAB]

Examples

times = [1.0, 2.5, 5.6]
prices = [0.9, 0.7, 0.5]
qs = ZCBPrice.(prices, times)

ufr = 0.03
α = 0.1

model = fit(Yield.SmithWilson(ufr=ufr, α=α), qs)

Extended Help

References

• Smith-Wilson Yields Curves
• A Technical Note on the Smith-Wilson Method

TenorShift(base, rule)

Lazy zero-rate transformation depending only on the tenor: z_new(t) = rule(z_base(t), t).

The rule function receives the base curve's Continuous zero rate and the tenor, and returns a new rate. It is evaluated on demand — no discretization or refitting. The base curve's analytic structure is fully preserved.

The rule function must have the signature (z::Rate, t) -> Rate. The return value is type-asserted as Rate so that compounding convention is always carried explicitly; rules returning a plain Real will raise a TypeError at call time. Use z + Continuous(0.01), Periodic(0.04, 2), etc., and let Rate arithmetic handle conversion to the curve's continuous representation.

Use this for static shifts — parallel bumps, twists, butterflies — that don't depend on where you are in projection time. For shifts whose shape evolves across a projection horizon, see ProjectedShift.

Constructing

The most ergonomic way to create a TenorShift is via the + operator with an AbstractYieldModel and a two-argument function:

base = Yield.Constant(0.05)

# Parallel shift (+100 bp)
base + (z, t) -> z + Periodic(0.01, 1)

# Tenor-dependent twist (steepener that fades at 30y)
base + (z, t) -> z + Continuous(0.02 * max(0.0, 1.0 - t/30.0))

You can also construct directly:

TenorShift(base, (z, t) -> z + Continuous(0.01))

Note: The + operator dispatches on Function. For callable objects that are not Function subtypes (e.g. custom structs with call syntax), use the direct constructor: TenorShift(base, my_callable).

TenorShift is a post-processing wrapper — it is not a fitting target. ForwardDiff propagates correctly through the transform for sensitivity analysis, but the rule function itself should be differentiable if used in an AD context.

TransformedYield is retained as a deprecated alias for TenorShift.

See also: ProjectedShift, AbstractYieldShift, CompositeYield, ScaledYield.

ZeroRateCurve(rates, tenors, [spline])
ZeroRateCurve(curve::AbstractYieldModel, tenors; spline=Spline.MonotoneConvex())

A yield curve defined by continuously-compounded zero rates at specified tenors, with interpolation between tenors via the existing Spline infrastructure.

The spline argument is a Spline.SplineCurve object (e.g. Spline.MonotoneConvex(), Spline.PCHIP(), Spline.Linear(), Spline.Cubic()). Defaults to Spline.MonotoneConvex().

The curve stores the raw rates vector, making it compatible with ForwardDiff: construct ZeroRateCurve(dual_rates, tenors, spline) inside an AD closure and the interpolation will propagate dual numbers.

Constructing from another yield model

The second form samples zero rates from any AbstractYieldModel (e.g. Yield.Constant, Yield.NelsonSiegel, a fitted spline curve, etc.) at the specified tenors, producing a ZeroRateCurve suitable for key rate analysis with ActuaryUtilities.jl. All tenors must be positive (t > 0).

Examples

using FinanceModels

rates = [0.02, 0.03, 0.035, 0.04]
tenors = [1.0, 2.0, 5.0, 10.0]

zrc = ZeroRateCurve(rates, tenors)                              # default: MonotoneConvex
zrc_pchip = ZeroRateCurve(rates, tenors, Spline.PCHIP())        # PCHIP
zrc_lin = ZeroRateCurve(rates, tenors, Spline.Linear())          # linear
zrc_cubic = ZeroRateCurve(rates, tenors, Spline.Cubic())         # cubic

discount(zrc, 1.0)   # exp(-0.02 * 1.0)
discount(zrc, 3.5)   # interpolated rate at t=3.5
zero(zrc, 5.0)       # Continuous(0.035)

# From a NelsonSiegel model:
ns = Yield.NelsonSiegel(1.0, 0.04, -0.02, 0.01)
zrc_ns = ZeroRateCurve(ns, [1.0, 2.0, 5.0, 10.0, 20.0])

Performance note

discount reconstructs the interpolation model on each call for AD compatibility (dual numbers must flow through the interpolation). For non-AD usage where discount is called many times on the same curve, construct Yield.build_model(zrc.spline, zrc.tenors, zrc.rates) once and use that instead. The AD pathway in ActuaryUtilities builds the model once per gradient step, avoiding this per-call overhead.

Forward curve smoothness

The default Spline.MonotoneConvex() guarantees positive continuous forward rates and produces C1-smooth forward curves (Hagan & West, 2006). For C2 smoothness, use Spline.Cubic(). Spline.Linear() produces kinks in the forward curve at tenor points.

curve * scalar
scalar * curve

Scale the continuous zero rates of curve by a Real scalar. Returns a ScaledYield.

This is useful for after-tax yield calculations. For example, curve * 0.79 produces a curve whose continuous zero rate at every point is 79% of the original.

Examples

julia> m = Yield.Constant(Continuous(0.05)) * 0.79;

julia> discount(m, 1) ≈ exp(-0.05 * 0.79)
true

Yield.AbstractYieldModel + Yield.AbstractYieldModel

The addition of two yields will create a CompositeYield. For rate, discount, and accumulation purposes the spot rates of the two curves will be added together.

Yield.AbstractYieldModel - Yield.AbstractYieldModel

The subtraction of two yields will create a CompositeYield. For rate, discount, and accumulation purposes the spot rates of the second curves will be subtracted from the first.

curve / scalar

Scale the continuous zero rates of curve by 1/scalar. Returns a ScaledYield.

This is useful for grossing-up a yield to a pre-tax equivalent.

Examples

julia> m = Yield.Constant(Continuous(0.05)) / 0.79;

julia> discount(m, 1) ≈ exp(-0.05 / 0.79)
true

accumulation(yc, from, to)

The accumulation factor for the yield curve yc for times from through to.

H(α, t1, t2)

The Smith-Wilson H function implemented in a faster way.

H_ordered(α, t_min, t_max)

The Smith-Wilson H function with ordered arguments (for better performance than using min and max).

returns the index associated with the time t, an initial rate vector, and a time vector

returns a pair of vectors (f and fᵈ) used in Monotone Convex Yield Curve fitting

build_model(spline, tenors, rates)

Build a yield model from a SplineCurve type descriptor, tenor times, and rates. Returns an AbstractYieldModel that supports discount() and callable (t) syntax.

Used by ZeroRateCurve and the AD pathway in ActuaryUtilities to construct the interpolation model efficiently (once per gradient step rather than per discount call).

g_rate(x, f⁻, f, fᵈ)

Compute the integrated deviation G(x) = ∫₀ˣ g(u) du, which captures how the instantaneous forward curve deviates from the discrete forward across an interval. This quantity feeds into the zero-rate relation r(t) = fᵈ + (Δt / t) ⋅ G(x) used by the Hagan-West construction.