## Understanding Equity Trees

### Introduction

Financial Instruments Toolbox™ supports five types of recombining tree models to represent the evolution of stock prices:

Cox-Ross-Rubinstein (CRR) model

Equal probabilities (EQP) model

Leisen-Reimer (LR) model

Implied trinomial tree (ITT) model

Standard trinomial tree (STT) model

For a discussion of recombining trees, see Rate and Price Trees.

The CRR, EQP, LR, STT, and ITT models are examples of discrete time models. A discrete time model divides time into discrete bits; prices can only be computed at these specific times.

The CRR model is one of the most common methods used to model the evolution of stock processes. The strength of the CRR model lies in its simplicity. It is a good model when dealing with many tree levels. The CRR model yields the correct expected value for each node of the tree and provides a good approximation for the corresponding local volatility. The approximation becomes better as the number of time steps represented in the tree is increased.

The EQP model is another discrete time model. It has the advantage of building a tree with the exact volatility in each tree node, even with small numbers of time steps. It also provides better results than CRR in some given trading environments, for example, when stock volatility is low and interest rates are high. However, this additional precision causes increased complexity, which is reflected in the number of calculations required to build a tree.

The LR model is another discrete time model. It has the advantage of producing estimates close to the Black-Scholes model using only a few steps, while also minimizing the oscillation.

The ITT model is a CRR-style implied trinomial tree which takes advantage of prices quoted from liquid options in the market with varying strikes and maturities to build a tree that more accurately represents the market. An ITT model is commonly used to price exotic options in such a way that they are consistent with the market prices of standard options.

The STT model is another discrete time model. It is considered to produce more accurate results than the binomial model when fewer time steps are modeled. The STT model is sometimes more stable and accurate than the binomial model when pricing exotic options.

### Building Equity Binary Trees

The tree of stock prices is the fundamental unit representing
the evolution of the price of a stock over a given period of time.
The MATLAB^{®} functions `crrtree`

, `eqptree`

, and `lrtree`

create
CRR trees, EQP trees, and LR trees, respectively. These functions
create an output tree structure along with information about the parameters
used for creating the tree.

The functions `crrtree`

, `eqptree`

, and `lrtree`

take
three structures as input arguments:

The stock parameter structure

`StockSpec`

The interest-rate term structure

`RateSpec`

The tree time layout structure

`TimeSpec`

#### Calling Sequence for Equity Binary Trees

The calling syntax for `crrtree`

is:

CRRTree = crrtree (StockSpec, RateSpec, TimeSpec)

Similarly, the calling syntax for `eqptree`

is:

EQPTree = eqptree (StockSpec, RateSpec, TimeSpec)

And, the calling syntax for `lrtree`

is:

LRTree = lrtree(StockSpec, RateSpec, TimeSpec, Strike)

All three functions require the structures `StockSpec`

, `RateSpec`

,
and `TimeSpec`

as input arguments:

`StockSpec`

is a structure that specifies parameters of the stock whose price evolution is represented by the tree. This structure, created using the function`stockspec`

, contains information such as the stock's original price, its volatility, and its dividend payment information.`RateSpec`

is the interest-rate specification of the initial rate curve. Create this structure with the function`intenvset`

.`TimeSpec`

is the tree time layout specification. Create these structures with the functions`crrtimespec`

,`eqptimespec`

, and`lrtimespec`

. The structures contain information regarding the mapping of relevant dates into the tree structure, plus the number of time steps used for building the tree.

#### Specifying the Stock Structure for Equity Binary Trees

The structure `StockSpec`

encapsulates the
stock-specific information required for building the binary tree of
an individual stock's price movement.

You generate `StockSpec`

with the function `stockspec`

. This function requires two
input arguments and accepts up to three additional input arguments
that depend on the existence and type of dividend payments.

The syntax for calling `stockspec`

is:

```
StockSpec = stockspec(Sigma, AssetPrice, DividendType,
...
```

DividendAmounts, ExDividendDates)

where:

`Sigma`

is the decimal annual volatility of the underlying security.`AssetPrice`

is the price of the stock at the valuation date.`DividendType`

is a character vector specifying the type of dividend paid by the stock. Allowed values are`cash`

,`constant`

, or`continuous`

.`DividendAmounts`

has a value that depends on the specification of`DividendType`

. For`DividendType`

`cash`

,`DividendAmounts`

is a vector of cash dividends. For`DividendType`

`constant`

