# FinanceModels.Yield API Reference

`FinanceModels.Yield.CompositeYield`

`FinanceModels.Yield.Constant`

`FinanceModels.Yield.ForwardStarting`

`FinanceModels.Yield.NelsonSiegel`

`FinanceModels.Yield.NelsonSiegelSvensson`

`FinanceModels.Yield.SmithWilson`

`FinanceModels.Yield.H`

`FinanceModels.Yield.H_ordered`

`FinanceModels.Yield.par`

## Exported API

`Base.zero`

— Method`zero(curve,time)`

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

`FinanceCore.discount`

— Method```
discount(yc, to)
discount(yc, from,to)
```

The discount factor for the yield curve `yc`

for times `from`

through `to`

.

`FinanceCore.forward`

— Method`forward(yc, from, to)˚`

The forward `Rate`

implied by the yield curve `yc`

between times `from`

and `to`

.

`FinanceModels.Yield.par`

— Method`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))
```

## Unexported API

`FinanceModels.Yield.CompositeYield`

— Type`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.

`FinanceModels.Yield.Constant`

— Type`FinanceModels.Yield.ForwardStarting`

— Type`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.

`FinanceModels.Yield.NelsonSiegel`

— Type```
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
```

`FinanceModels.Yield.NelsonSiegelSvensson`

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

Return the NelsonSiegelSvensson yield curve. The rates should be continuous zero spot rates. If `rates`

are not `Rate`

s, then they will be interpreted as `Continuous`

`Rate`

s.

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
```

`FinanceModels.Yield.SmithWilson`

— Type```
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**

`Base.:*`

— 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
```

`Base.:+`

— Method`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.

`Base.:-`

— Method`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.

`Base.:/`

— Method`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
```

`FinanceCore.accumulation`

— Method`accumulation(yc, from, to)`

The accumulation factor for the yield curve `yc`

for times `from`

through `to`

.

`FinanceModels.Yield.H`

— Method`H(α, t1, t2)`

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

`FinanceModels.Yield.H_ordered`

— Method`H_ordered(α, t_min, t_max)`

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

Please open an issue if you encounter any issues or confusion with the package.