# fitNelsonSiegel

Fit Nelson-Siegel function to bond market data

`fitNelsonSiegel` for an `IRFunctionCurve` is not recommended. Use `fitNelsonSiegel` with a `parametercurve` object instead. For more information, see `fitNelsonSiegel`.

## Syntax

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

## Description

example

````CurveObj = IRFunctionCurve.fitNelsonSiegel(Type,Settle,Instruments)` fits a Nelson-Siegel function to market data for a bond. ```

example

````CurveObj = IRFunctionCurve.fitNelsonSiegel(___,Name,Value)` adds optional name-value pair arguments. ```

## 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.2386 ```
```% create the plot plot(PlottingPoints, getParYields(NSModel, PlottingPoints),'r') hold on scatter(Maturity,Yield,'black') datetick('x')```

## Input Arguments

collapse all

Type of interest-rate curve for a bond, specified by using a scalar character vector.

Data Types: `char`

Settle date of interest-rate curve, specified using a scalar date character vector or serial date number.

Data Types: `double` | `char`

Instruments, specified using an `N`-by-`4` data matrix 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.

Data Types: `double`

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: ```CurveObj = IRFunctionCurve.fitNelsonSiegel('Zero',datenum('30-Apr-2008'),Instruments)```

Name-Value Pair Arguments for All Bond Instruments

collapse all

Compounding frequency per-year for the `IRFunctionCurve` object, specified as the comma-separated pair consisting of `'Compounding'` and a scalar numeric using one of the supported values:

• `−1` = Continuous compounding

• `0` = Simple interest (no compounding)

• `1` = Annual compounding

• `2` = Semiannual compounding

• `3` = Compounding three times per year

• `4` = Quarterly compounding

• `6` = Bimonthly compounding

• `12` = Monthly compounding

Data Types: `double`

Day count basis of the interest-rate curve, specified as the comma-separated pair consisting of `'Basis'` and a scalar integer.

• 0 — actual/actual

• 1 — 30/360 (SIA)

• 2 — actual/360

• 3 — actual/365

• 4 — 30/360 (PSA)

• 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

Data Types: `double`

`IRFitOptions` object, specified using previously created object using `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_`i

• The difference between observed and model-predicted prices for each bond, `ObsP_`i`PredP_`i

• The 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.

Data Types: `object`

Name-Value Pair Arguments for Each Bond Instrument

collapse all

Coupons per year for the bond, specified as the comma-separated pair consisting of `'InstrumentPeriod'` and a scalar numeric value.

Data Types: `double`

Day count basis of the bond, specified as the comma-separated pair consisting of `'InstrumentBasis'` and a scalar integer.

• 0 — actual/actual

• 1 — 30/360 (SIA)

• 2 — actual/360

• 3 — actual/365

• 4 — 30/360 (PSA)

• 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

Note

`InstrumentBasis` distinguishes a bond instrument's `Basis` value from the interest-rate curve's `Basis` value.

Data Types: `double`

End-of-month rule, specified as the comma-separated pair consisting of `'InstrumentEndMonthRule'` and a logical value. 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.

Data Types: `logical`

Instrument issue date, specified as the comma-separated pair consisting of `'InstrumentIssueDate'` and a scalar date character vector or serial date number.

Data Types: `char` | `double`

Date when a bond makes its first coupon payment (used when bond has an irregular first coupon period), specified as the comma-separated pair consisting of `'InstrumentFirstCouponDate'` and a scalar date character vector or serial date number. When `InstrumentFirstCouponDate` and `InstrumentLastCouponDate` are both specified, `InstrumentFirstCouponDate` takes precedence in determining the coupon payment structure. If you do not specify a `InstrumentFirstCouponDate`, the cash flow payment dates are determined from other inputs.

Data Types: `char` | `double`

Last coupon date of a bond before the maturity date (used when bond has an irregular last coupon period), specified as the comma-separated pair consisting of `'InstrumentLastCouponDate'` and a scalar date character vector or serial date number. In the absence of a specified `InstrumentFirstCouponDate`, a specified `InstrumentLastCouponDate` determines the coupon structure of the bond. The coupon structure of a bond is truncated at the `InstrumentLastCouponDate`, regardless of where it falls, and is followed only by the bond's maturity cash flow date. If you do not specify a `InstrumentLastCouponDate`, the cash flow payment dates are determined from other inputs.

Data Types: `char` | `double`

Face or par value, specified as the comma-separated pair consisting of `'InstrumentFace'` and a scalar numeric.

Data Types: `double`

Note

When using `Instrument` name-value pairs, you can specify simple interest 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: `InstrumentBasis` is `0` (act/act) and `InstrumentPeriod` is `2`.

## Output Arguments

collapse all

Nelson-Siegel curve model, returned as a structure. 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`].

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

## Version History

Introduced in R2008b