, it is a vector of constant annualized dividend yields. For`DividendType`

`continuous`

, it is a scalar representing a continuously annualized dividend yield.`ExDividendDates`

also has a value that depends on the nature of`DividendType`

. For`DividendType`

`cash`

or`constant`

,`ExDividendDates`

is vector of dividend dates. For`DividendType`

`continuous`

,`ExDividendDates`

is ignored.

#### Stock Structure Example Using a Binary Tree

Consider a stock with a price of $100 and an annual volatility of 15%. Assume that the stock pays three cash $5.00 dividends on dates January 01, 2004, July 01, 2005, and January 01, 2006. You specify these parameters in MATLAB as:

Sigma = 0.15; AssetPrice = 100; DividendType = 'cash'; DividendAmounts = [5; 5; 5]; ExDividendDates = {'jan-01-2004', 'july-01-2005', 'jan-01-2006'}; StockSpec = stockspec(Sigma, AssetPrice, DividendType, ... DividendAmounts, ExDividendDates)

StockSpec = FinObj: 'StockSpec' Sigma: 0.1500 AssetPrice: 100 DividendType: 'cash' DividendAmounts: [3x1 double] ExDividendDates: [3x1 double]

#### Specifying the Interest-Rate Term Structure for Equity Binary Trees

The `RateSpec`

structure defines the interest
rate environment used when building the stock price binary tree. Modeling the Interest-Rate Term Structure explains
how to create these structures using the function `intenvset`

, given the interest rates,
the starting and ending dates for each rate, and the compounding value.

#### Specifying the Tree-Time Term Structure for Equity Binary Trees

The `TimeSpec`

structure
defines the tree layout of the binary tree:

It maps the valuation and maturity dates to their corresponding times.

It defines the time of the levels of the tree by dividing the time span between valuation and maturity into equally spaced intervals. By specifying the number of intervals, you define the granularity of the tree time structure.

The syntax for building a `TimeSpec`

structure
is:

```
TimeSpec = crrtimespec(ValuationDate, Maturity,
NumPeriods)
```

TimeSpec = eqptimespec(ValuationDate,
Maturity, NumPeriods)

```
TimeSpec = lrtimespec(ValuationDate,
Maturity, NumPeriods)
```

where:

`ValuationDate`

is a scalar date marking the pricing date and first observation in the tree (location of the root node). You enter`ValuationDate`

either as a datetime or a date character vector.`Maturity`

is a scalar date marking the maturity of the tree, entered as a serial date number or a date character vector.`NumPeriods`

is a scalar defining the number of time steps in the tree; for example,`NumPeriods = 10`

implies 10 time steps and 11 tree levels (0, 1, 2, ..., 9, 10).

`TimeSpec`

Example Using a Binary Tree

Consider building a CRR tree, with a valuation date of January 1, 2003, a maturity date of January 1, 2008, and 20 time steps. You specify these parameters in MATLAB as:

ValuationDate = datetime(2003,1,1); Maturity = datetime(2008,1,1); NumPeriods = 20; TimeSpec = crrtimespec(ValuationDate, Maturity, NumPeriods)

TimeSpec = FinObj: 'BinTimeSpec' ValuationDate: 731582 Maturity: 733408 NumPeriods: 20 Basis: 0 EndMonthRule: 1 tObs: [1x21 double] dObs: [1x21 double]

Two vector fields in the `TimeSpec`

structure are of
particular interest: `dObs`

and `tObs`

. These
two fields represent the observation times and corresponding dates of all tree
levels, with `dObs(1)`

and `tObs(1)`

,
respectively, representing the root node (`ValuationDate`

), and
`dObs(end)`

and `tObs(end)`

representing
the last tree level (`Maturity`

).

**Note**

There is no relationship between the dates specified for the tree and the
implied tree level times, and the maturities specified in the interest-rate
term structure. The rates in `RateSpec`

are interpolated or
extrapolated as required to meet the time distribution of the tree.

#### Examples of Binary Tree Creation

You can now use the `StockSpec`

and `TimeSpec`

structures
described previously to build an equal probability tree (`EQPTree`

),
a CRR tree (`CRRTree`

), or an LR tree (`LRTree`

).
First, you must define the interest-rate term structure. For this
example, assume that the interest rate is fixed at 10% annually between
the valuation date of the tree (January 1, 2003) until its maturity.

