capbycir

Price cap instrument from Cox-Ingersoll-Ross interest-rate tree

Syntax

``````[Price,PriceTree] = capbycir(CIRTree,Strike,Settle,Maturity)``````
``````[Price,PriceTree] = capbycir(___,Name,Value)``````

Description

example

``````[Price,PriceTree] = capbycir(CIRTree,Strike,Settle,Maturity)``` computes the price of a cap instrument from a Cox-Ingersoll-Ross (CIR) interest-rate tree. `capbycir` computes prices of vanilla caps and amortizing caps using a CIR++ model with the Nawalka-Beliaeva (NB) approach.```

example

``````[Price,PriceTree] = capbycir(___,Name,Value)``` adds additional name-value pair arguments.```

Examples

collapse all

Define the `Strike` for a cap.

`Strike = 0.03;`

Create a `RateSpec` using the `intenvset` function.

```Rates = [0.035; 0.042147; 0.047345; 0.052707]; Dates = [datetime(2017,1,1) ; datetime(2018,1,1) ; datetime(2019,1,1) ; datetime(2020,1,1) ; datetime(2021,1,1)]; ValuationDate = 'Jan-1-2017'; EndDates = Dates(2:end)'; Compounding = 1; RateSpec = intenvset('ValuationDate', ValuationDate, 'StartDates', ValuationDate, 'EndDates',EndDates,'Rates', Rates, 'Compounding', Compounding); ```

Create a `CIR` tree.

```NumPeriods = length(EndDates); Alpha = 0.03; Theta = 0.02; Sigma = 0.1; Settle = datetime(2017,1,1); Maturity = datetime(2021,1,1); CIRTimeSpec = cirtimespec(ValuationDate, Maturity, NumPeriods); CIRVolSpec = cirvolspec(Sigma, Alpha, Theta); CIRT = cirtree(CIRVolSpec, RateSpec, CIRTimeSpec)```
```CIRT = struct with fields: FinObj: 'CIRFwdTree' VolSpec: [1x1 struct] TimeSpec: [1x1 struct] RateSpec: [1x1 struct] tObs: [0 1 2 3] dObs: [736696 737061 737426 737791] FwdTree: {1x4 cell} Connect: {[3x1 double] [3x3 double] [3x5 double]} Probs: {[3x1 double] [3x3 double] [3x5 double]} ```

Price the 3% cap.

`[Price,PriceTree] = capbycir(CIRT,Strike,Settle,Maturity) `
```Price = 7.9081 ```
```PriceTree = struct with fields: FinObj: 'CIRPriceTree' tObs: [0 1 2 3 4] PTree: {1x5 cell} Connect: {[3x1 double] [3x3 double] [3x5 double]} Probs: {[3x1 double] [3x3 double] [3x5 double]} ```

Input Arguments

collapse all

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

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 CIR tree. The cap argument `Settle` is ignored.

To support existing code, `capbycir` 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, `capbycir` also accepts serial date numbers as inputs, but they are not recommended.

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: ```[Price,PriceTree] = capbycir(CIRTree,CouponRate,Settle,Maturity,'Basis',3)```

Reset frequency payment per year, specified as the comma-separated pair consisting of `'CapReset'` and a `NINST`-by-`1` vector.

Data Types: `double`

Day-count basis representing the basis used when annualizing the input forward rate, specified as the comma-separated pair consisting of `'Basis'` and 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`

Notional principal amount, specified as the comma-separated pair consisting of `'Principal'` and a `NINST`-by-`1` of notional principal amounts or a `NINST`-by-`1` cell array.

For the `NINST`-by-`1` cell array, 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`

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.PTree` contains cap prices.

• `PriceTree.tObs` contains the observation times.

• `PriceTree.Connect` contains the connectivity vectors. Each element in the cell array describes how nodes in that level connect to the next. For a given tree level, there are `NumNodes` elements in the vector, and they contain the index of the node at the next level that the middle branch connects to. Subtracting 1 from that value indicates where the up-branch connects to, and adding 1 indicated where the down branch connects to.

• `PriceTree.Probs` contains the probability arrays. Each element of the cell array contains the up, middle, and down transition probabilities for each node of the level.

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)$

References

[1] Cox, J., Ingersoll, J.,and S. Ross. "A Theory of the Term Structure of Interest Rates." Econometrica. Vol. 53, 1985.

[2] Brigo, D. and F. Mercurio. Interest Rate Models - Theory and Practice. Springer Finance, 2006.

[3] Hirsa, A. Computational Methods in Finance. CRC Press, 2012.

[4] Nawalka, S., Soto, G., and N. Beliaeva. Dynamic Term Structure Modeling. Wiley, 2007.

[5] Nelson, D. and K. Ramaswamy. "Simple Binomial Processes as Diffusion Approximations in Financial Models." The Review of Financial Studies. Vol 3. 1990, pp. 393–430.

Version History

Introduced in R2018a

expand all