IRTree

Create IRTree pricer object for Cap, Floor, Swap, Swaption, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument

Description

Create and price a Cap, Floor, Swap, Swaption, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object with a HullWhite or BlackKarasinski model and an IRTree pricing method using this workflow:

1. Use fininstrument to create a Cap, Floor, Swaption, Swap, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

2. Use finmodel to specify a HullWhite, BlackKarasinski, BlackDermanToy, or CoxIngersollRoss model for the Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

3. Use finpricer to specify an IRTree pricer object for a BK, BDT, CIR, or HW trinomial tree model for the Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

For more information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

For more information on the available instruments, models, and pricing methods for a Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

IRTreePricerObj = finpricer(PricerType,'Model',model_type,'DiscountCurve',ratecurve_obj,'TreeDates',tree_dates)

IRTreePricerObj = finpricer(PricerType,'Model',model_type,'DiscountCurve',ratecurve_obj,'Maturity',maturity_date,'NumPeriods',number_periods)

Description

IRTreePricerObj = finpricer(PricerType,'Model',model_type,'DiscountCurve',ratecurve_obj,'TreeDates',tree_dates) creates a IRTree pricer object for BDT, HW, and BK models by specifying PricerType and the required name-value pair arguments for Model, DiscountCurve, and TreeDates to set properties using name-value pair arguments. For example, IRTreePricerObj = finpricer("IRTree",'Model',HullWhite,'DiscountCurve',ratecure_obj,'TreeDates',['jan-30-2018';'jan-30-2019']) creates an IRTree pricer object for a HW model.

IRTreePricerObj = finpricer(PricerType,'Model',model_type,'DiscountCurve',ratecurve_obj,'Maturity',maturity_date,'NumPeriods',number_periods) creates a IRTree pricer object for a CIR model by specifying PricerType and the required name-value pair arguments for Model, DiscountCurve, and Maturity, and NumPeriods to set properties using name-value pair arguments. For example, IRTreePricerObj = finpricer("IRTree",'Model',CIRModel,'DiscountCurve',ZeroCurve,'Maturity',ZDates(end),'NumPeriods', length(ZDates)) creates an IRTree pricer object for a CIR model.

Input Arguments

PricerType — Pricer type

string with value "IRTree" | character vector with value 'IRTree'

Pricer type, specified as a string with the value of "IRTree" or a character vector with the value of 'IRTree'.

Data Types: char | string

Name-Value Arguments

Specify required 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: IRTreePricerObj = finpricer("IRTree",'Model',HullWhite,'DiscountCurve',ratecure_obj,'TreeDates',['jan-30-2018';'jan-30-2019'])

Required Name-Value Pair Arguments

Model — Model type

HullWhite object | BlackKarasinski object | BlackDermanToy object | CoxIngersollRoss object

Model type, specified as the comma-separated pair consisting of 'Model' and the name of a previously created HullWhite, BlackKarasinski, BlackDermanToy, or CoxIngersollRoss model object.

Create the model object using finmodel.

Note

When you use a HullWhite model, the IRTree pricer uses the HW2000 algorithm [1].

Data Types: object

DiscountCurve — ratecurve object for creating IRTree and discounting cash flows

Read-only: ratecurve object

This property is read-only.

ratecurve object for creating IRTree and discounting cash flows, specified as the comma-separated pair consisting of 'DiscountCurve' and the name of a ratecurve object.

Data Types: object

Required Name-Value Pair Argument for BDT, HW, and BK Models

TreeDates — Dates marking the cash flow dates of the tree

vector

Dates marking the cash flow dates of the tree, specified as the comma-separated pair consisting of 'TreeDates' and an NLEVELS-by-1 vector of dates. Cash flows with these dates will fall on tree nodes. The TreeDates argument determines the number of levels, or depth, of the tree. List dates in increasing order.

Note

Only use TreeDates when you specify a HullWhite, BlackKarasinski, or BlackDermanToy model object in the Model argument.

Data Types: double | cell | datetime

Required Name-Value Pair Arguments for CIR Model

Maturity — Date marking the depth of CIR tree

datetime | string | character vector

Date marking the depth of the CIR tree, specified as the comma-separated pair consisting of 'Maturity' and a scalar datetime, string, or character vector.

Note

Only use Maturity when you specify a CoxIngersollRoss model object in the Model argument.

Data Types: double | string | datetime

NumPeriods — Number of levels of CIR tree

numeric

Number of levels of CIR tree, specified as the comma-separated pair consisting of 'NumPeriods' and a scalar numeric value.