ValuationDate = datetime(2003,1,1); Maturity = datetime(2008,1,1); Rate = 0.1; RateSpec = intenvset('Rates', Rate, 'StartDates', ... ValuationDate, 'EndDates', Maturity, 'Compounding', -1);

To build a `CRRTree`

, enter:

CRRTree = crrtree(StockSpec, RateSpec, TimeSpec)

CRRTree = FinObj: 'BinStockTree' Method: 'CRR' StockSpec: [1x1 struct] TimeSpec: [1x1 struct] RateSpec: [1x1 struct] tObs: [1x21 double] dObs: [1x21 double] STree: {1x21 cell} UpProbs: [1x20 double]

To build an `EQPTree`

, enter:

EQPTree = eqptree(StockSpec, RateSpec, TimeSpec)

EQPTree = FinObj: 'BinStockTree' Method: 'EQP' StockSpec: [1x1 struct] TimeSpec: [1x1 struct] RateSpec: [1x1 struct] tObs: [1x21 double] dObs: [1x21 double] STree: {1x21 cell} UpProbs: [1x20 double]

### Building Implied Trinomial Trees

The tree of stock prices is the fundamental unit representing
the evolution of the price of a stock over a given period of time.
The function `itttree`

creates
an output tree structure along with the information about the parameters
used to create the tree.

The function `itttree`

takes
four structures as input arguments:

The stock parameter structure

`StockSpec`

The interest-rate term structure

`RateSpec`

The tree time layout structure

`TimeSpec`

The stock option specification structure

`StockOptSpec`

#### Calling Sequence for Implied Trinomial Trees

The calling syntax for `itttree`

is:

ITTTree = itttree (StockSpec,RateSpec,TimeSpec,StockOptSpec)

`StockSpec`

is a structure that specifies parameters of the stock whose price evolution is represented by the tree. This structure, created using the function`stockspec`

, contains information such as the stock's original price, its volatility, and its dividend payment information.`RateSpec`

is the interest-rate specification of the initial rate curve. Create this structure with the function`intenvset`

.`TimeSpec`

is the tree time layout specification. Create these structures with the function`itttimespec`

. This structure contains information regarding the mapping of relevant dates into the tree structure, plus the number of time steps used for building the tree.`StockOptSpec`

is a structure containing parameters of European stock options instruments. Create this structure with the function`stockoptspec`

.

#### Specifying the Stock Structure for Implied Trinomial Trees

The structure `StockSpec`

encapsulates the
stock-specific information required for building the trinomial tree
of an individual stock's price movement.

You generate `StockSpec`

with the function `stockspec`

. This function requires two
input arguments and accepts up to three additional input arguments
that depend on the existence and type of dividend payments.

The syntax for calling `stockspec`

is:

```
StockSpec = stockspec(Sigma, AssetPrice, DividendType,
...
```

DividendAmounts, ExDividendDates)

where:

`Sigma`

is the decimal annual volatility of the underlying security.`AssetPrice`

is the price of the stock at the valuation date.`DividendType`

is a character vector specifying the type of dividend paid by the stock. Allowed values are`cash`

,`constant`

, or`continuous`

.`DividendAmounts`

has a value that depends on the specification of`DividendType`

. For`DividendType`

`cash`

,`DividendAmounts`

is a vector of cash dividends. For`DividendType`

`constant`

, it is a vector of constant annualized dividend yields. For`DividendType`

`continuous`

, it is a scalar representing a continuously annualized dividend yield.`ExDividendDates`

also has a value that depends on the nature of`DividendType`

. For`DividendType`

`cash`

or`constant`

,`ExDividendDates`

is vector of dividend dates. For`DividendType`

`continuous`

,`ExDividendDates`

is ignored.

#### Stock Structure Example Using an Implied Trinomial Tree

Consider a stock with a price of $100 and an annual volatility of 12%. Assume that the stock is expected to pay a dividend yield of 6%. You specify these parameters in MATLAB as:

```
So = 100;
DividendYield = 0.06;
Sigma = .12;
StockSpec = stockspec(Sigma, So, 'continuous', DividendYield)
```

StockSpec = FinObj: 'StockSpec' Sigma: 0.1200 AssetPrice: 100 DividendType: 'continuous' DividendAmounts: 0.0600 ExDividendDates: []

#### Specifying the Interest-Rate Term Structure for Implied Trinomial Trees

The structure `RateSpec`

