Documentation

Calling Sequence

The calling syntax for hjmtree is HJMTree = hjmtree(VolSpec, RateSpec, TimeSpec).

Similarly, the calling syntax for bdttree is BDTTree = bdttree(VolSpec, RateSpec, TimeSpec).

Each of these functions requires VolSpec, RateSpec, and TimeSpec input arguments:

Creating an HJM Volatility Model

The function hjmvolspec generates the structure VolSpec, which specifies the volatility process $$\sigma \left(t,T\right)$$ used in the creation of the forward-rate trees. In this context capital T represents the starting time of the forward rate, and t represents the observation time. The volatility process can be constructed from a combination of factors specified sequentially in the call to function that creates it. Each factor specification starts with a character vector specifying the name of the factor, followed by the pertinent parameters.

HJM Volatility Specification Example.  Consider an example that uses a single factor, specifically, a constant-sigma factor. The constant factor specification requires only one parameter, the value of $$\sigma$$. In this case, the value corresponds to 0.10.

HJMVolSpec = hjmvolspec('Constant', 0.10)

HJMVolSpec = 

      FinObj: 'HJMVolSpec'
FactorModels: {'Constant'}
  FactorArgs: {{1x1 cell}}
  SigmaShift: 0
  NumFactors: 1
   NumBranch: 2
     PBranch: [0.5000 0.5000]
 Fact2Branch: [-1 1]

The NumFactors field of the VolSpec structure, VolSpec.NumFactors = 1, reveals that the number of factors used to generate VolSpec was one. The FactorModels field indicates that it is a Constant factor, and the NumBranches field indicates the number of branches. As a consequence, each node of the resulting tree has two branches, one going up, and the other going down.

Consider now a two-factor volatility process made from a proportional factor and an exponential factor.

% Exponential factor
Sigma_0 = 0.1;
Lambda = 1;
% Proportional factor
CurveProp = [0.11765; 0.08825; 0.06865];
CurveTerm = [   1   ;    2   ;    3   ];
% Build VolSpec
HJMVolSpec = hjmvolspec('Proportional', CurveProp, CurveTerm,...
1e6,'Exponential', Sigma_0, Lambda)

HJMVolSpec = 

      FinObj: 'HJMVolSpec'
FactorModels: {'Proportional'  'Exponential'}
  FactorArgs: {{1x3 cell}  {1x2 cell}}
  SigmaShift: 0
  NumFactors: 2
   NumBranch: 3
     PBranch: [0.2500 0.2500 0.5000]
 Fact2Branch: [2x3 double]

The output shows that the volatility specification was generated using two factors. The tree has three branches per node. Each branch has probabilities of 0.25, 0.25, and 0.5, going from top to bottom.

Creating a BDT Volatility Model

The function bdtvolspec generates the structure VolSpec, which specifies the volatility process. The function requires three input arguments:

An optional fourth argument InterpMethod, specifying the interpolation method, can be included.

The syntax used for calling bdtvolspec is:

BDTVolSpec = bdtvolspec(ValuationDate, VolDates, VolCurve,... InterpMethod)

where:

BDT Volatility Specification Example.  Consider the following example:

ValuationDate = datenum('01-01-2000');
EndDates = datenum(['01-01-2001'; '01-01-2002'; '01-01-2003'; 
'01-01-2004'; '01-01-2005']);
Volatility = [.2; .19; .18; .17; .16];

Use bdtvolspec to create a volatility specification. Because no interpolation method is explicitly specified, the function uses the linear default.

BDTVolSpec = bdtvolspec(ValuationDate, EndDates, Volatility)

BDTVolSpec = 
             FinObj: 'BDTVolSpec'
      ValuationDate: 730486
           VolDates: [5x1 double]
           VolCurve: [5x1 double]
    VolInterpMethod: 'linear'

Rate Specification Creation Example

Consider the following example:

Compounding = 1;
Rates = [0.02; 0.02; 0.02; 0.02];
StartDates = ['01-Jan-2000';   
              '01-Jan-2001';  
              '01-Jan-2002';  
              '01-Jan-2003'];
EndDates =   ['01-Jan-2001'; 
              '01-Jan-2002';  
              '01-Jan-2003'; 
              '01-Jan-2004'];
ValuationDate = '01-Jan-2000';

RateSpec = intenvset('Compounding',1,'Rates', Rates,... 
'StartDates', StartDates, 'EndDates', EndDates,... 
'ValuationDate', ValuationDate)

RateSpec = 

        FinObj: 'RateSpec'
   Compounding: 1
          Disc: [4x1 double]
         Rates: [4x1 double]
      EndTimes: [4x1 double]
    StartTimes: [4x1 double]
      EndDates: [4x1 double]
    StartDates: [4x1 double]
 ValuationDate: 730486
         Basis: 0
  EndMonthRule: 1

