## Creating an `IRFunctionCurve` Object

To create an `IRFunctionCurve` object, see the following options:

### Fitting `IRFunctionCurve` Object Using a Function Handle

You can use `IRFunctionCurve` with a MATLAB® function handle to define an interest-rate curve. For more information on defining a function handle, see the MATLAB Programming Fundamentals documentation.

#### Example

This example uses a `FunctionHandle` argument with a value `@(t) t.^2` to create an interest-rate curve.

```rr = IRFunctionCurve('Zero',today,@(t) t.^2) ```
```rr = Properties: FunctionHandle: @(t)t.^2 Type: 'Zero' Settle: 733600 Compounding: 2 Basis: 0```

### Fitting `IRFunctionCurve` Object Using Nelson-Siegel Method

Use the function, `fitNelsonSiegel`, for the Nelson-Siegel model that fits the empirical form of the yield curve with a prespecified functional form of the spot rates which is a function of the time to maturity of the bonds.

The Nelson-Siegel model represents a dynamic three-factor model: level, slope, and curvature. However, the Nelson-Siegel factors are unobserved, or latent, which allows for measurement error, and the associated loadings have economic restrictions (forward rates are always positive, and the discount factor approaches zero as maturity increases). For more information, see “Zero-coupon yield curves: technical documentation,” BIS Papers, Bank for International Settlements, Number 25, October 2005.

#### Example

This example uses `IRFunctionCurve` to model the default-free term structure of interest rates in the United Kingdom.

`load ukdata20080430`

Convert repo rates to be equivalent zero-coupon bonds.

```RepoCouponRate = repmat(0,size(RepoRates)); RepoPrice = bndprice(RepoRates, RepoCouponRate, RepoSettle, RepoMaturity);```

Aggregate the data.

```Settle = [RepoSettle;BondSettle]; Maturity = [RepoMaturity;BondMaturity]; CleanPrice = [RepoPrice;BondCleanPrice]; CouponRate = [RepoCouponRate;BondCouponRate]; Instruments = [Settle Maturity CleanPrice CouponRate]; InstrumentPeriod = [repmat(0,6,1);repmat(2,31,1)]; CurveSettle = datenum('30-Apr-2008');```

The `IRFunctionCurve` object provides the capability to fit a Nelson-Siegel curve to observed market data with the `fitNelsonSiegel` function. The fitting is done by calling the function `lsqnonlin`. The `fitNelsonSiegel` function has required inputs of `Type`, `Settle`, and a matrix of instrument data.

```NSModel = IRFunctionCurve.fitNelsonSiegel('Zero',CurveSettle,... Instruments,'Compounding',-1,'InstrumentPeriod',InstrumentPeriod); ```

Plot the Nelson-Siegel interest-rate curve for forward rates.

```PlottingDates = CurveSettle+20:30:CurveSettle+365*25; TimeToMaturity = yearfrac(CurveSettle,PlottingDates); NSForwardRates = getForwardRates(NSModel, PlottingDates); plot(TimeToMaturity,NSForwardRates) title('Nelson Siegel model of UK instantaneous nominal forward curve')``` ### Fitting `IRFunctionCurve` Object Using Svensson Method

Use the function, `fitSvensson`, for the Svensson model to improve the flexibility of the curves and the fit for a Nelson-Siegel model. In 1994, Svensson extended Nelson and Siegel’s function by adding a further term that allows for a second “hump.” The extra precision is achieved at the cost of adding two more parameters, β3 and τ2, which have to be estimated.

#### Example

In this example of using the `fitSvensson` function, an `IRFitOptions` structure, previously defined using `IRFitOptions`, is used. Thus, you must specify `FitType`, `InitialGuess`, `UpperBound`, `LowerBound`, and the `OptOptions` optimization parameters for `lsqnonlin`.

`load ukdata20080430`

Convert repo rates to be equivalent zero coupon bonds.

```RepoCouponRate = repmat(0,size(RepoRates)); RepoPrice = bndprice(RepoRates, RepoCouponRate, RepoSettle, RepoMaturity);```

Aggregate the data.