defines the interest
rate environment used when building the stock price binary tree. Modeling the Interest-Rate Term Structure explains
how to create these structures using the function `intenvset`

, given the interest rates,
the starting and ending dates for each rate, and the compounding value.

#### Specifying the Tree-Time Term Structure for Implied Trinomial Trees

The `TimeSpec`

structure
defines the tree layout of the trinomial tree:

It maps the valuation and maturity dates to their corresponding times.

It defines the time of the levels of the tree by dividing the time span between valuation and maturity into equally spaced intervals. By specifying the number of intervals, you define the granularity of the tree time structure.

The syntax for building a `TimeSpec`

structure
is:

`TimeSpec = itttimespec(ValuationDate, Maturity, NumPeriods)`

where:

`ValuationDate`

is a scalar date marking the pricing date and first observation in the tree (location of the root node). You enter`ValuationDate`

either as a datetime or a date character vector.`Maturity`

is a scalar date marking the maturity of the tree, entered as a serial date number or a date character vector.`NumPeriods`

is a scalar defining the number of time steps in the tree; for example,`NumPeriods = 10`

implies 10 time steps and 11 tree levels (0, 1, 2, ..., 9, 10).

`TimeSpec`

Example Using an Implied Trinomial Tree

Consider building an ITT tree, with a valuation date of January 1, 2006, a maturity date of January 1, 2008, and four time steps. You specify these parameters in MATLAB as:

ValuationDate = datetime(2006,1,1); EndDate = datetime(2008,1,1); NumPeriods = 4; TimeSpec = itttimespec(ValuationDate, EndDate, NumPeriods)

TimeSpec = FinObj: 'ITTTimeSpec' ValuationDate: 732678 Maturity: 733408 NumPeriods: 4 Basis: 0 EndMonthRule: 1 tObs: [0 0.5000 1 1.5000 2] dObs: [732678 732860 733043 733225 733408]

Two vector fields in the `TimeSpec`

structure are of
particular interest: `dObs`

and `tObs`

. These
two fields represent the observation times and corresponding dates of all tree
levels, with `dObs(1)`

and `tObs(1)`

,
respectively, representing the root node (`ValuationDate`

), and
`dObs(end)`

and `tObs(end)`

representing
the last tree level (`Maturity`

).

#### Specifying the Option Stock Structure for Implied Trinomial Trees

The `StockOptSpec`

structure
encapsulates the option-stock-specific information required for building
the implied trinomial tree. You generate `StockOptSpec`

with
the function `stockoptspec`

.
This function requires five input arguments. An optional sixth argument `InterpMethod`

,
specifying the interpolation method, can be included. The syntax for
calling `stockoptspec`

is:

[StockOptSpec] = stockoptspec(OptPrice, Strike, Settle, Maturity, OptSpec)

where:

`Optprice`

is a`NINST`

-by-`1`

vector of European option prices.`Strike`

is a`NINST`

-by-`1`

vector of strike prices.`Settle`

is a scalar date marking the settlement date.`Maturity`

is a`NINST`

-by-`1`

vector of maturity dates.`OptSpec`

is a`NINST`

-by-`1`

cell array of character vectors for the values`'call'`

or`'put'`

.

#### Option Stock Structure Example Using an Implied Trinomial Tree

Consider the following data quoted from liquid options in the market with varying strikes and maturity. You specify these parameters in MATLAB as:

Settle = '01/01/06'; Maturity = ['07/01/06'; '07/01/06'; '07/01/06'; '07/01/06'; '01/01/07'; '01/01/07'; '01/01/07'; '01/01/07'; '07/01/07'; '07/01/07'; '07/01/07'; '07/01/07'; '01/01/08'; '01/01/08'; '01/01/08'; '01/01/08']; Strike = [113; 101; 100; 88; 128; 112; 100; 78; 144; 112; 100; 69; 162; 112; 100; 61]; OptPrice = [ 0; 4.807905472659144; 1.306321897011867; 0.048039195057173; 0; 2.310953054191461; 1.421950392866235; 0.020414826276740; 0; 5.091986935627730; 1.346534812295291; 0.005101325584140; 0; 8.047628153217246; 1.219653432150932; 0.001041436654748]; OptSpec = { 'call'; 'call'; 'put'; 'put'; 'call'; 'call'; 'put'; 'put'; 'call'; 'call'; 'put'; 'put'; 'call'; 'call'; 'put'; 'put'}; StockOptSpec = stockoptspec(OptPrice, Strike, Settle, Maturity, OptSpec)

