Main Content

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

| | | | | | | | | | | |

Related Examples

More About