Use the function datedisp to examine the dates defined in the variable RateSpec. For example:

datedisp(RateSpec.ValuationDate)
01-Jan-2000

Creating a Time Specification

Calling the time specification creation functions with the same data used to create the interest-rate term structure, RateSpec builds the structure that specifies the time layout for the tree.

HJM Time Specification Example.  Consider the following example:

Maturity = EndDates;
HJMTimeSpec = hjmtimespec(ValuationDate, Maturity, Compounding)

HJMTimeSpec = 

       FinObj: 'HJMTimeSpec'
ValuationDate: 730486
     Maturity: [4x1 double]
  Compounding: 1
        Basis: 0
 EndMonthRule: 1

Maturities specified when building TimeSpec need not coincide with the EndDates of the rate intervals in RateSpec. Since TimeSpec defines the time-date mapping of the tree, the rates in RateSpec are interpolated to obtain the initial rates with maturities equal to those in TimeSpec.

Creating a BDT Time Specification.  Consider the following example:

Maturity = EndDates;
BDTTimeSpec = bdttimespec(ValuationDate, Maturity, Compounding)

BDTTimeSpec = 

           FinObj: 'BDTTimeSpec'
    ValuationDate: 730486
         Maturity: [4x1 double]
      Compounding: 1
            Basis: 0
     EndMonthRule: 1

Creating an HJM Tree

% Reset the volatility factor to the Constant case
HJMVolSpec = hjmvolspec('Constant', 0.10);

HJMTree = hjmtree(HJMVolSpec, RateSpec, HJMTimeSpec)

HJMTree = 

  FinObj: 'HJMFwdTree'
 VolSpec: [1x1 struct]
TimeSpec: [1x1 struct]
RateSpec: [1x1 struct]
    tObs: [0 1 2 3]
    TFwd: {[4x1 double] [3x1 double] [2x1 double] [3]}
  CFlowT: {[4x1 double] [3x1 double] [2x1 double] [4]}
 FwdTree:{[4x1 double][3x1x2 double][2x2x2 double][1x4x2 double]}

Creating a BDT Tree

Now use the previously computed values for VolSpec, RateSpec, and TimeSpec as input to the function bdttree to create a BDT tree.

BDTTree = bdttree(BDTVolSpec, RateSpec, BDTTimeSpec)

BDTTree = 

  FinObj: 'BDTFwdTree'
 VolSpec: [1x1 struct]
TimeSpec: [1x1 struct]
RateSpec: [1x1 struct]
    tObs: [0 1.00 2.00 3.00]
    TFwd: {[4x1 double]  [3x1 double]  [2x1 double]  [3.00]}
  CFlowT: {[4x1 double]  [3x1 double]  [2x1 double]  [4.00]}
 FwdTree: {[1.02] [1.02 1.02] [1.01 1.02 1.03] [1.01 1.02 1.02 1.03]}

HJM Tree Structure

You can now examine in some detail the contents of the HJMTree structure contained in this file.

HJMTree

HJMTree = 

  FinObj: 'HJMFwdTree'
 VolSpec: [1x1 struct]
TimeSpec: [1x1 struct]
RateSpec: [1x1 struct]
    tObs: [0 1 2 3]
    TFwd: {[4x1 double]  [3x1 double]  [2x1 double]  [3]}
  CFlowT: {[4x1 double]  [3x1 double]  [2x1 double] [4]}
 FwdTree:{[4x1 double][3x1x2 double][2x2x2 double][1x4x2 double]}

FwdTree contains the actual forward-rate tree. MATLAB represents it as a cell array with each cell array element containing a tree level.

The other fields contain other information relevant to interpreting the values in FwdTree. The most important are VolSpec, TimeSpec, and RateSpec, which contain the volatility, time structure, and rate structure information respectively.

First Node.  Observe the forward rates in FwdTree. The first node represents the valuation date, tObs = 0.

HJMTree.FwdTree{1}

ans =

   1.0356
   1.0468
   1.0523
   1.0563

Look closely at the RateSpec structure used in generating this tree to see where these values originate. Arrange the values in a single array.

[HJMTree.RateSpec.StartTimes HJMTree.RateSpec.EndTimes... 
HJMTree.RateSpec.Rates]

ans =

         0    1.0000    0.0356
    1.0000    2.0000    0.0468
    2.0000    3.0000    0.0523
    3.0000    4.0000    0.0563

If you find the corresponding inverse discounts of the interest rates in the third column, you have the values at the first node of the tree. You can turn interest rates into inverse discounts using the function rate2disc.

Disc = rate2disc(HJMTree.TimeSpec.Compounding,... 
HJMTree.RateSpec.Rates, HJMTree.RateSpec.EndTimes,... 
HJMTree.RateSpec.StartTimes);
FRates = 1./Disc