StockOptSpec = FinObj: 'StockOptSpec' OptPrice: [16x1 double] Strike: [16x1 double] Settle: 732678 Maturity: [16x1 double] OptSpec: {16x1 cell} InterpMethod: 'price'

**Note**

The algorithm for building the ITT tree requires specifying option prices
for all tree nodes. The maturities of those options correspond to those of
the tree levels, and the strike to the prices on the tree nodes. The types
of option are `Calls`

for the nodes above the central
nodes, and `Puts`

for those below and including the central
nodes.

Clearly, all these options will not be available in the market, hence
making interpolation, and extrapolation necessary to obtain the node option
prices. The degree to which the tree reflects the market will unavoidably be
tied to the results of these interpolations and extrapolations. Keeping in
mind that extrapolation is less accurate than interpolation, and more so the
further away the extrapolated points are from the data points, the function
`itttree`

issues a warning with a list of the options
for which extrapolation was necessary.

Sometimes, it may be desirable to view a list of ideal option prices to
form an idea of the ranges needed. This can be achieved by calling the
function `itttree`

specifying only the first three input
arguments. The second output argument is a structure array containing the
list of ideal options needed.

#### Creating an Implied Trinomial Tree

You can now use the `StockSpec`

, `TimeSpec`

,
and `StockOptSpec`

structures described in Stock Structure Example Using an Implied Trinomial Tree, TimeSpec Example Using an Implied Trinomial Tree, and Option Stock Structure Example Using an Implied Trinomial Tree to
build an implied trinomial tree (ITT). First, you must define the
interest rate term structure. For this example, assume that the interest
rate is fixed at 8% annually between the valuation date of the tree
(January 1, 2006) until its maturity.

Rate = 0.08; ValuationDate = datetime(2006,1,1); EndDate = datetime(2008,1,1); RateSpec = intenvset('StartDates', ValuationDate, 'EndDates', EndDate, ... 'ValuationDate', ValuationDate, 'Rates', Rate, 'Compounding', -1)

RateSpec = struct with fields: FinObj: 'RateSpec' Compounding: -1 Disc: 0.8521 Rates: 0.0800 EndTimes: 2 StartTimes: 0 EndDates: 733408 StartDates: 732678 ValuationDate: 732678 Basis: 0 EndMonthRule: 1

To build an `ITTTree`

,
enter:

ITTTree = itttree(StockSpec, RateSpec, TimeSpec, StockOptSpec)

ITTTree = FinObj: 'ITStockTree' StockSpec: [1x1 struct] StockOptSpec: [1x1 struct] TimeSpec: [1x1 struct] RateSpec: [1x1 struct] tObs: [0 0.500000000000000 1 1.500000000000000 2] dObs: [732678 732860 733043 733225 733408] STree: {1x5 cell} Probs: {[3x1 double] [3x3 double] [3x5 double] [3x7 double]}

### Building Standard Trinomial Trees

The tree of stock prices is the fundamental unit representing the evolution of the
price of a stock over a given period of time. The function `stttree`

creates an output tree
structure along with the information about the parameters used to create the tree.

The function `stttree`

takes three structures as
input arguments:

The stock parameter structure

`StockSpec`

The interest-rate term structure

`RateSpec`

The tree time layout structure

`TimeSpec`

#### Calling Sequence for Standard Trinomial Trees

The calling syntax for `stttree`

is:

STTTree = stttree (StockSpec,RateSpec,TimeSpec)

`StockSpec`

is a structure that specifies parameters of the stock whose price evolution is represented by the tree. This structure, created using the function`stockspec`

, contains information such as the stock's original price, its volatility, and its dividend payment information.`RateSpec`

is the interest-rate specification of the initial rate curve. Create this structure with the function`intenvset`

.`TimeSpec`

is the tree time layout specification. Create these structures with the function`stttimespec`

. This structure contains information regarding the mapping of relevant dates into the tree structure, plus the number of time steps used for building the tree.

#### Specifying the Stock Structure for Standard Trinomial Trees

The structure `StockSpec`

encapsulates the stock-specific
information required for building the trinomial tree of an individual stock's
price movement.

You generate `StockSpec`

with the function `stockspec`

. This function
requires two input arguments and accepts up to three additional input arguments
that depend on the existence and type of dividend payments.

The syntax for calling `stockspec`

is:

