CoxIngersollRoss

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

Since R2023b

Description

Create and price a Cap, Floor, Swaption, Swap, FloatBond, FixedBond, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object with a CoxIngersollRoss 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 CoxIngersollRoss model object for the Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

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

Creation

Syntax

CoxIngersollRossModelObj = finmodel(ModelType,Sigma=sigma_value,Alpha=alpha_value,Theta=theta_value)

Description

CoxIngersollRossModelObj = finmodel(ModelType,Sigma=sigma_value,Alpha=alpha_value,Theta=theta_value) creates a CoxIngersollRossModelObj model object by specifying ModelType and the required name-value arguments Sigma, Alpha, and Theta to set properties using name-value pair arguments. For example, CoxIngersollRossModelObj = finmodel("coxingersollross",Sigma=0.34,Alpha=0.052,Theta=0.017) creates a CoxIngersollRoss model object.

Input Arguments

ModelType — Model type

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

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

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.

Example: CoxIngersollRossObj = finmodel("coxingersollross",Sigma=0.034,Alpha=0.052,Theta=.017)

Sigma — Volatility

numeric

Volatility, specified as a scalar numeric.

Data Types: double

Alpha — Mean reversion speed

numeric

Mean reversion speed, specified as a scalar numeric.

Data Types: double

Theta — Mean reversion speed

numeric

Mean reversion level or long-term mean of the short rate, specified as a scalar numeric.

Data Types: double

Properties

Sigma — Volatility

numeric

Volatility, returned as a scalar numeric value.

Data Types: double

Alpha — Mean reversion speed

numeric

Mean reversion speed, returned as a scalar numeric.

Data Types: double

Theta — Mean reversion speed

numeric

Mean reversion level or long-term mean of the short rate, returned as a scalar numeric.

Data Types: double

Examples

Use CoxIngersollRoss Model and IRTree Pricer 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: [1x1 struct]
        TreeDates: [4x1 datetime]
            Model: [1x1 finmodel.CoxIngersollRoss]
    DiscountCurve: [1x1 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: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results

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

    93.459    -354.23    1384.8    -1.4211e-10

More About

Cox-Ingersoll-Ross Model

The Cox-Ingersoll-Ross (CIR) model is a mathematical model that you can use to describe the behavior of interest rates over time.

The CIR model assumes that interest rates have a long-term average or mean level to which they revert over time. This mean reversion property allows the model to capture the tendency of interest rates to move towards their long-term average.

The CIR model uses a stochastic process that describes the evolution of interest rates as a function of time and random factors and is represented as

$$d{r}_t=\alpha (b-r_t)dt+\sigma \sqrt{r_t}d{W}_t$$

where:

• rt is the instantaneous interest rate at time t.

• ɑ is the rate of mean reversion.

• b is the mean of the interest rate.

• W_t is the Wiener process, a random variable modeling the market risk factor.

• σ is the standard deviation of the interest rate, the measure of volatility.

Version History

Introduced in R2023b