Note

Only use NumPeriods when you specify a CoxIngersollRoss model object in the Model argument.

Data Types: double

Output Arguments

IRTreePricerObj — IRTree pricer

IRTree object

IRTree pricer, returned as a IRTree object.

Properties

Tree — HW, BK, or CIR trinomial tree

struct for HW, BK, or CIR tree

HW, BK, or CIR trinomial tree, returned as a struct with the following properties:

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

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

• 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.

• CFlowT is a cell array with as many elements as levels of the tree. Each cell array element contains the time factors (tObs) corresponding to its level of the tree and those levels ahead of it.

• Probs contains the probability arrays. Each element of the cell array contains the up, middle, and down transition probabilities for each node of the level.

• Connect contains a cell array with connectivity information for each node of the tree. The arrangement is similar to 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).

• 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.

• RateTree contains the interest rate from one node to the next.

Data Types: struct

TreeDates — Tree dates

datetime

Tree dates, returned as a scalar datetime or datetime array.

Data Types: datetime

Model — Model type

HullWhite object | BlackKarasinski object | BlackDermanToy object | CoxIngersollRoss

Model type, returned as an object.

Data Types: object

DiscountCurve — ratecurve object for creating IRTree and discounting cash flows

Read-only: ratecurve object

This property is read-only.

ratecurve object for creating the IRTree object and discounting cash flows, returned as a ratecurve object.

Data Types: object

Object Functions

price	Compute price for interest-rate instrument with IRTree pricer
oas	Compute option adjusted spread for OptionEmbeddedFixedBond instrument using interest-rate tree

Examples

Use IRTree Pricer and HullWhite Model to Price FixedBondOption Instrument

This example shows the workflow to price a FixedBondOption instrument when you use a HullWhite model and an IRTree pricing method.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object as the underlying bond.

BondInst = fininstrument("FixedBond",'Maturity',datetime(2029,9,15),'CouponRate',0.025,'Period', 1,'Name',"fixed_bond_instrument")

BondInst = 
  FixedBond with properties:

                  CouponRate: 0.0250
                      Period: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 15-Sep-2029
                        Name: "fixed_bond_instrument"

Create FixedBondOption Instrument Object

Use fininstrument to create a FixedBondOption instrument object.

FixedBOption = fininstrument("FixedBondOption",'ExerciseDate',datetime(2025,9,15),'Strike',98,'Bond',BondInst,'Name',"fixed_bond_option_instrument")

FixedBOption = 
  FixedBondOption with properties:

       OptionType: "call"
    ExerciseStyle: "european"
     ExerciseDate: 15-Sep-2025
           Strike: 98
             Bond: [1×1 fininstrument.FixedBond]
             Name: "fixed_bond_option_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2019,9,15);
Type = 'zero';
ZeroTimes = [calyears([1:10])]';
ZeroRates = [0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307 0.0310]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Sep-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",'Alpha',0.01,'Sigma',0.05)

HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0100
    Sigma: 0.0500

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object with the 'DiscountCurve' name-value pair argument.

HWTreePricer = finpricer("irtree",'Model',HullWhiteModel,'DiscountCurve',myRC,'TreeDates',ZeroDates)

HWTreePricer = 
  HWBKTree with properties:

             Tree: [1×1 struct]
        TreeDates: [10×1 datetime]
            Model: [1×1 finmodel.HullWhite]
    DiscountCurve: [1×1 ratecurve]

HWTreePricer.Tree

ans = struct with fields:
        tObs: [0 1 1.9973 2.9945 3.9918 4.9918 5.9891 6.9863 7.9836 8.9836]
        dObs: [15-Sep-2019    15-Sep-2020    15-Sep-2021    15-Sep-2022    15-Sep-2023    15-Sep-2024    15-Sep-2025    15-Sep-2026    15-Sep-2027    15-Sep-2028]
      CFlowT: {[10×1 double]  [9×1 double]  [8×1 double]  [7×1 double]  [6×1 double]  [5×1 double]  [4×1 double]  [3×1 double]  [2×1 double]  [9.9809]}
       Probs: {[3×1 double]  [3×3 double]  [3×5 double]  [3×7 double]  [3×9 double]  [3×11 double]  [3×13 double]  [3×15 double]  [3×17 double]}
     Connect: {[2]  [2 3 4]  [2 3 4 5 6]  [2 3 4 5 6 7 8]  [2 3 4 5 6 7 8 9 10]  [2 3 4 5 6 7 8 9 10 11 12]  [2 3 4 5 6 7 8 9 10 11 12 13 14]  [2 3 4 5 6 7 8 9 10 11 12 13 14 15 16]  [2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18]}
     FwdTree: {1×10 cell}
    RateTree: {1×10 cell}