```Settle = [RepoSettle;BondSettle]; Maturity = [RepoMaturity;BondMaturity]; CleanPrice = [RepoPrice;BondCleanPrice]; CouponRate = [RepoCouponRate;BondCouponRate]; Instruments = [Settle Maturity CleanPrice CouponRate]; InstrumentPeriod = [repmat(0,6,1);repmat(2,31,1)]; CurveSettle = datenum('30-Apr-2008'); ```

Define `OptOptions` for `IRFitOptions`.

```OptOptions = optimoptions('lsqnonlin','MaxFunEvals',1000); fIRFitOptions = IRFitOptions([5.82 -2.55 -.87 0.45 3.9 0.44],... 'FitType','durationweightedprice','OptOptions',OptOptions,... 'LowerBound',[0 -Inf -Inf -Inf 0 0],'UpperBound',[Inf Inf Inf Inf Inf Inf]);```

Fit the interest-rate curve using a Svensson model.

```SvenssonModel = IRFunctionCurve.fitSvensson('Zero',CurveSettle,... Instruments,'IRFitOptions', fIRFitOptions, 'Compounding',-1,... 'InstrumentPeriod',InstrumentPeriod)```
```Local minimum possible. lsqnonlin stopped because the final change in the sum of squares relative to its initial value is less than the default value of the function tolerance. SvenssonModel = Type: Zero Settle: 733528 (30-Apr-2008) Compounding: -1 Basis: 0 (actual/actual)```

The status message, output from `lsqnonlin`, indicates that the optimization to find parameters for the Svensson equation terminated successfully.

Plot the Svensson interest-rate curve for forward rates.

```PlottingDates = CurveSettle+20:30:CurveSettle+365*25; TimeToMaturity = yearfrac(CurveSettle,PlottingDates); SvenssonForwardRates = getForwardRates(SvenssonModel, PlottingDates); plot(TimeToMaturity,SvenssonForwardRates) title('Svensson model of UK instantaneous nominal forward curve')``` ### Fitting `IRFunctionCurve` Object Using Smoothing Spline Method

Use the function, `fitSmoothingSpline`, to model the term structure with a spline, specifically, the term structure represents the forward curve with a cubic spline.

Note

You must have a license for Curve Fitting Toolbox™ software to use the `fitSmoothingSpline` function.

#### Example

The `IRFunctionCurve` object is used to fit a smoothing spline representation of the forward curve with a penalty function. Required inputs for `fitSmoothingSpline` are `Type`, `Settle`, the matrix of `Instruments`, and `Lambdafun`, a function handle containing the penalty function

`load ukdata20080430`

Convert repo rates to be equivalent zero coupon bonds.

```RepoCouponRate = repmat(0,size(RepoRates)); RepoPrice = bndprice(RepoRates, RepoCouponRate, RepoSettle, RepoMaturity);```

Aggregate the data.

```Settle = [RepoSettle;BondSettle]; Maturity = [RepoMaturity;BondMaturity]; CleanPrice = [RepoPrice;BondCleanPrice]; CouponRate = [RepoCouponRate;BondCouponRate]; Instruments = [Settle Maturity CleanPrice CouponRate]; InstrumentPeriod = [repmat(0,6,1);repmat(2,31,1)]; CurveSettle = datenum('30-Apr-2008'); ```

Choose parameters for `Lambdafun`.

```L = 9.2; S = -1; mu = 1;```

Define the `Lambdafun` penalty function.

```lambdafun = @(t) exp(L - (L-S)*exp(-t/mu)); t = 0:.1:25; y = lambdafun(t); figure semilogy(t,y); title('Penalty Function for VRP Approach') ylabel('Penalty') xlabel('Time') ``` Use the `fitSmoothingSpline` function to fit the interest-rate curve and model the `Lambdafun` penalty function.

```VRPModel = IRFunctionCurve.fitSmoothingSpline('Forward',CurveSettle,... Instruments,lambdafun,'Compounding',-1, 'InstrumentPeriod',InstrumentPeriod);```

Plot the smoothing spline interest-rate curve for forward rates.

