Main Content

hwtree

Build Hull-White interest-rate tree

collapse all in page

Syntax

HWTree = hwtree(VolSpec,RateSpec,TimeSpec)
HWTree = hwtree(___,Name,Value)

Description

example

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

example

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

Examples

collapse all

Open Live Script

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]  [1.0847 1.0661 1.0478 1.0298 1.0121]  [1.1156 1.0965 1.0776 1.0591 1.0409 1.0231 1.0055]}

Use treeviewer to observe the tree you have created.

Input Arguments

collapse all

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

Data Types: struct

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

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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

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

collapse all

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.

Version History

Introduced before R2006a

See Also

| | | | |

Topics