```
StockSpec = stockspec(Sigma, AssetPrice, DividendType, ...
```

DividendAmounts, ExDividendDates)

where:

`Sigma`

is the decimal annual volatility of the underlying security.`AssetPrice`

is the price of the stock at the valuation date.`DividendType`

is a character vector specifying the type of dividend paid by the stock. Allowed values are`cash`

,`constant`

, or`continuous`

.`DividendAmounts`

has a value that depends on the specification of`DividendType`

. For`DividendType`

`cash`

,`DividendAmounts`

is a vector of cash dividends. For`DividendType`

`constant`

, it is a vector of constant annualized dividend yields. For`DividendType`

`continuous`

, it is a scalar representing a continuously annualized dividend yield.`ExDividendDates`

also has a value that depends on the nature of`DividendType`

. For`DividendType`

`cash`

or`constant`

,`ExDividendDates`

is vector of dividend dates. For`DividendType`

`continuous`

,`ExDividendDates`

is ignored.

#### Stock Structure Example Using a Standard Trinomial Tree

Consider a stock with a price of $100 and an annual volatility of 12%. Assume that the stock is expected to pay a dividend yield of 6%. You specify these parameters in MATLAB as:

```
So = 100;
DividendYield = 0.06;
Sigma = .12;
StockSpec = stockspec(Sigma, So, 'continuous', DividendYield)
```

StockSpec = FinObj: 'StockSpec' Sigma: 0.1200 AssetPrice: 100 DividendType: 'continuous' DividendAmounts: 0.0600 ExDividendDates: []

#### Specifying the Interest-Rate Term Structure for Standard Trinomial Trees

The structure `RateSpec`

defines the interest rate
environment used when building the stock price binary tree. Modeling the Interest-Rate Term Structure explains how
to create these structures using the function `intenvset`

, given the
interest rates, the starting and ending dates for each rate, and the compounding
value.

#### Specifying the Tree-Time Term Structure for Standard Trinomial Trees

The `TimeSpec`

structure defines the tree layout of the
trinomial tree:

It maps the valuation and maturity dates to their corresponding times.

It defines the time of the levels of the tree by dividing the time span between valuation and maturity into equally spaced intervals. By specifying the number of intervals, you define the granularity of the tree time structure.

The syntax for building a `TimeSpec`

structure is:

```
TimeSpec = stttimespec(ValuationDate, Maturity,
NumPeriods)
```

where:

`ValuationDate`

is a scalar date marking the pricing date and first observation in the tree (location of the root node). You enter`ValuationDate`

either as a datetime or a date character vector.`Maturity`

is a scalar date marking the maturity of the tree, entered as a serial date number or a date character vector.`NumPeriods`

is a scalar defining the number of time steps in the tree; for example,`NumPeriods = 10`

implies 10 time steps and 11 tree levels (0, 1, 2, ..., 9, 10).

`TimeSpec`

Example Using a Standard Trinomial Tree

Consider building an STT tree, with a valuation date of January 1, 2006, a maturity date of January 1, 2008, and four time steps. You specify these parameters in MATLAB as:

ValuationDate = datetime(2006,1,1); EndDate = datetime(2008,1,1); NumPeriods = 4; TimeSpec = stttimespec(ValuationDate, EndDate, NumPeriods)

TimeSpec = FinObj: 'STTTimeSpec' ValuationDate: 732678 Maturity: 733408 NumPeriods: 4 Basis: 0 EndMonthRule: 1 tObs: [0 0.5000 1 1.5000 2] dObs: [732678 732860 733043 733225 733408]

Two vector fields in the `TimeSpec`

structure are of
particular interest: `dObs`

and `tObs`

. These
two fields represent the observation times and corresponding dates of all tree
levels, with `dObs(1)`

and `tObs(1)`

,
respectively, representing the root node (`ValuationDate`

), and
`dObs(end)`

and `tObs(end)`

representing
the last tree level (`Maturity`

).

#### Creating a Standard Trinomial Tree

You can now use the `StockSpec`

, `TimeSpec`

structures described in Stock Structure Example Using an Implied Trinomial Tree and TimeSpec Example Using an Implied Trinomial Tree, to build a
standard trinomial tree (STT). First, you must define the interest rate term
structure. For this example, assume that the interest rate is fixed at 8%
annually between the valuation date of the tree (January 1, 2006) until its
maturity.