```PlottingDates = CurveSettle+20:30:CurveSettle+365*25; TimeToMaturity = yearfrac(CurveSettle,PlottingDates); VRPForwardRates = getForwardRates(VRPModel, PlottingDates); plot(TimeToMaturity,VRPForwardRates) title('Smoothing Spline model of UK instantaneous nominal forward curve')``` ### Using `fitFunction` to Create Custom Fitting Function

When using an `IRFunctionCurve` object, you can create a custom fitting function with the `fitFunction` function. To use `fitFunction`, you must define a `FunctionHandle`. In addition, you must also use `IRFitOptions` to define an `IRFitOptions` object to support an `InitialGuess` for the parameters of the curve function.

#### Example

The following example demonstrates the use of `fitFunction` with a `FunctionHandle` and an `IRFitOptions` object.

```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]; CurveSettle = datenum('30-Apr-2008'); ```

Define the `FunctionHandle`.

`functionHandle = @(t,theta) polyval(theta,t);`

Define the `OptOptions` for `IRFitOptions`.

```OptOptions = optimoptions('lsqnonlin','display','iter'); ```

Define `fitFunction`.

```CustomModel = IRFunctionCurve.fitFunction('Zero', CurveSettle, ... functionHandle,Instruments, IRFitOptions([.05 .05 .05],'FitType','price',... 'OptOptions',OptOptions));```
``` Norm of First-order Iteration Func-count f(x) step optimality CG-iterations 0 4 38036.7 4.92e+04 1 8 38036.7 10 4.92e+04 0 2 12 38036.7 2.5 4.92e+04 0 3 16 38036.7 0.625 4.92e+04 0 4 20 38036.7 0.15625 4.92e+04 0 5 24 30741.5 0.0390625 1.72e+05 0 6 28 30741.5 0.078125 1.72e+05 0 7 32 30741.5 0.0195312 1.72e+05 0 8 36 28713.6 0.00488281 2.33e+05 0 9 40 20323.3 0.00976562 9.47e+05 0 10 44 20323.3 0.0195312 9.47e+05 0 11 48 20323.3 0.00488281 9.47e+05 0 12 52 20323.3 0.0012207 9.47e+05 0 13 56 19698.8 0.000305176 1.08e+06 0 14 60 17493 0.000610352 7e+06 0 15 64 17493 0.0012207 7e+06 0 16 68 17493 0.000305176 7e+06 0 17 72 15455.1 7.62939e-05 2.25e+07 0 18 76 15455.1 0.000177499 2.25e+07 0 19 80 13317.1 3.8147e-05 3.18e+07 0 20 84 12865.3 7.62939e-05 7.83e+07 0 21 88 11779.8 7.62939e-05 7.58e+06 0 22 92 11747.6 0.000152588 1.45e+05 0 23 96 11720.9 0.000305176 2.33e+05 0 24 100 11667.2 0.000610352 1.48e+05 0 25 104 11558.6 0.0012207 3.55e+05 0 26 108 11335.5 0.00244141 1.57e+05 0 27 112 10863.8 0.00488281 6.36e+05 0 28 116 9797.14 0.00976562 2.53e+05 0 29 120 6882.83 0.0195312 9.18e+05 0 30 124 6882.83 0.0373993 9.18e+05 0 31 128 3218.45 0.00934981 1.96e+06 0 32 132 612.703 0.0186996 3.01e+06 0 33 136 13.0998 0.0253882 3.05e+06 0 34 140 0.0762922 0.00154002 5.05e+04 0 35 144 0.0731652 3.61102e-06 29.9 0 36 148 0.0731652 6.32335e-08 0.063 0 Local minimum possible. lsqnonlin stopped because the final change in the sum of squares relative to its initial value is less than the default value of the function tolerance. ```

Plot the custom function that is defined using `fitFunction`.

```Yields = bndyield(CleanPrice,CouponRate,Settle(1),Maturity); scatter(Maturity,Yields); PlottingPoints = min(Maturity):30:max(Maturity); hold on; plot(PlottingPoints, getParYields(CustomModel, PlottingPoints),'r'); datetick legend('Market Yields','Fitted Yield Curve') title('Custom Function fit to Market Data') ``` 