Main Content

cfbycir

Price cash flows from Cox-Ingersoll-Ross interest-rate tree

collapse all in page

Syntax

[Price,PriceTree] = cfbycir(CIRTree,CFlowAmounts,CFlowDates,Settle)
[Price,PriceTree] = cfbycir(___,Basis)

Description

[Price,PriceTree] = cfbycir(CIRTree,CFlowAmounts,CFlowDates,Settle) prices cash flows from a Cox-Ingersoll-Ross (CIR) interest-rate tree using a CIR++ model with the Nawalka-Beliaeva (NB) approach.

example

[Price,PriceTree] = cfbycir(___,Basis) adds an optional argument for Basis.

example

Examples

collapse all

Open Live Script

Price a portfolio containing two cash flow instruments paying interest annually over the four-year period from January 1, 2017 to June 1, 2020.

Load the file deriv.mat, which provides CIRTree. The CIRTree structure contains the time and interest-rate information required to price the instruments.

load deriv.mat;

The valuation date (settle date) specified in the CIRTree is January 1, 2017 (serial date number 736696).

CIRTree.RateSpec.ValuationDate 
ans = 
736696

Provide values for the other required arguments.

CFlowAmounts =[5 NaN 5.5 105; 5 0 6 105];
CFlowDates = [736847,NaN,737061,737212; 
              737426,737577,737791,737943];

Compute the prices of the two cash flow instruments using cfbycir.

[Price,PriceTree] = cfbycir(CIRTree, CFlowAmounts, CFlowDates,... 
CIRTree.RateSpec.ValuationDate)
Price = 2×1

  109.6845
   98.7246


PriceTree = struct with fields:
     FinObj: 'CIRPriceTree'
      PTree: {[2x1 double]  [2x3 double]  [2x5 double]  [2x7 double]  [2x7 double]}
       tObs: [0 1 2 3 4]
    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

Cash flow amounts, specified as a number of instruments (NINST) by maximum number of cash flows (MOSTCFS) matrix of cash flow amounts. Each row is a list of cash flow values for one instrument. If an instrument has fewer than MOSTCFS cash flows, the end of the row is padded with NaNs.

Data Types: double

Cash flow dates, specified as NINST-by-MOSTCFS vector using serial date numbers. Each entry contains the serial date number of the corresponding cash flow in CFlowAmounts.

Data Types: double

Settlement date, specified as a vector using serial date numbers or date character vectors. The Settle date for every cash flow is set to the ValuationDate of the CIR tree. The cash flow argument Settle is ignored.

Data Types: double | char

(Optional) Day-count basis of the instrument, specified as a 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

For more information, see Basis.

Data Types: double

Output Arguments

collapse all

Expected prices at time 0, returned as a NINST-by-1 vector.

Tree structure of instrument prices, returned as a MATLAB® structure of trees containing vectors of instrument prices and observation times for each node. Within PriceTree:

  • PriceTree.PTree contains the clean 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.

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

See Also

| | | | | | | | | | | | |

Topics