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.

Note

Alternatively, you can use the IRTree object to price interest-rate instruments. For more information, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

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: [1×1 struct]
    TimeSpec: [1×1 struct]
    RateSpec: [1×1 struct]
        tObs: [0 0.9973 1.9973 2.9973]
        dObs: [731947 732312 732677 733042]
      CFlowT: {[4×1 double]  [3×1 double]  [2×1 double]  [3.9973]}
       Probs: {[3×1 double]  [3×3 double]  [3×5 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

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 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')

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.

More About

Hull-White Interest-Rate Tree

The Hull-White (HW) interest-rate tree describes the evolution of interest rates over time.

The HW interest-rate tree is useful for pricing interest-rate derivatives and managing interest-rate risk. The binomial tree structure allows for a straightforward representation of potential future interest rates, making it useful for pricing interest-rate derivatives and risk management.

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