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 or BlackKarasinski model for the Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument.

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

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)

Description

IRTreePricerObj = finpricer(PricerType,'Model',model_type,'DiscountCurve',ratecurve_obj,'TreeDates',tree_dates) creates a IRTree pricer object 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.

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

IRTree Name-Value Pair Arguments

Specify required comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: IRTreePricerObj = finpricer("IRTree",'Model',"HullWhite",'DiscountCurve',ratecure_obj,'TreeDates',['jan-30-2018';'jan-30-2019'])

'Model' — Model type

string with value of "HullWhite" or "BlackKarasinski" | character vector with value of 'HullWhite' or 'BlackKarasinski'

Model type, specified as the comma-separated pair consisting of 'Model' and a character vector or string.

Note

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

Data Types: char | string

'DiscountCurve' — ratecurve object for creating IRTree and discounting cash flows

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

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

Data Types: double | cell | datetime

Properties

Tree — HW or BK trinomial tree

struct for HW or BK tree

HW or BK 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

string with value of "HullWhite" or "BlackKarasinski"

Model type, returned as a string.

Data Types: string

DiscountCurve — ratecurve object for creating IRTree and discounting cash flows

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

Examples

Use Hull-White Tree Pricer and Hull-White 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: [1x1 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: [10x1 datetime]
                Rates: [10x1 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: [1x1 struct]
        TreeDates: [10x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 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: [1x10 datetime]
      CFlowT: {1x10 cell}
       Probs: {1x9 cell}
     Connect: {1x9 cell}
     FwdTree: {1x10 cell}
    RateTree: {1x10 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: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results

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

    11.174    243.09    3667.6    -272.19

Use Black-Karasinski Tree Pricer and Black-Karasinski 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: [1x1 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: [10x1 datetime]
                Rates: [10x1 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: [1x1 struct]
        TreeDates: [10x1 datetime]
            Model: [1x1 finmodel.BlackKarasinski]
    DiscountCurve: [1x1 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: [1x10 datetime]
      CFlowT: {1x10 cell}
       Probs: {1x9 cell}
     Connect: {1x9 cell}
     FwdTree: {1x10 cell}
    RateTree: {1x10 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: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results

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

    0.58143    2.793    45.702    -15.842

Use Hull-White Tree Pricer and Hull-White 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: [1x1 struct]
        TreeDates: [10x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 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: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results

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

    107.7     0      4086.4    -602.56

Use Hull-White Tree Pricer and Hull-White 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: [1x1 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: [1x1 struct]
        TreeDates: [10x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 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: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results

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

    117.47     0      315.09    -60.007

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.