FRates =
    1.0356
    1.0468
    1.0523
    1.0563

Second Node.  The second node represents the first-rate observation time, tObs = 1. This node displays two states: one representing the branch going up and the other representing the branch going down.

Note that HJMTree.VolSpec.NumBranch = 2.

HJMTree.VolSpec

ans = 

          FinObj: 'HJMVolSpec'
    FactorModels: {'Constant'}
      FactorArgs: {{1x1 cell}}
      SigmaShift: 0
      NumFactors: 1
       NumBranch: 2
         PBranch: [0.5000 0.5000]
     Fact2Branch: [-1 1]

Examine the rates of the node corresponding to the up branch.

HJMTree.FwdTree{2}(:,:,1)

ans =

    1.0364
    1.0420
    1.0461

Now examine the corresponding down branch.

HJMTree.FwdTree{2}(:,:,2)

ans =

    1.0574
    1.0631
    1.0672

Third Node.  The third node represents the second observation time, tObs = 2. This node contains a total of four states, two representing the branches going up and the other two representing the branches going down. Examine the rates of the node corresponding to the up states.

HJMTree.FwdTree{3}(:,:,1)

ans =

    1.0317    1.0526
    1.0358    1.0568

Next examine the corresponding down states.

HJMTree.FwdTree{3}(:,:,2)

ans =

    1.0526    1.0738
    1.0568    1.0781

Isolating a Specific Node.  Starting at the third level, indexing within the tree cell array becomes complex, and isolating a specific node can be difficult. The function bushpath isolates a specific node by specifying the path to the node as a vector of branches taken to reach that node. As an example, consider the node reached by starting from the root node, taking the branch up, then the branch down, and then another branch down. Given that the tree has only two branches per node, branches going up correspond to a 1, and branches going down correspond to a 2. The path up-down-down becomes the vector [1 2 2].

FRates = bushpath(HJMTree.FwdTree, [1 2 2])

FRates =

    1.0356
    1.0364
    1.0526
    1.0674

bushpath returns the spot rates for all the nodes tapped by the path specified in the input argument, the first one corresponding to the root node, and the last one corresponding to the target node.

Isolating the same node using direct indexing obtains

HJMTree.FwdTree{4}(:, 3, 2)

ans =

    1.0674

As expected, this single value corresponds to the last element of the rates returned by bushpath.

You can use these techniques with any type of tree generated with Financial Instruments Toolbox, such as forward-rate trees or price trees.

BDT Tree Structure

You can now examine in some detail the contents of the BDTTree structure.

BDTTree 

BDTTree = 

      FinObj: 'BDTFwdTree'
     VolSpec: [1x1 struct]
    TimeSpec: [1x1 struct]
    RateSpec: [1x1 struct]
        tObs: [0 1.00 2.00 3.00]
        TFwd: {[4x1 double]  [3x1 double]  [2x1 double]  [3.00]}
      CFlowT: {[4x1 double]  [3x1 double]  [2x1 double]  [4.00]}
     FwdTree: {[1.10]  [1.10 1.14]  [1.10 1.14 1.19]  [1.09 1.12 1.16 1.22]}

FwdTree contains the actual rate tree. MATLAB represents it as a cell array with each cell array element containing a tree level.

The other fields contain other information relevant to interpreting the values in FwdTree. The most important are VolSpec, TimeSpec, and RateSpec, which contain the volatility, time structure, and rate structure information respectively.

Look at the RateSpec structure used in generating this tree to see where these values originate. Arrange the values in a single array.

[BDTTree.RateSpec.StartTimes BDTTree.RateSpec.EndTimes... 
BDTTree.RateSpec.Rates]

ans =

         0    1.0000    0.1000
         0    2.0000    0.1100
         0    3.0000    0.1200
         0    4.0000    0.1250

Look at the rates in FwdTree. The first node represents the valuation date, tObs = 0. The second node represents tObs = 1. Examine the rates at the second, third, and fourth nodes.

BDTTree.FwdTree{2}  

ans =

      1.0979    1.1432

The second node represents the first observation time, tObs = 1. This node contains a total of two states, one representing the branch going up (1.0979) and the other representing the branch going down (1.1432).

BDTTree.FwdTree{3}

ans =

    1.0976    1.1377    1.1942

The third node represents the second observation time, tObs = 2. This node contains a total of three states, one representing the branch going up (1.0976), one representing the branch in the middle (1.1377) and the other representing the branch going down (1.1942).

BDTTree.FwdTree{4}

ans =

    1.0872    1.1183    1.1606    1.2179

The fourth node represents the third observation time, tObs = 3. This node contains a total of four states, one representing the branch going up (1.0872), two representing the branches in the middle (1.1183 and 1.1606), and the other representing the branch going down (1.2179).

