Documentation

# fitNelsonSiegel

Fit Nelson-Siegel function to bond market data

## Class

`@IRFunctionCurve`

## Syntax

```CurveObj = IRFunctionCurve.fitNelsonSiegel(Type,Settle,Instruments)
CurveObj = IRFunctionCurve.fitNelsonSiegel(Type,Settle,Instruments,Name,Value)
```

## Arguments

 `Type` Type of interest-rate curve for a bond: `zero` or `forward`. `Settle` Scalar for the `Settle` date of the curve. `Instruments` `N`-by-`4` data matrix for `Instruments` where the first column is `Settle` date, the second column is `Maturity`, the third column is the clean price, and the fourth column is a `CouponRate` for the bond. `Compounding` (Optional) Scalar that sets the compounding frequency per year for the `IRFunctionCurve` object: `-1` = Continuous compounding `Basis` (Optional) Day-count basis of the interest-rate curve. A scalar of integers. 0 = actual/actual (default)1 = 30/360 (SIA)2 = actual/3603 = actual/3654 = 30/360 (BMA)5 = 30/360 (ISDA)6 = 30/360 (European)7 = actual/365 (Japanese)8 = actual/actual (ICMA)9 = actual/360 (ICMA)10 = actual/365 (ICMA)11 = 30/360E (ICMA) 12 = actual/365 (ISDA)13 = BUS/252 For more information, see Basis. `IRFitOptions` (Optional) Object constructed from `IRFitOptions`. When using `IRFitOption`, the default `FitType` is `DurationWeightedPrice`. Duration weighted price refers to the form of the objective function that needs to be minimized to find the optimal Nelson-Siegel parameters. Specifically, this objective function minimizes using the following three algorithms: The difference between observed and model-predicted yields for each bond, `ObsY_`i – `PredY_`iThe difference between observed and model-predicted prices for each bond, `ObsP_`i – `PredP_`iThe difference between observed and model-predicted prices, weighted by the inverse of the duration of each bond (`ObsP_`i – `PredP_`i) / `D_`i. Weighting price by inverse duration converts the pricing errors into yield fitting errors, to a first approximation.

## Instrument Parameters

For each bond `Instrument`, you can specify the following additional instrument parameters as name-value pairs. For example, `InstrumentBasis` distinguishes a bond instrument's `Basis` value from the curve's `Basis` value.

 `InstrumentPeriod` (Optional) Coupons per year of the bond. A vector of integers. Allowed values are `0`, `1`, `2` (default), `3`, `4`, `6`, and `12`. `InstrumentBasis` (Optional) Day-count basis of the bond. A vector of integers. 0 = actual/actual (default)1 = 30/360 (SIA)2 = actual/3603 = actual/3654 = 30/360 (BMA)5 = 30/360 (ISDA)6 = 30/360 (European)7 = actual/365 (Japanese)8 = actual/actual (ICMA)9 = actual/360 (ICMA)10 = actual/365 (ICMA)11 = 30/360E (ICMA) 12 = actual/365 (ISDA)13 = BUS/252 For more information, see Basis (Financial Toolbox). `InstrumentEndMonthRule` (Optional) End-of-month rule. A vector. This rule applies only when `Maturity` is an end-of-month date for a month having 30 or fewer days. `0` = ignore rule, meaning that a bond's coupon payment date is always the same numerical day of the month. `1` = set rule on (default), meaning that a bond's coupon payment date is always the last actual day of the month. `InstrumentIssueDate` (Optional) Date when an instrument was issued. `InstrumentFirstCouponDate` (Optional) Date when a bond makes its first coupon payment; used when bond has an irregular first coupon period. When `FirstCouponDate` and `LastCouponDate` are both specified, `FirstCouponDate` takes precedence in determining the coupon payment structure. If you do not specify a `FirstCouponDate`, the cash flow payment dates are determined from other inputs. `InstrumentLastCouponDate` (Optional) Last coupon date of a bond before the maturity date; used when bond has an irregular last coupon period. In the absence of a specified `FirstCouponDate`, a specified `LastCouponDate` determines the coupon structure of the bond. The coupon structure of a bond is truncated at the `LastCouponDate`, regardless of where it falls, and is followed only by the bond's maturity cash flow date. If you do not specify a `LastCouponDate`, the cash flow payment dates are determined from other inputs. `InstrumentFace` (Optional) Face or par value. Default = `100`.