Rate = 0.08; ValuationDate = datetime(2006,1,1); EndDate = datetime(2008,1,1); RateSpec = intenvset('StartDates', ValuationDate, 'EndDates', EndDate, ... 'ValuationDate', ValuationDate, 'Rates', Rate, 'Compounding', -1)

RateSpec = struct with fields: FinObj: 'RateSpec' Compounding: -1 Disc: 0.8521 Rates: 0.0800 EndTimes: 2 StartTimes: 0 EndDates: 733408 StartDates: 732678 ValuationDate: 732678 Basis: 0 EndMonthRule: 1

To build an `STTTree`

, enter:

STTTree = stttree(StockSpec, RateSpec, TimeSpec)

STTTree = FinObj: 'STStockTree' StockSpec: [1x1 struct] TimeSpec: [1x1 struct] RateSpec: [1x1 struct] tObs: [0 0.5000 1 1.5000 2] dObs: [732678 732860 733043 733225 733408] STree: {1x5 cell} Probs: {[3x1 double] [3x3 double] [3x5 double] [3x7 double]}

### Examining Equity Trees

Financial Instruments Toolbox uses equity binary and trinomial trees to represent prices of equity options and of underlying stocks. At the highest level, these trees have structures wrapped around them. The structures encapsulate information required to interpret information in the tree.

To examine an equity, binary, or trinomial tree, load the data
in the MAT-file `deriv.mat`

into the MATLAB workspace.

```
load deriv.mat
```

Display the list of variables loaded from the MAT-file with
the `whos`

command.

Name Size Bytes Class Attributes BDTInstSet 1x1 27344 struct BDTTree 1x1 7322 struct BKInstSet 1x1 27334 struct BKTree 1x1 8532 struct CRRInstSet 1x1 21066 struct CRRTree 1x1 7086 struct EQPInstSet 1x1 21066 struct EQPTree 1x1 7086 struct HJMInstSet 1x1 27336 struct HJMTree 1x1 8334 struct HWInstSet 1x1 27334 struct HWTree 1x1 8532 struct ITTInstSet 1x1 21070 struct ITTTree 1x1 12660 struct STTInstSet 1x1 21070 struct STTTree 1x1 7782 struct ZeroInstSet 1x1 17458 struct ZeroRateSpec 1x1 2152 struct

#### Examining a `CRRTree`

You can examine in some detail the contents of the `CRRTree`

structure contained in this file.

CRRTree

CRRTree = FinObj: 'BinStockTree' Method: 'CRR' StockSpec: [1x1 struct] TimeSpec: [1x1 struct] RateSpec: [1x1 struct] tObs: [0 1 2 3 4] dObs: [731582 731947 732313 732678 733043] STree: {[100] [110.5171 90.4837] [122.1403 100 81.8731] [1x4 double] [1x5 double]} UpProbs: [0.7309 0.7309 0.7309 0.7309]

The `Method`

field of the structure indicates that this is a
CRR tree, not an EQP tree.

The fields `StockSpec`

, `TimeSpec`

, and
`RateSpec`

hold the original structures passed into the
function `crrtree`

. They contain all the context information
required to interpret the tree data.

The fields `tObs`

and `dObs`

are vectors
containing the observation times and dates, that is, the times and dates of the
levels of the tree. In this particular case, `tObs`

reveals
that the tree has a maturity of four years (`tObs(end) = 4`

)
and that it has four time steps (the length of `tObs`

is five).

The field `dObs`

shows the specific dates for the tree
levels, with a granularity of one day. This means that all values in
`tObs`

that correspond to a given day from 00:00 hours to
24:00 hours are mapped to the corresponding value in `dObs`

.
You can use the function `datestr`

to convert these
MATLAB serial dates into their character vector representations.

The field `UpProbs`

is a vector representing the
probabilities for up movements from any node in each level. This vector has one
element per tree level. All nodes for a given level have the same probability of
an up movement. In the specific case being examined, the probability of an up
movement is 0.7309 for all levels, and the probability for a down movement is
0.2691 (1 − 0.7309).

Finally, the field `STree`

contains the actual stock tree. It
is represented in MATLAB as a cell array with each cell array element containing a vector
of prices corresponding to a tree level. The prices are in descending order,
that is, `CRRTree.STree{3}(1)`

represents the topmost element
of the third level of the tree, and `CRRTree.STree{3}(end)`

represents the bottom element of the same level of the tree.

#### Examining an `ITTTree`

You can examine in some detail the contents of the `ITTTree`

