capbyhjm

Price cap instrument from Heath-Jarrow-Morton interest-rate tree

Syntax

``````[Price,PriceTree] = capbyhjm(HJMTree,Strike,Settle,Maturity)``````
``````[Price,PriceTree] = capbyhjm(___,CapReset,Basis,Principal,Options)``````

Description

example

``````[Price,PriceTree] = capbyhjm(HJMTree,Strike,Settle,Maturity)``` computes the price of a cap instrument from a Heath-Jarrow-Morton interest-rate tree. `capbyhjm` computes prices of vanilla caps and amortizing caps.```

example

``````[Price,PriceTree] = capbyhjm(___,CapReset,Basis,Principal,Options)``` adds optional arguments.```

Examples

collapse all

Load the file `deriv.mat`, which provides `HJMTree`. The `HJMTree` structure contains the time and forward-rate information needed to price the cap instrument.

`load deriv.mat;`

Set the required values. Other arguments will use defaults.

```Strike = 0.03; Settle = datetime(2000,1,1); Maturity = datetime(2004,1,1);```

Use `capbyhjm` to compute the price of the cap instrument.

`Price = capbyhjm(HJMTree, Strike, Settle, Maturity)`
```Price = 6.2831 ```

Load `deriv.mat` to specify the `HJMTree` and then define the cap instrument.

```load deriv.mat; Settle = datetime(2000,1,1); Maturity = datetime(2004,1,1); Strike = 0.045; CapReset = 1; Principal ={{datetime(2001,1,1) 100;datetime(2002,1,1) 80;datetime(2003,1,1) 70;datetime(2004,1,1) 30}};```

Price the amortizing cap.

```Basis = 1; Price = capbyhjm(HJMTree, Strike, Settle, Maturity, CapReset, Basis, Principal)```
```Price = 1.4588 ```

Input Arguments

collapse all

Interest-rate tree structure, specified by using `hjmtree`.

Data Types: `struct`

Rate at which cap is exercised, specified as a `NINST`-by-`1` vector of decimal values.

Data Types: `double`

Settlement date for the cap, specified as a `NINST`-by-`1` vector using a datetime array, string array, or date character vectors. The `Settle` date for every cap is set to the `ValuationDate` of the HJM tree. The cap argument `Settle` is ignored.

To support existing code, `capbyhjm` also accepts serial date numbers as inputs, but they are not recommended.

Maturity date for the cap, specified as a `NINST`-by-`1` vector using a datetime array, string array, or date character vectors.

To support existing code, `capbyhjm` also accepts serial date numbers as inputs, but they are not recommended.

(Optional) Reset frequency payment per year, specified as a `NINST`-by-`1` vector.

Data Types: `double`

(Optional) Day-count basis representing the basis used when annualizing the input forward rate, specified as a `NINST`-by-`1` vector of integers.

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

(Optional) Notional principal amount, specified as a `NINST`-by-`1` of notional principal amounts, or a `NINST`-by-`1` cell array, where each element is a `NumDates`-by-`2` cell array where the first column is dates and the second column is associated principal amount. The date indicates the last day that the principal value is valid.

Use `Principal` to pass a schedule to compute the price for an amortizing cap.

Data Types: `double` | `cell`

(Optional) Derivatives pricing options structure, specified using `derivset`.

Data Types: `struct`

Output Arguments

collapse all

Expected price of the cap at time 0, returned as a `NINST`-by-`1` vector.

Tree structure with values of the cap at each node, returned as a MATLAB® structure of trees containing vectors of instrument prices and a vector of observation times for each node:

• `PriceTree.tObs` contains the observation times.

• `PriceTree.PBush` contains the clean prices.

collapse all

Cap

A cap is a contract that includes a guarantee that sets the maximum interest rate to be paid by the holder, based on an otherwise floating interest rate.

The payoff for a cap is:

$\mathrm{max}\left(CurrentRate-CapRate,0\right)$