Isolating a Specific Node.  The function treepath isolates a specific node by specifying the path to the node as a vector of branches taken to reach that node. As an example, consider the node reached by starting from the root node, taking the branch up, then the branch down, and finally another branch down. Given that the tree has only two branches per node, branches going up correspond to a 1, and branches going down correspond to a 2. The path up-down-down becomes the vector [1 2 2].

FRates = treepath(BDTTree.FwdTree, [1 2 2]) 

FRates =

    1.1000
    1.0979
    1.1377
    1.1606

treepath returns the short rates for all the nodes tapped by the path specified in the input argument, the first one corresponding to the root node, and the last one corresponding to the target node.

HW and BK Tree Structures

The HW and BK tree structures are similar to the BDT tree structure. You can see this if you examine the sample HW tree contained in the file deriv.mat.

load deriv.mat;
HWTree

HWTree = 

      FinObj: 'HWFwdTree'
     VolSpec: [1x1 struct]
    TimeSpec: [1x1 struct]
    RateSpec: [1x1 struct]
        tObs: [0 1.00 2.00 3.00]
        dObs: [731947.00 732313.00 732678.00 733043.00]
      CFlowT: {[4x1 double]  [3x1 double]  [2x1 double]  [4.00]}
       Probs: {[3x1 double]  [3x3 double]  [3x5 double]}
     Connect: {[2.00]  [2.00 3.00 4.00]  [2.00 2.00 3.00 4.00 4.00]}
     FwdTree: {[1.03]  [1.05 1.04 1.02]  [1.08 1.07 1.05 1.03 1.01]  [1.09 1.08 1.06 1.04 1.02]

All fields of this structure are similar to their BDT counterparts. There are two additional fields not present in BDT: Probs and Connect. The Probs field represents the occurrence probabilities at each branch of each node in the tree. The Connect field describes the connectivity of the nodes of a given tree level to nodes to the next tree level.

Probs Field.  While BDT and one-factor HJM models have equal probabilities for each branch at a node, HW and BK do not. For HW and BK trees, the Probs field indicates the likelihood that a particular branch will be taken in moving from one node to another node on the next level.

The Probs field consists of a cell array with one cell per tree level. Each cell is a 3-by-NUMNODES array with the top row representing the probability of an up movement, the middle row representing the probability of a middle movement, and the last row the probability of a down movement.

As an illustration, consider the first two elements of the Probs field of the structure, corresponding to the first (root) and second levels of the tree.

HWTree.Probs{1}

0.16666666666667
0.66666666666667
0.16666666666667

HWTree.Probs{2}

0.12361333418768   0.16666666666667   0.21877591615172
0.65761074966060   0.66666666666667   0.65761074966060
0.21877591615172   0.16666666666667   0.12361333418768

Reading from top to bottom, the values in HWTree.Probs{1} correspond to the up, middle, and down probabilities at the root node.

HWTree.Probs{2} is a 3-by-3 matrix of values. The first column represents the top node, the second column represents the middle node, and the last column represents the bottom node. As with the root node, the first, second, and third rows hold the values for up, middle, and down branching off each node.

As expected, the sum of all the probabilities at any node equals 1.

sum(HWTree.Probs{2})

1.0000    1.0000    1.0000

Connect Field.  The other field that distinguishes HW and BK tree structures from the BDT tree structure is Connect. This field describes how each node in a given level connects to the nodes of the next level. The need for this field arises from the possibility of nonstandard branching in a tree.

The Connect field of the HW tree structure consists of a cell array with one cell per tree level.

HWTree.Connect

ans = 

    [2]    [1x3 double]    [1x5 double]

Each cell contains a 1-by-NUMNODES vector. Each value in the vector relates to a node in the corresponding tree level and represents the index of the node in the next tree level that the middle branch of the node connects to.

If you subtract 1 from the values contained in Connect, you reveal the index of the nodes in the next level that the up branch connects to. If you add 1 to the values, you reveal the index of the corresponding down branch.

As an illustration, consider HWTree.Connect{1}:

HWTree.Connect{1}

ans =

     2

This indicates that the middle branch of the root node connects to the second (from the top) node of the next level, as expected. If you subtract 1 from this value, you obtain 1, which tells you that the up branch goes to the top node. If you add 1, you obtain 3, which points to the last node of the second level of the tree.

Now consider level 3 in this example:

HWTree.Connect{3}

2     2     3     4     4

On this level, there is nonstandard branching. This can be easily recognized because the middle branch of two nodes is connected to the same node on the next level.

To visualize this, consider the following illustration of the tree.

Here it becomes apparent that there is nonstandard branching at the third level of the tree, on the top and bottom nodes. The first and second nodes connect to the same trio of nodes on the next level. Similar branching occurs at the bottom and next-to-bottom nodes of the tree.