Price FixedBondOption Instrument

Use price to compute the price and sensitivities for the FixedBondOption instrument.

[Price, outPR] = price(HWTreePricer,FixedBOption,["all"])

Price = 
11.1739

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price      Delta     Gamma      Vega 
    ______    _______    ______    ______

    11.174    -272.19    3667.6    243.09

Use BlackKarasinski Tree Pricer and BlackKarasinski Model to Price FixedBondOption Instrument

This example shows the workflow to price a FixedBondOption instrument when you use a BlackKarasinski model and an IRTree pricing method.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object as the underlying bond.

BondInst = fininstrument("FixedBond",'Maturity',datetime(2029,9,15),'CouponRate',0.025,'Period',1,'Name',"fixed_bond_instrument")

BondInst = 
  FixedBond with properties:

                  CouponRate: 0.0250
                      Period: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 15-Sep-2029
                        Name: "fixed_bond_instrument"

Create FixedBondOption Instrument Object

Use fininstrument to create a FixedBondOption instrument object.

FixedBOption = fininstrument("FixedBondOption",'ExerciseDate',datetime(2025,9,15),'Strike',100,'Bond',BondInst,'Name',"fixed_bond_option")

FixedBOption = 
  FixedBondOption with properties:

       OptionType: "call"
    ExerciseStyle: "european"
     ExerciseDate: 15-Sep-2025
           Strike: 100
             Bond: [1×1 fininstrument.FixedBond]
             Name: "fixed_bond_option"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2019,9,15);
Type = 'zero';
ZeroTimes = [calyears([1:10])]';
ZeroRates = [0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307 0.0310]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Sep-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create BlackKarasinski Model Object

Use finmodel to create a BlackKarasinski model object.

BlackKarasinskiModel = finmodel("BlackKarasinski",'Alpha',0.02,'Sigma',0.34)

BlackKarasinskiModel = 
  BlackKarasinski with properties:

    Alpha: 0.0200
    Sigma: 0.3400

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

BKTreePricer = finpricer("IRTree",'Model',BlackKarasinskiModel,'DiscountCurve',myRC,'TreeDates',ZeroDates)

BKTreePricer = 
  HWBKTree with properties:

             Tree: [1×1 struct]
        TreeDates: [10×1 datetime]
            Model: [1×1 finmodel.BlackKarasinski]
    DiscountCurve: [1×1 ratecurve]

BKTreePricer.Tree

ans = struct with fields:
        tObs: [0 1 1.9973 2.9945 3.9918 4.9918 5.9891 6.9863 7.9836 8.9836]
        dObs: [15-Sep-2019    15-Sep-2020    15-Sep-2021    15-Sep-2022    15-Sep-2023    15-Sep-2024    15-Sep-2025    15-Sep-2026    15-Sep-2027    15-Sep-2028]
      CFlowT: {[10×1 double]  [9×1 double]  [8×1 double]  [7×1 double]  [6×1 double]  [5×1 double]  [4×1 double]  [3×1 double]  [2×1 double]  [9.9809]}
       Probs: {[3×1 double]  [3×3 double]  [3×5 double]  [3×7 double]  [3×9 double]  [3×11 double]  [3×13 double]  [3×15 double]  [3×17 double]}
     Connect: {[2]  [2 3 4]  [2 3 4 5 6]  [2 3 4 5 6 7 8]  [2 3 4 5 6 7 8 9 10]  [2 3 4 5 6 7 8 9 10 11 12]  [2 3 4 5 6 7 8 9 10 11 12 13 14]  [2 3 4 5 6 7 8 9 10 11 12 13 14 15 16]  [2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18]}
     FwdTree: {1×10 cell}
    RateTree: {1×10 cell}

Price FixedBondOption Instrument

Use price to compute the price and sensitivities for the FixedBondOption instrument.

[Price, outPR] = price(BKTreePricer,FixedBOption,["all"])

Price = 
0.5814

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
     Price      Delta     Gamma     Vega 
    _______    _______    ______    _____

    0.58143    -15.842    45.702    2.793

Use HullWhite Tree Pricer and HullWhite Model to Price Vanilla FixedBond Instrument

This example shows the workflow to price a vanilla FixedBond instrument when you use a HullWhite model and an IRTree pricing method.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

