hwtree

Build Hull-White interest-rate tree

Syntax

HWTree = hwtree(VolSpec,RateSpec,TimeSpec)

HWTree = hwtree(___,Name,Value)

Description

HWTree = hwtree(VolSpec,RateSpec,TimeSpec) builds a Hull-White interest-rate tree.

HWTree = hwtree(___,Name,Value) adds optional name-value pair arguments.

Examples

Create an HWTree

Using the data provided, create a Hull-White volatility specification (VolSpec), rate specification (RateSpec), and tree time layout specification (TimeSpec). Then, use these specifications to create a Hull-White tree using hwtree.

Compounding = -1;
ValuationDate = '01-01-2004';
StartDate = ValuationDate;
VolDates = ['12-31-2004'; '12-31-2005'; '12-31-2006'; 
'12-31-2007'];
VolCurve = 0.01;
AlphaDates = '01-01-2008';
AlphaCurve = 0.1;
Rates = [0.0275; 0.0312; 0.0363; 0.0415];

HWVolSpec = hwvolspec(ValuationDate, VolDates, VolCurve,...  
AlphaDates, AlphaCurve);

RateSpec = intenvset('Compounding', Compounding,...
					 'ValuationDate', ValuationDate,...
					 'StartDates', ValuationDate,...
					 'EndDates', VolDates,...
					 'Rates', Rates);
 
HWTimeSpec = hwtimespec(ValuationDate, VolDates, Compounding);
HWTree = hwtree(HWVolSpec, RateSpec, HWTimeSpec)

HWTree = struct with fields:
      FinObj: 'HWFwdTree'
     VolSpec: [1x1 struct]
    TimeSpec: [1x1 struct]
    RateSpec: [1x1 struct]
        tObs: [0 0.9973 1.9973 2.9973]
        dObs: [731947 732312 732677 733042]
      CFlowT: {[4x1 double]  [3x1 double]  [2x1 double]  [3.9973]}
       Probs: {[3x1 double]  [3x3 double]  [3x5 double]}
     Connect: {[2]  [2 3 4]  [2 3 4 5 6]}
     FwdTree: {[1.0278]  [1.0536 1.0356 1.0178]  [1x5 double]  [1x7 double]}

Use treeviewer to observe the tree you have created.

Input Arguments

VolSpec — Volatility process specification

structure

Volatility process specification, specified using the VolSpec obtained from hwvolspec. See hwvolspec for information on the volatility process.

Data Types: struct

RateSpec — Interest-rate specification for initial rate curve

structure

Interest-rate specification for initial rate curve, specified by the RateSpec obtained from intenvset. For information on the interest-rate specification, see intenvset.

Data Types: struct

TimeSpec — Time layout specification

structure

Time layout specification, specified using the TimeSpec obtained from hwtimespec. The TimeSpec defines the observation dates of the HW tree and the compounding rule for date to time mapping and price-yield formulas. See hwtimespec for information on the tree structure.

Data Types: struct

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: HWTree = hwtree(VolSpec,RateSpec,TimeSpec,'Method','HW1996')

'Method' — Hull-White method upon which tree-node connectivity algorithm is based

HW2000 (default) | character vector with values of HW1996 or HW2000

Hull-White method upon which the tree-node connectivity algorithm is based, specified a character vector with a value of HW1996 or HW2000.

Note

hwtree supports two tree-node connectivity algorithms. HW1996 is based on the original paper published in the Journal of Derivatives, and HW2000 is the general version of the algorithm, as specified in the paper published in August 2000.

Data Types: char

Output Arguments

HWTree — Hull-White interest-rate tree

structure

Hull-White interest-rate tree, returned as a structure containing time and interest rate information of a trinomial recombining tree.

The HWTree structure returned contains all the information necessary to propagate back any cash flows occurring during the time span of the tree. The main fields of HWTree are:

• HWTree.tObs contains the time factor of each level of the tree.

• HWTree.dObs contains the date of each level of the tree.

• HWTree.Probs contains a cell array of 3-by-N numeric arrays with the up/mid/down probabilities of each node of the tree except for the last level. The cells in the cell array are ordered from root node. The arrays are 3-by-N with the first row corresponding to an up-move, the mid row to a mid-move and so on. Each column of the array represents a node starting from the top node of a given level.

• HWTree.Connect contains a cell array with connectivity information for each node of the tree. The arrangement is similar to HWTree.Probs, with the exception that it has only one row in each cell. The number represents the node in the next level to which the middle branch connects to. The top branch connects to the value above (minus one) and the lower branch connects to the value below (plus one).

• HWTree.FwdTree contains the forward spot rate from one node to the next. The forward spot rate is defined as the inverse of the discount factor.

References

[1] Hull, J., and A. White. "Using Hull-White Interest Rate Trees." Journal of Derivatives. 1996.

[2] Hull, J., and A. White. "The General Hull-White Model and Super Calibration.” August 2000.