### Note

When using `Instrument` name-value pairs, you can specify simple for a bond by specifying the `InstrumentPeriod` value as `0`. If `InstrumentBasis` and `InstrumentPeriod` are not specified for a bond, the following default values are used: `Basis` is `0` (act/act) and `Period` is `2`.

## Description

```CurveObj = IRFunctionCurve.fitNelsonSiegel(Type, Settle, Instruments,Name,Value)``` fits a Nelson-Siegel function to market data for a bond. You must enter the optional arguments for `Basis`, `Compounding`, and `IRFitOptions` as comma-separated pairs of `Name`,`Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1`,`Value1`,...,`NameN`,`ValueN`.

After creating a Nelson-Siegel model, you can view the Nelson-Siegel model parameters using:

`CurveObj.Parameters`
where the order of parameters is `[Beta0,Beta1,Beta2,tau1]`.

## Examples

collapse all

This example shows how to use the Nelson-Siegel function to fit bond market data.

```Settle = repmat(datenum('30-Apr-2008'),[6 1]); Maturity = [datenum('07-Mar-2009');datenum('07-Mar-2011');... datenum('07-Mar-2013');datenum('07-Sep-2016');... datenum('07-Mar-2025');datenum('07-Mar-2036')]; CleanPrice = [100.1;100.1;100.8;96.6;103.3;96.3]; CouponRate = [0.0400;0.0425;0.0450;0.0400;0.0500;0.0425]; Instruments = [Settle Maturity CleanPrice CouponRate]; PlottingPoints = datenum('07-Mar-2009'):180:datenum('07-Mar-2036'); Yield = bndyield(CleanPrice,CouponRate,Settle,Maturity); NSModel = IRFunctionCurve.fitNelsonSiegel('Zero',datenum('30-Apr-2008'),Instruments); NSModel.Parameters```
```ans = 1×4 4.6617 -1.0227 -0.3484 1.2385 ```
```% create the plot plot(PlottingPoints, getParYields(NSModel, PlottingPoints),'r') hold on scatter(Maturity,Yield,'black') datetick('x')```

## Algorithms

The Nelson-Siegel model proposes that the instantaneous forward curve can be modeled with the following:

`$f={\beta }_{0}+{\beta }_{1}{e}^{\frac{-m}{\tau }}+{\beta }_{2}\frac{m}{\tau }{e}^{\frac{-m}{\tau }}$`

This can be integrated to derive an equation for the zero curve (see [6] for more information on the equations and the derivation):

## References

[1] Nelson, C.R., Siegel, A.F. “Parsimonious modelling of yield curves.” Journal of Business. Vol. 60, 1987, pp 473–89.

[2] Svensson, L.E.O. “Estimating and interpreting forward interest rates: Sweden 1992-4.” International Monetary Fund, IMF Working Paper, 1994/114.

[3] Fisher, M., Nychka, D., Zervos, D. “Fitting the term structure of interest rates with smoothing splines.” Board of Governors of the Federal Reserve System, Federal Reserve Board Working Paper 1995-1.

[4] Anderson, N., Sleath, J. “New estimates of the UK real and nominal yield curves.” Bank of England Quarterly Bulletin, November, 1999, pp 384–92.

[5] Waggoner, D. “Spline Methods for Extracting Interest Rate Curves from Coupon Bond Prices.” Federal Reserve Board Working Paper 1997–10.

[6] “Zero-coupon yield curves: technical documentation.” BIS Papers No. 25, October 2005.

[7] Bolder, D.J., Gusba, S. “Exponentials, Polynomials, and Fourier Series: More Yield Curve Modelling at the Bank of Canada.” Working Papers 2002–29, Bank of Canada.

[8] Bolder, D.J., Streliski, D. “Yield Curve Modelling at the Bank of Canada.” Technical Reports 84, 1999, Bank of Canada.