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 = Yields.Constant(0.04);

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

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

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

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

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

CompositeYield(curve1,curve2,operation)

Creates a datastructure that will perform the given operation after independently calculating the effects of the two curves. Can only be created via the public API by using the +, -, *, and / operatations on AbstractYield objects.

As this is double the normal operations when performing calculations, if you are using the curve in performance critical locations, you should consider transforming the inputs and constructing a single curve object ahead of time.

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 = Yields.Zero(zero, maturity)
julia> fwd = Yields.ForwardStarting(curve, 1.0)

julia> FinanceCore.discount(curve,1,2)
0.9275624570410582

julia> FinanceCore.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.

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 = Yields.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

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

Yields.AbstractYieldModel * Yields.AbstractYieldModel

The multiplication of two yields will create a CompositeYield. For rate, discount, and accumulation purposes the spot rates of the two curves will be added together. This can be useful, for example, if you wanted to after-tax a yield.

Examples

julia> m = Yields.Constant(0.01) * 0.79;

julia> accumulation(m,1)
1.0079

julia> accumulation(.01*.79,1)
1.0079

Yields.AbstractYieldModel + Yields.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.

Yields.AbstractYieldModel - Yields.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.

Yields.AbstractYieldModel / Yields.AbstractYieldModel

The division of two yields will create a CompositeYield. For rate, discount, and accumulation purposes the spot rates of the two curves will have the first divided by the second. This can be useful, for example, if you wanted to gross-up a yield to be pre-tax.

Examples

julia> m = Yields.Constant(0.01) / 0.79;

julia> accumulation(d,1)
1.0126582278481013

julia> accumulation(.01/.79,1)
1.0126582278481013

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).