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 a 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.