HullWhite

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

Since R2020a

Description

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

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

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

3. Use finpricer to specify a HullWhite pricing method for a Cap, Floor, or Swaption instrument object and use an IRTree or IRMonteCarlo pricing method for the Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

4. Optionally, when using an OptionEmbeddedFixedBond with an IRTree pricing method and a HullWhite model, you can calculate the option adjusted spread (OAS) using oas.

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 pricing methods for a Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

HullWhiteModelObj = finmodel(ModelType,'Alpha'alpha_value,'Sigma',sigma_value)

Description

HullWhiteModelObj = finmodel(ModelType,'Alpha'alpha_value,'Sigma',sigma_value) creates a HullWhite model object by specifying ModelType and the required name-value pair argumentsAlpha and Sigma to set properties using name-value pair arguments. For example, HullWhiteModelObj = finmodel("HullWhite",'Alpha',0.052,'Sigma',0.34) creates a HullWhite model object.

Input Arguments

ModelType — Model type

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

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

Data Types: char | string

Name-Value Arguments

Specify required and optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: HullWhiteModelObj = finmodel("HullWhite",'Alpha',0.052,'Sigma',0.34)

Alpha — Mean reversion speed

numeric

Mean reversion speed, specified as the comma-separated pair consisting of 'Alpha' and a scalar numeric or timetable.

Alpha accepts a timetable, where the first column is dates and the second column is the associated Alpha value.

Data Types: double | timetable

Sigma — Volatility

numeric | timetable

Volatility, specified as the comma-separated pair consisting of 'Sigma' and a scalar numeric or timetable.

Sigma accepts a timetable, where the first column is dates and the second column is the associated Sigma value.

Data Types: double | timetable

Properties

Alpha — Mean reversion speed

numeric

Mean reversion speed, returned as a scalar numeric or timetable.

Data Types: double | timetable

Sigma — Volatility

numeric | timetable

Volatility, returned as a scalar numeric value or timetable.

Data Types: double | timetable

Examples

Use HullWhite Model and HullWhite Pricer to Price Floor Instrument

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

Create Floor Instrument Object

Use fininstrument to create a Floor instrument object.

FloorOpt = fininstrument("Floor",'Strike',0.045,'Maturity',datetime(2019,1,30),'Reset',4,'Principal',100,'Basis',1,'Name',"floor_option")

FloorOpt = 
  Floor with properties:

                      Strike: 0.0450
                    Maturity: 30-Jan-2019
                 ResetOffset: 0
                       Reset: 4
                       Basis: 1
                   Principal: 100
             ProjectionCurve: [0x0 ratecurve]
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                        Name: "floor_option"

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",'Alpha',0.032,'Sigma',0.04)

HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0320
    Sigma: 0.0400

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,9,15);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
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-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create HullWhite Pricer Object

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

outPricer = finpricer("analytic",'Model',HullWhiteModel,'DiscountCurve',myRC) 

outPricer = 
  HullWhite with properties:

    DiscountCurve: [1x1 ratecurve]
            Model: [1x1 finmodel.HullWhite]

Price Floor Instrument

Use price to compute the price for the Floor instrument.

Price = price(outPricer,FloorOpt)

Price = 
1.4917

More About

Hull-White Model

The Hull-White (HW) model is a mathematical model used to describe the behavior of interest rates over time.

The HW model uses stochastic calculus to model the evolution of interest rates as a function of time and random factors. This is a one-factor short-rate model, which means that it assumes that the short-term interest rate is determined by a single underlying factor.

The HW model assumes that the short-term interest rate follows a stochastic process. The stochastic process is typically modeled as a mean-reverting process driven by a random shock or factor.

The HW model is defined as:

$$d{r}_t=[{\theta }_t-\alpha r_t]dt+\sigma d{W}_t$$

where

r_t is the short-term interest rate at time t.

dr_t is the change in the short-term interest rate over a small time interval dt.

Θ_t is the time-varying mean reversion level of the interest rate.

α is the constant mean reversion speed.

σ is the constant volatility of the interest rate.

dW_t is a standard Wiener process or Brownian motion, representing the randomness or uncertainty in the evolution of the interest rate.

Version History

Introduced in R2020a