Maturity = datetime(2024,1,1);
Period = 1;
VBond = fininstrument("FixedBond",'Maturity', Maturity,'CouponRate', 0.025,'Period',Period) 

VBond = 
  FixedBond with properties:

                  CouponRate: 0.0250
                      Period: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Jan-2024
                        Name: ""

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,1,1);
ZeroTimes = calyears(1:10)';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
Compounding = 1;
ZeroCurve = ratecurve("zero",Settle,ZeroDates,ZeroRates, "Compounding",Compounding);

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

VolCurve = 0.01;
AlphaCurve = 0.1;

HWModel = finmodel("HullWhite",'alpha',AlphaCurve,'sigma',VolCurve);

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

HWTreePricer = finpricer("IRTree",'Model',HWModel,'DiscountCurve',ZeroCurve,'TreeDates',ZeroDates)

HWTreePricer = 
  HWBKTree with properties:

             Tree: [1×1 struct]
        TreeDates: [10×1 datetime]
            Model: [1×1 finmodel.HullWhite]
    DiscountCurve: [1×1 ratecurve]

Price FixedBond Instrument

Use price to compute the price and sensitivities for the vanilla FixedBond instrument.

[Price, outPR] = price(HWTreePricer, VBond,["all"])

Price = 
107.7023

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price     Delta     Gamma     Vega
    _____    _______    ______    ____

    107.7    -602.56    4086.4     0  

Use HullWhite Tree Pricer and HullWhite Model to Price Vanilla FloatBond Instrument

This example shows the workflow to price a vanilla FloatBond instrument when you use a HullWhite model and an IRTree pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,1,1);
ZeroTimes = calyears(1:10)';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
Compounding = 1;
ZeroCurve = ratecurve("zero",Settle,ZeroDates,ZeroRates, "Compounding",Compounding);

Create FloatBond Instrument Object

Use fininstrument to create a vanilla FloatBond instrument object.

Spread = 0.03;
Reset = 1;
Maturity = datetime(2024,1,1);
Period = 1;
Float = fininstrument("FloatBond",'Maturity',Maturity,'Spread',Spread,'Reset',Reset,'ProjectionCurve',ZeroCurve)

Float = 
  FloatBond with properties:

                      Spread: 0.0300
             ProjectionCurve: [1×1 ratecurve]
                 ResetOffset: 0
                       Reset: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
          LatestFloatingRate: NaN
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Jan-2024
                        Name: ""

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

VolCurve = 0.01;
AlphaCurve = 0.1;

HWModel = finmodel("HullWhite",'alpha',AlphaCurve,'sigma',VolCurve);

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

HWTreePricer = finpricer("IRTree",'Model',HWModel,'DiscountCurve',ZeroCurve,'TreeDates',ZeroDates)

HWTreePricer = 
  HWBKTree with properties:

             Tree: [1×1 struct]
        TreeDates: [10×1 datetime]
            Model: [1×1 finmodel.HullWhite]
    DiscountCurve: [1×1 ratecurve]

Price FloatBond Instrument

Use price to compute the price and sensitivities for the vanilla FloatBond instrument.

[Price, outPR] = price(HWTreePricer,Float,["all"])

Price = 
117.4686

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price      Delta     Gamma     Vega
    ______    _______    ______    ____

    117.47    -60.007    315.09     0  

Use IRTree Pricer and BlackDermanToy Model to Price FixedBondOption Instrument

This example shows the workflow to price a FixedBondOption instrument when you use a BlackDermanToy model and an IRTree pricing method.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object as the underlying bond.

BondInst = fininstrument("FixedBond",Maturity=datetime(2029,9,15),CouponRate=.024,Principal=100,Basis=1,Period=1,Name="fixed_bond")

BondInst = 
  FixedBond with properties:

                  CouponRate: 0.0240
                      Period: 1
                       Basis: 1
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 15-Sep-2029
                        Name: "fixed_bond"

Create FixedBondOption Instrument Object

Use fininstrument to create a FixedBondOption instrument object.

FixedBOption = fininstrument("FixedBondOption",ExerciseDate=datetime(2025,9,15),Strike=800,Bond=BondInst,OptionType="put",ExerciseStyle="american",Name="fixed_bond_option")

FixedBOption = 
  FixedBondOption with properties:

       OptionType: "put"
    ExerciseStyle: "american"
     ExerciseDate: 15-Sep-2025
           Strike: 800
             Bond: [1×1 fininstrument.FixedBond]
             Name: "fixed_bond_option"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2019,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:10)]';