structure contained in this file.

ITTTree

ITTTree = FinObj: 'ITStockTree' StockSpec: [1x1 struct] StockOptSpec: [1x1 struct] TimeSpec: [1x1 struct] RateSpec: [1x1 struct] tObs: [0 1 2 3 4] dObs: [732678 733043 733408 733773 734139] STree: {1x5 cell} Probs: {[3x1 double] [3x3 double] [3x5 double] [3x7 double]}

The fields `StockSpec`

, `StockOptSpec`

,
`TimeSpec`

, and `RateSpec`

hold the
original structures passed into the function `itttree`

. They
contain all the context information required to interpret the tree data.

The fields `tObs`

and `dObs`

are vectors
containing the observation times and dates and the times and dates of the levels
of the tree. In this particular case, `tObs`

reveals that the
tree has a maturity of four years (`tObs(end) = 4`

) and that it
has four time steps (the length of `tObs`

is five).

The field `dObs`

shows the specific dates for the tree
levels, with a granularity of one day. This means that all values in
`tObs`

that correspond to a given day from 00:00 hours to
24:00 hours are mapped to the corresponding value in `dObs`

.
You can use the function `datestr`

to convert these
MATLAB serial dates into their character vector representations.

The field `Probs`

is a vector representing the probabilities
for movements from any node in each level. This vector has three elements per
tree node. In the specific case being examined, at `tObs`

=
`1`

, the probability for an up movement is 0.4675, and the
probability for a down movement is 0.1934.

Finally, the field `STree`

contains the actual stock tree. It
is represented in MATLAB as a cell array with each cell array element containing a vector
of prices corresponding to a tree level. The prices are in descending order,
that is, `ITTTree.STree{4}(1)`

represents the top element of
the fourth level of the tree, and `ITTTree.STree{4}(end)`

represents the bottom element of the same level of the tree.

#### Isolating a Specific Node for a `CRRTree`

The function `treepath`

can isolate a
specific set of nodes of a binary tree by specifying the path used to reach the
final node. As an example, consider the nodes tapped by starting from the root
node, then following a down movement, then an up movement, and finally a down
movement. You use a vector to specify the path, with `1`

corresponding to an up movement and `2`

corresponding to a down
movement. An up-down-up path is then represented as `[2 1 2]`

.
To obtain the values of all nodes tapped by this path, enter:

SVals = treepath(CRRTree.STree, [2 1 2])

SVals = 100.0000 90.4837 100.0000 90.4837

The first value in the vector `SVals`

corresponds to the root
node, and the last value corresponds to the final node reached by following the
path indicated.

#### Isolating a Specific Node for an `ITTTree`

The function `trintreepath`

can isolate a
specific set of nodes of a trinomial tree by specifying the path used to reach
the final node. As an example, consider the nodes tapped by starting from the
root node, then following an up movement, then a middle movement, and finally a
down movement. You use a vector to specify the path, with `1`

corresponding to an up movement, `2`

corresponding to a middle
movement, and `3`

corresponding to a down movement. An
up-down-middle-down path is then represented as `[1 3 2 3]`

. To
obtain the values of all nodes tapped by this path, enter:

pathSVals = trintreepath(ITTTree, [1 3 2 3])

pathSVals = 50.0000 66.3448 50.0000 50.0000 37.6819

The first value in the vector `pathSVals`

corresponds to the
root node, and the last value corresponds to the final node reached by following
the path indicated.

### Differences Between CRR and EQP Tree Structures

In essence, the structures representing CRR trees and EQP trees are similar. If you create a CRR or an EQP tree using identical input arguments, only a few of the tree structure fields differ:

The

`Method`

field has a value of`'CRR'`

or`'EQP'`

indicating the method used to build the structure.The prices in the

`STree`

cell array have the same structure, but the prices within the cell array are different.For EQP, the structure field

`UpProb`

always holds a vector with all elements set to 0.5, while for CRR, these probabilities are calculated based on the input arguments passed when building the tree.

## See Also

`crrtree`

| `eqptree`

| `lrtree`

| `stockspec`

| `intenvset`

| `crrtimespec`

| `eqptimespec`

| `lrtimespec`

| `itttree`

| `itttimespec`

| `stockoptspec`

| `treepath`

| `trintreepath`

## Related Examples

- Pricing Equity Derivatives Using Trees
- Creating Instruments or Properties
- Graphical Representation of Equity Derivative Trees