fitFunction

Custom fit interest-rate curve object to bond market data

Syntax

```CurveObj = IRFunctionCurve.fitFunction(Type, Settle,FunctionHandle, Instruments, IRFitOptionsObj)
CurveObj = IRFunctionCurve.fitFunction(Type, Settle,FunctionHandle, Instruments, IRFitOptionsObj, 'Parameter1',Value1, 'Parameter2', Value2, ...)
```

Arguments

 `Type` Type of interest-rate curve for a bond: `zero`, `forward`, or `discount`. `Settle` Scalar for the `Settle` date of the curve. `FunctionHandle` Function handle that defines the interest-rate curve. The function handle takes two numeric vectors (time-to-maturity and a vector of function coefficients) and returns one numeric output (interest rate or discount factor). For more information on defining a function handle, see the MATLAB® Programming Fundamentals documentation. `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. `IRFitOptionsObj` Object constructed from `IRFitOptions`. `Compounding` (Optional) Scalar that sets the compounding frequency per year for the `IRFunctionCurve` object:`−1` = Continuous compounding`1` = Annual compounding`2` = Semiannual compounding (default)`3` = Compounding three times per year`4` = Quarterly compounding`6` = Bimonthly compounding`12` = Monthly compounding `Basis` (Optional) Day-count basis of the bond. 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/252For more information, see basis.

Instrument Parameters

For each bond `Instrument`, you can specify the following additional instrument parameters as parameter/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. `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` parameter/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: `Basis` is `0` (act/act) and `Period` is `2`.

Description

```CurveObj = IRFunctionCurve.fitFunction(Type, Settle, FunctionHandle, Instruments, IRFitOptionsObj, 'Parameter1', Value1, 'Parameter2', Value2, ...)``` fits a bond to a custom fitting function. You must enter the optional arguments for `Basis` and `Compounding` as parameter/value pairs.

Examples

```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'); OptOptions = optimoptions('lsqnonlin','display','iter'); functionHandle = @(t,theta) polyval(theta,t); 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.```