cfbybk

Price cash flows from Black-Karasinski interest-rate tree

Syntax

[Price,PriceTree] = cfbybk(BKTree,CFlowAmounts,CFlowDates,Settle)

[Price,PriceTree] = cfbybk(___,Basis,Options)

Description

[Price,PriceTree] = cfbybk(BKTree,CFlowAmounts,CFlowDates,Settle) prices cash flows from a Black-Karasinski interest-rate tree.

[Price,PriceTree] = cfbybk(___,Basis,Options) adds optional arguments.

Examples

Price a Portfolio Containing Two Cash Flow Instruments

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

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

load deriv.mat; 

The valuation date (settle date) specified in BKTree is January 1, 2004 (date number 731947).

BKTree.RateSpec.ValuationDate

ans =

      731947

Provide values for the other required arguments.

CFlowAmounts =[5 NaN 5.5 105; 5 0 6 105];
CFlowDates = [732678, NaN, 733408,733774; 
              732678, 733034, 733408, 734774];

Use this information to compute the prices of the two cash flow instruments.

[Price, PriceTree] = cfbybk(BKTree, CFlowAmounts, CFlowDates,... 
BKTree.RateSpec.ValuationDate)

Warning: Not all cash flows are aligned with the tree. Result will be approximated. 
> In cfbytrintree (line 88)
  In cfbybk (line 75) 

Price =

   93.3600
   81.6218


PriceTree = 

  struct with fields:

     FinObj: 'BKPriceTree'
      PTree: {[2×1 double]  [2×3 double]  [2×5 double]  [2×5 double]  [2×5 double]}
       tObs: [0 1 2 3 4]
    Connect: {[2]  [2 3 4]  [2 2 3 4 4]}
      Probs: {[3×1 double]  [3×3 double]  [3×5 double]}

You can visualize the prices of the two cash flow instruments with the treeviewer function.

Input Arguments

BKTree — Interest-rate tree structure

structure

Interest-rate tree structure, specified by using bktree.

Data Types: struct

CFlowAmounts — Cash flow amounts

matrix

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

CFlowDates — Cash flow dates

matrix

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

Data Types: double

Settle — Settlement date

serial date number | date character vector

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

Data Types: double | char

Basis — Day-count basis of instrument

0 (actual/actual) (default) | integer from 0 to 13

(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

Options — Derivatives pricing options structure

structure

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

Data Types: struct

Output Arguments

Price — Expected prices at time 0

vector

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

PriceTree — Tree structure of instrument prices

structure

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.