ZeroRates = [0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307 0.0310]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates,Basis=5)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 5
                Dates: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Sep-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create BlackDermanToy Model Object

Use finmodel to create a BlackDermanToy model object.

BlackDermanToyModel = finmodel("BlackDermanToy",Sigma=0.14)

BlackDermanToyModel = 
  BlackDermanToy with properties:

    Sigma: 0.1400

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

BKTreePricer = finpricer("IRTree",Model=BlackDermanToyModel,DiscountCurve=myRC,TreeDates=ZeroDates)

BKTreePricer = 
  BDTTree with properties:

             Tree: [1×1 struct]
        TreeDates: [10×1 datetime]
            Model: [1×1 finmodel.BlackDermanToy]
    DiscountCurve: [1×1 ratecurve]

BKTreePricer.Tree

ans = struct with fields:
        tObs: [0 1 2 3 4 5 6 7 8 9]
        dObs: [15-Sep-2019    15-Sep-2020    15-Sep-2021    15-Sep-2022    15-Sep-2023    15-Sep-2024    15-Sep-2025    15-Sep-2026    15-Sep-2027    15-Sep-2028]
     FwdTree: {1×10 cell}
    RateTree: {1×10 cell}

Price FixedBondOption Instrument

Use price to compute the price and sensitivities for the FixedBondOption instrument.

[Price, outPR] = price(BKTreePricer,FixedBOption,"all")

Price = 
705.2729

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price     Delta      Gamma        Vega    
    ______    ______    _______    ___________

    705.27    844.75    -8084.8    -2.0464e-08

Use IRTree Pricer and CoxIngersollRoss Model to Price FixedBond Instrument

This example shows the workflow to price a FixedBond instrument when you use a CoxIngersollRoss model and an IRTree pricing method.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

Period = 1;
Maturity = datetime(2027,1,1); 
CouponRate = 0.035;
FixedBond = fininstrument("FixedBond",'Maturity',Maturity,'CouponRate',CouponRate,'Period',Period,Name="fixed_bond")

FixedBond = 
  FixedBond with properties:

                  CouponRate: 0.0350
                      Period: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Jan-2027
                        Name: "fixed_bond"

Create CoxIngersollRoss Model Object

Use finmodel to create a CoxIngersollRoss model object.

alpha = 0.03; 
theta = 0.02; 
sigma = 0.1; 
CIRModel = finmodel("CoxIngersollRoss",Sigma=sigma,Alpha=alpha,Theta=theta)

CIRModel = 
  CoxIngersollRoss with properties:

    Sigma: 0.1000
    Alpha: 0.0300
    Theta: 0.0200

Create ratecurve Object

Create a ratecurve object using ratecurve.

Times= [calyears([1 2 3 4 ])]';
Settle = datetime(2023,1,1);
ZRates = [0.035; 0.042147; 0.047345; 0.052707]';
ZDates = Settle + Times;
Compounding = -1; 
Basis = 1;
ZeroCurve = ratecurve("zero",Settle,ZDates,ZRates,Compounding = Compounding, Basis = Basis);

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object for the CoxIngersollRoss model and use the ratecurve object for the 'DiscountCurve' name-value argument.

CIRPricer = finpricer("irtree",Model=CIRModel,DiscountCurve=ZeroCurve,Maturity=ZDates(end),NumPeriods=length(ZDates))

CIRPricer = 
  CIRTree with properties:

             Tree: [1×1 struct]
        TreeDates: [4×1 datetime]
            Model: [1×1 finmodel.CoxIngersollRoss]
    DiscountCurve: [1×1 ratecurve]

Price FixedBond Instrument

Use price to compute the price for the FixedBond instrument.

[Price,outPR] = price(CIRPricer,FixedBond,"all")

Price = 
93.4593

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price      Delta     Gamma        Vega    
    ______    _______    ______    ___________

    93.459    -354.23    1384.8    -1.4211e-10

References

[1] Hull, John, and Alan White. “The General Hull–White Model and Supercalibration.” Financial Analysts Journal, vol. 57, no. 6, Nov. 2001, pp. 34–43.

Version History

Introduced in R2020a

R2023b: Support for CoxIngersollRoss Model

You can use IRTree with a CoxIngersollRoss model.

R2023a: Support for Option Adjusted Spread

You can use the oas function to calculate the option adjusted spread (OAS) when using an IRTree pricer object with an HullWhite, BlackKarasinski, or BlackDermanToy model.

R2022b: Support for Black-Derman-Toy model

The name-value argument option for Model supports a "BlackDermanToy" binomial tree model.