OptionEmbeddedRangeAccrualNote

OptionEmbeddedRangeAccrualNote instrument object

Since R2026a

expand all in page

Description

Create and price an OptionEmbeddedRangeAccrualNote instrument object for one or more Fixed Bond Option instruments using this workflow:

  1. Use fininstrument to create an OptionEmbeddedRangeAccrualNote instrument object for one or more Option Embedded Range Accrual Note instruments.

  2. Use finmodel to specify a HullWhite or LinearGaussian2F model for the OptionEmbeddedRangeAccrualNote instrument object.

  3. When using a HullWhite or LinearGaussian2F model, use finpricer to specify an IRMonteCarlo pricing method for one or more OptionEmbeddedRangeAccrualNote instruments.

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 models and pricing methods for an OptionEmbeddedRangeAccrualNote instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

OptionEmbeddedRangeAccrualNoteObj = fininstrument(InstrumentType,Maturity=maturity_value,ReferenceType=reference_type,ReferenceTenor=reference_tenor_value,CouponRate=couponrate_value,TargetRange=targetrange_value)
OptionEmbeddedRangeAccrualNoteObj = fininstrument(___,Name=Value)

Description

OptionEmbeddedRangeAccrualNoteObj = fininstrument(InstrumentType,Maturity=maturity_value,ReferenceType=reference_type,ReferenceTenor=reference_tenor_value,CouponRate=couponrate_value,TargetRange=targetrange_value) creates a RangeAccrualNote object for one or more Option Embedded Range Accrual Note instruments by specifying InstrumentType and sets the properties for the required name-value pair arguments Maturity, ReferenceType, ReferenceTenor, CouponRate, and TargetRange.

For more information, see More About.

example

OptionEmbeddedRangeAccrualNoteObj = fininstrument(___,Name=Value) sets optional properties using additional name-value arguments in addition to the required arguments in the previous syntax. For example, OptionEmbeddedRangeAccrualNoteObj = fininstrument("OptionEmbedded",Maturity=datetime(2026,9,15),ReferenceType="spot",ReferenceTenor=10,CouponRate=0.04,TargetRange=[100, 200],Period=2,Basis=4,Principal=500,CMSReferenceReset=4,CallSchedule=schedule,Name="OptionEmbeddedRangeAccrualNote_option") creates a OptionEmbeddedRangeAccrualNote instrument. You can specify multiple name-value pair arguments.

example

Input Arguments

expand all

Instrument type, specified as a string with the value of "OptionEmbeddedRangeAccrualNote", a character vector with the value of 'OptionEmbeddedRangeAccrualNote', an NINST-by-1 string array with values of "OptionEmbeddedRangeAccrualNote", or an NINST-by-1 cell array of character vectors with values of 'OptionEmbeddedRangeAccrualNote'.

Data Types: char | cell | string

Name-Value Arguments

expand all

Specify 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: OptionEmbeddedRangeAccrualNoteObj = fininstrument("OptionEmbedded",Maturity=datetime(2026,9,15),ReferenceType="spot",ReferenceTenor=10,CouponRate=0.04,TargetRange=[100, 200],Period=2,Basis=4,Principal=500,CMSReferenceReset=4,CallSchedule=schedule,Name="OptionEmbeddedRangeAccrualNote_option")

Required OptionEmbeddedRangeAccrualNote Name-Value Pair Arguments

expand all

OptionEmbeddedRangeAccrualNote maturity date, specified as a scalar datetime value or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

If you use date character vectors or strings, the format must be recognizable by datetime because the Maturity property is stored as a datetime.

Data Types: char | cell | string

Type of underlying reference rate, specified as a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array.

  • "cms" — Refers to the Constant Maturity Swap rate, a common choice for instruments linked to long-term interest rate expectations.

  • "spot" — Represents the spot rate, which is typically an interbank rate or an overnight rate.

In an option embedded range accrual note, the reference rate is crucial as it dictates whether the note accrues interest and the rate at which it does so. Common reference rates include:

  • Overnight Rates — Such as the Secured Overnight Financing Rate (SOFR)

  • Interbank Rates —Such as the Euro Interbank Offered Rate (EURIBOR)

  • Swap Rates — Such as the Constant Maturity Swap (CMS) rate

Data Types: char | cell | string

Tenor, in years, for the underlying reference rate, specified as a scalar numeric or an NINST-by-1 numeric array.

The underlying reference rate specific to using ReferenceType can be a Constant Maturity Swap (CMS) rate or a spot rate.

You can specify multiple tenors to create OptionEmbeddedRangeAccrualNote instruments with more than one reference rate. For instance, to create a dual CMS Range Accrual Note, specify [10,30] with ReferenceType as "cms" to use both the 10-year and 30-year CMS rates.

Data Types: double

OptionEmbeddedRangeAccrualNote coupon rate, specified as a scalar decimal annual rate or a timetable where the first column is dates and the second column is associated rates. The date indicates the last day that the coupon rate is valid.

Note

If you are creating one or more OptionEmbeddedRangeAccrualNote instruments and use a timetable, the timetable specification applies to all of the OptionEmbeddedRangeAccrualNote instruments. CouponRate does not accept an NINST-by-1 cell array of timetables as input.

Data Types: double | timetable

OptionEmbeddedRangeAccrualNote target range for the reference rate, specified as numeric vector, timetable, or function handle.

  • Numeric Vector

    When using a numeric vector for TargetRange, you define a [lowerBarrier, upperBarrier] target range (inclusive) for the reference rate. Specify this value as a 1-by-2 vector that applies to all reference rates. For example:

    • [0, 3.25/100]

    • [0, inf]

    • [-inf, 4/100]

  • Timetable Format

    For more complex range settings, a timetable can specify different ranges for distinct periods. When you use a timetable for the TargetRange, the columns represent the corresponding [lowerBarrier, upperBarrier] target ranges for each reference rate. Each date in the timetable indicates the last day that the target range is valid. The dimension in the timetable representing the reference rates must be arranged according to the tenors outlined in ReferenceTenor.

    For more complex range settings, a timetable can specify different ranges for distinct periods. For example,

           Time             Var1     
    ___________    ______________

    01-Jan-2021       0    0.0325
    01-Jan-2025       0    0.0375
    01-Jan-2026       0.01 Inf
    where

    • Year 1 is 0.00% – 3.25%.

    • Year 2 to year 5 is 0.00% – 3.75%.

    • Year 6 is >= 0.01%.

    For an example of this TargetRange when using a timetable format, see Price OptionEmbeddedRangeAccrualNote Instrument with Multiple Target Ranges Using HullWhite Model and IRMonteCarlo Pricer.

    Note

    If you are creating one or more OptionEmbeddedRangeAccrualNote instruments and use a timetable, the timetable specification applies to all of the OptionEmbeddedRangeAccrualNote instruments. TargetRange does not accept an NINST-by-1 cell array of timetables as input.

  • Function Handle

    If an OptionEmbeddedRangeAccrualNote instrument involves using multiple reference rates with different ranges for each reference rate, you can specify TargetRange as a function handle. By using a function handle, you can dynamically define and manage complex relationships and conditions, ensuring that each reference rate is accurately evaluated against its corresponding range.

    When using a function handle for TargetRange, the function should accept input parameters in the form (refRates, rateDates), where refRates is an NRateDates-by-NTrials-by-NRefRates 3-D matrix containing reference rates. Each page (third dimension) of this matrix corresponds to a specific tenor as defined in the ReferenceTenor parameter. The rateDates is a vector containing the dates associated with the reference rates within a single coupon period. The function handle must return a fractional value between 0 and 1 that represents how interest accrues for each day the reference rates remain within the specified range. For instance, the function handle fractional return value can be the ratio of the number of days the rates remain within the range to the total number of coupon dates in that period.

    For an example of TargetRange using a function handle, see Price OptionEmbeddedRangeAccrualNote Instrument with a Custom Target Range Using HullWhite Model and IRMonteCarlo Pricer.

Data Types: double | timetable | function_handle

Optional OptionEmbeddedRangeAccrualNote Name-Value Arguments

expand all

Frequency of actual coupon payments per year, specified as a scalar integer or an NINST-by-1 vector of integers. Values for Period are 1, 2, 3, 4, 6, or 12.

Data Types: double

Day count basis, specified as a scalar integer or an NINST-by-1 vector of integers using the following values:

  • 0 — actual/actual

  • 1 — 30/360 (SIA)

  • 2 — actual/360

  • 3 — actual/365

  • 4 — 30/360 (PSA)

  • 5 — 30/360 (ISDA)

  • 6 — 30/360 (European)

  • 7 — actual/365 (Japanese)

  • 8 — actual/actual (ICMA)

  • 9 — actual/360 (ICMA)

  • 10 — actual/365 (ICMA)

  • 11 — 30/360E (ICMA)

  • 12 — actual/365 (ISDA)

  • 13 — BUS/252

For more information, see Basis.

Data Types: double

Principal amount, specified as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Frequency of actual payments per year for underlying reference swap of CMS, specified as a scalar or an NINST-by-1 vector.

Note

CMSReferenceReset applies only when you specify ReferenceType as "cms".

Data Types: double

Call schedule for OptionEmbeddedRangeAccrualNote, specified as a timetable of call dates and strikes.

When you specify CallSchedule, the call dates are a subset of the coupon payment dates. The Maturity date is automatically excluded from the exercise dates, even if included in the CallSchedule.

If you use a date character vector or date string for the dates in this timetable, the format must be recognizable by datetime because the CallSchedule property is stored as a datetime.

Data Types: timetable

Flag indicating whether the cash flow is adjusted by day count convention, specified as a scalar logical or an NINST-by-1 vector of logicals with values of true or false.

Data Types: logical

Business day conventions for cash flow dates, specified as a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array. The selection for business day convention determines how nonbusiness days are treated. Nonbusiness days are defined as weekends plus any other date that businesses are not open (for example, statutory holidays). Values are:

  • "actual" — Nonbusiness days are effectively ignored. Cash flows that fall on nonbusiness days are assumed to be distributed on the actual date.

  • "follow" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day.

  • "modifiedfollow" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day. However, if the following business day is in a different month, the previous business day is adopted instead.

  • "previous" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day.

  • "modifiedprevious" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day. However, if the previous business day is in a different month, the following business day is adopted instead.

Data Types: char | cell | string

Holidays used in computing business days, specified as an NINST-by-1 vector of a datetime array, string array, or date character vectors. For example:

H = holidays(datetime('today'),datetime(2025,12,15));
OptionEmbeddedRangeAccuralNoteObj = fininstrument("OptionEmbeddedRangeAccuralNote",Maturity=datetime(2026,9,15),ReferenceType="spot", ...
ReferenceTenor=10,CouponRate=0.04,TargetRange=[100, 200],Period=2,Basis=4,Principal=500,CMSReferenceReset=4, ...
CallSchedule=schedule,Holidays=H)

Data Types: char | datetime | string

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month with 30 or fewer days, specified as a scalar logical value or an NINST-by-1 vector of logicals with values of true or false.

  • If you set EndMonthRule to false, the software ignores the rule, meaning that a payment date is always the same numerical day of the month.

  • If you set EndMonthRule to true, the software applies the rule, meaning that a payment date is always the last actual day of the month.

Data Types: logical

Forward starting date of payments, specified as a scalar character vector, string, or datetime or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

If you use date character vectors or strings, the format must be recognizable by datetime because the StartDate property is stored as a datetime.

Data Types: char | datetime | string

User-defined name for one of more instruments, specified as a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array.

Data Types: char | cell | string

Output Arguments

expand all

Option embedded range accrual note instrument, returned as an OptionEmbeddedRangeAccrualNote object.

Properties

expand all

OptionEmbeddedRangeAccrualNote maturity date, returned as a scalar datetime or an NINST-by-1 vector of datetimes.

Data Types: datetime

Type of underlying reference rate, returned as a scalar string or an NINST-by-1 string array.

Data Types: string

Tenor, in years, for underlying reference rate, returned as a scalar numeric or an NINST-by-1 vector.

Data Types: double

OptionEmbeddedRangeAccrualNote coupon annual rate, returned as a scalar decimal or a timetable.

Data Types: double | timetable

OptionEmbeddedRangeAccrualNote target range ([lowerBarrier,upperBarrier]) for the reference rate, returned as a scalar numeric vector, timetable, or a function handle.

Data Types: double | timetable | function_handle

Frequency of payments per year, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

Day count basis, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

Principal amount, returned as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Frequency of actual payments per year for underlying reference swap of CMS, returned as a scalar or an NINST-by-1 vector.

Note

CMSReferenceReset applies only when you specify ReferenceType as "cms".

Data Types: double

Call schedule for OptionEmbeddedRangeAccrualNote, returned as a timetable of call dates and strikes for the option embedded range accrual note.

Data Types: timetable

Flag indicating whether cash flow adjusts for day count convention, returned as a scalar logical or an NINST-by-1 vector of logicals with values of true or false.

Data Types: logical

Business day conventions, returned as a scalar string or an NINST-by-1 string array.

Data Types: string

Holidays used in computing business days, returned as an NINST-by-1 vector of datetimes.

Data Types: datetime

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month having 30 or fewer days, returned as a scalar logical or an NINST-by-1 vector of logical values.

Data Types: logical

Forward starting date of payments, returned as a scalar datetime or an NINST-by-1 vector of datetimes.

Data Types: datetime

User-defined name for the instrument, returned as a scalar string or an NINST-by-1 string array.

Data Types: string

Examples

collapse all

Open Live Script

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

Create OptionEmbeddedRangeAccrualNote Instrument Object

Use fininstrument to create an OptionEmbeddedRangeAccrualNote instrument object. Use the CallSchedule name-value argument to specify the call schedule.

Maturity = datetime(2026,9,15);

Strike = [1000; 1000 ];
ExerciseDates = [datetime(2025,12,1); datetime(2026,12,1)];
CallSchedule =  timetable(ExerciseDates,Strike,'VariableNames',{'Strike Schedule'}); 

OptionEmbeddedRangeAccrualNoteInstrument = fininstrument("OptionEmbeddedRangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=10,CouponRate=0.4, ...
    TargetRange=[0,3.25/100],Principal=1000,CallSchedule=CallSchedule,Name="optimembeddedrangeaccrualnote_instrument")
OptionEmbeddedRangeAccrualNoteInstrument = 
  OptionEmbeddedRangeAccrualNote with properties:

               ReferenceType: "cms"
                      Period: 2
                       Basis: 0
                   Principal: 1000
           CMSReferenceReset: 2
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
              ReferenceTenor: 10
                    Maturity: 15-Sep-2026
                  CouponRate: 0.4000
                 TargetRange: [0 0.0325]
                CallSchedule: [1×1 timetable]
                   StartDate: NaT
                        Name: "optimembeddedrangeaccrualnote_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2024,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:3)]';
ZeroRates = [0.0055 0.0061 0.0073]';
ZeroDates = Settle + ZeroTimes;

myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

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

Create a HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",Alpha=0.02,Sigma=0.03)
HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0200
    Sigma: 0.0300

Create IRMonteCarlo Pricer Object

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

SimulationDates = Settle:caldays(1):Maturity;
SimulationDates = busdate(SimulationDates,"follow",OptionEmbeddedRangeAccrualNoteInstrument.Holidays);
outPricer = finpricer("IRMonteCarlo",Model=HullWhiteModel,DiscountCurve=myRC,SimulationDates=SimulationDates)
outPricer = 
  HWMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [16-Sep-2024    17-Sep-2024    18-Sep-2024    19-Sep-2024    20-Sep-2024    23-Sep-2024    24-Sep-2024    25-Sep-2024    26-Sep-2024    27-Sep-2024    30-Sep-2024    01-Oct-2024    02-Oct-2024    03-Oct-2024    …    ] (1×523 datetime)
              Model: [1×1 finmodel.HullWhite]

Price OptionEmbeddedRangeAccrualNote Instrument

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

[Price,outPR] = price(outPricer,OptionEmbeddedRangeAccrualNoteInstrument,"all")
Price = 
1.2799e+03

outPR = 
  priceresult with properties:

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


outPR.Results
ans=1×4 table
    Price     Delta       Gamma        Vega  
    ______    ______    __________    _______

    1279.9    6170.9    8.3019e+06    -1951.4
Open Live Script

This example shows the workflow to price an OptionEmbeddedRangeAccrualNote instrument with multiple target ranges (using TargetRange) and a CallSchedule when you use a HullWhite model and an IRMonteCarlo pricing method.

Create OptionEmbeddedRangeAccrualNote Instrument Object

Use fininstrument to create an OptionEmbeddedRangeAccrualNote instrument object with multiple target ranges by specifying the TargetRange name-value argument with a timetable. In addition, this OptionEmbeddedRangeAccrualNote instrument also specifies a CallSchedule using a timetable. 

Maturity = datetime(2026,9,15);

Strike = [1000; 1000 ; 1000];
ExerciseDates = [datetime(2021,12,1); datetime(2025,12,1); datetime(2026,12,1)];
CallSchedule =  timetable(ExerciseDates,Strike,'VariableNames',{'Strike Schedule'}); 

OptionEmbeddedRangeAccrualNoteInstrument = fininstrument("OptionEmbeddedRangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=10,CouponRate=0.4, ...
    TargetRange=timetable([datetime(2021,10,1);datetime(2025,10,1);datetime(2026,10,1)],[0,0.0325;0,0.0375;0.01,inf]),Principal=1000,CallSchedule=CallSchedule,Name="optionembeddedrangeaccrualnote_instrument")
OptionEmbeddedRangeAccrualNoteInstrument = 
  OptionEmbeddedRangeAccrualNote with properties:

               ReferenceType: "cms"
                      Period: 2
                       Basis: 0
                   Principal: 1000
           CMSReferenceReset: 2
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
              ReferenceTenor: 10
                    Maturity: 15-Sep-2026
                  CouponRate: 0.4000
                 TargetRange: [3×1 timetable]
                CallSchedule: [2×1 timetable]
                   StartDate: NaT
                        Name: "optionembeddedrangeaccrualnote_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2024,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:3)]';
ZeroRates = [0.0055 0.0061 0.0073]';
ZeroDates = Settle + ZeroTimes;

myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

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

Create a HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",Alpha=0.02,Sigma=0.03)
HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0200
    Sigma: 0.0300

Create IRMonteCarlo Pricer Object

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

SimulationDates = Settle:caldays(1):Maturity;
SimulationDates = busdate(SimulationDates,"follow",OptionEmbeddedRangeAccrualNoteInstrument.Holidays);
outPricer = finpricer("IRMonteCarlo",Model=HullWhiteModel,DiscountCurve=myRC,SimulationDates=SimulationDates)
outPricer = 
  HWMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [16-Sep-2024    17-Sep-2024    18-Sep-2024    19-Sep-2024    20-Sep-2024    23-Sep-2024    24-Sep-2024    25-Sep-2024    26-Sep-2024    27-Sep-2024    30-Sep-2024    01-Oct-2024    02-Oct-2024    03-Oct-2024    …    ] (1×523 datetime)
              Model: [1×1 finmodel.HullWhite]

Price OptionEmbeddedRangeAccrualNote Instrument

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

[Price,outPR] = price(outPricer,OptionEmbeddedRangeAccrualNoteInstrument,"all")
Price = 
1.1508e+03

outPR = 
  priceresult with properties:

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


outPR.Results
ans=1×4 table
    Price     Delta       Gamma        Vega  
    ______    ______    __________    _______

    1150.8    4230.6    2.1628e+06    -1019.9
Open Live Script

This example shows the workflow to price an OptionEmbeddedRangeAccrualNote instrument with a custom TargetRange (specified using a function handle) and uses a HullWhite model and an IRMonteCarlo pricing method.

Create OptionEmbeddedRangeAccrualNote Instrument Object

Use fininstrument to create an OptionEmbeddedRangeAccrualNote instrument object. The TargetRange name-value argument specifies a function handle for checkValidCoupon. This function handle supports a custom calculation for a triple CMS OptionEmbeddedRangeAccrualNote instrument. This OptionEmbeddedRangeAccrualNote uses "cms" as the ReferenceType with tenors [5, 10, 20]. The Period is set to 12, meaning each coupon period spans one month. Simulated reference rates are collected for each coupon period by the checkValidCoupon function. In addition, this OptionEmbeddedRangeAccrualNote instrument also specifies a CallSchedule using a timetable.

Maturity = datetime(2026,1,1);

Strike = [1000; 1000 ; 1000];
ExerciseDates = [datetime(2021,12,1); datetime(2025,12,1); datetime(2026,12,1)];
CallSchedule =  timetable(ExerciseDates,Strike,'VariableNames',{'Strike Schedule'});

OptionEmbeddedRangeAccrualNoteInstrument = fininstrument("OptionEmbeddedRangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=[5,10,20],Period=12,CouponRate=0.4, ...
    TargetRange=@checkValidCoupon,Principal=1000,CallSchedule=CallSchedule,Name="optionembeddedrangeaccrualnote_instrument")
OptionEmbeddedRangeAccrualNoteInstrument = 
  OptionEmbeddedRangeAccrualNote with properties:

               ReferenceType: "cms"
                      Period: 12
                       Basis: 0
                   Principal: 1000
           CMSReferenceReset: 2
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
              ReferenceTenor: [5 10 20]
                    Maturity: 01-Jan-2026
                  CouponRate: 0.4000
                 TargetRange: @checkValidCoupon
                CallSchedule: [2×1 timetable]
                   StartDate: NaT
                        Name: "optionembeddedrangeaccrualnote_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2024,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:3)]';
ZeroRates = [0.0055 0.0061 0.0073]';
ZeroDates = Settle + ZeroTimes;

myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

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

Create a HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",Alpha=0.02,Sigma=0.03)
HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0200
    Sigma: 0.0300

Create IRMonteCarlo Pricer Object

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

SimulationDates = Settle:caldays(1):Maturity;
SimulationDates = busdate(SimulationDates,"follow",OptionEmbeddedRangeAccrualNoteInstrument.Holidays);
outPricer = finpricer("IRMonteCarlo",Model=HullWhiteModel,DiscountCurve=myRC,SimulationDates=SimulationDates)
outPricer = 
  HWMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [16-Sep-2024    17-Sep-2024    18-Sep-2024    19-Sep-2024    20-Sep-2024    23-Sep-2024    24-Sep-2024    25-Sep-2024    26-Sep-2024    27-Sep-2024    30-Sep-2024    01-Oct-2024    02-Oct-2024    03-Oct-2024    …    ] (1×340 datetime)
              Model: [1×1 finmodel.HullWhite]

Price OptionEmbeddedRangeAccrualNote Instrument

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

[Price,outPR] = price(outPricer,OptionEmbeddedRangeAccrualNoteInstrument,"all")
Price = 
1.0305e+03

outPR = 
  priceresult with properties:

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


outPR.Results
ans=1×4 table
    Price     Delta       Gamma        Vega  
    ______    ______    __________    _______

    1030.5    1093.4    -3.888e+06    -499.88

Local Function

function ratio = checkValidCoupon(refRates, rateDates)
%%%%%%%%%% Information %%%%%%%%%%%%%%
% refRates: 3D matrix, NumSimulateDays-by-NumTrials-by-NumRefRates
% rateDates: vector, NumSimulateDays

% Reference rates are ordered as per ReferenceTenor and cover one coupon period.
% refRate1 = refRates(:,:,1): 5-year CMS for the period in rateDates
% refRate2 = refRates(:,:,2): 10-year CMS for the period in rateDates
% refRate3 = refRates(:,:,3): 20-year CMS for the period in rateDates

% Output ratio must be a 1 x NumTrials vector
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Define target range based on strategy.
Settle = datetime(2021,1,1);
Maturity = datetime(2026,1,1);
targetDates = Settle+calyears(1):calyears(1):Maturity;
targetRates = [.0325 .035 .0375 .04 .0425];

UpperRate = targetRates(find(rateDates(end) <= targetDates,1));
LowerRate = 0;

refRate1 = refRates(:,:,1);
refRate2 = refRates(:,:,2);
refRate3 = refRates(:,:,3);

% Calculate valid days based on custom logic.
validDays = sum((refRate3-refRate2) >= UpperRate | refRate1 >= LowerRate & refRate1 <= UpperRate,1); % 1 x NumTrials vector
totalDays = numel(rateDates);

% Compute accrued interest fraction based on custom logic.
AccruedCouponFraction = (2 * validDays - totalDays) / totalDays;

% Output ratio for pricer to compute accrued interest.
% AccruedCouponForThisPeriod = ratio * CouponRate*Principal/Period;
ratio = AccruedCouponFraction; % 1 x NumTrials vector

end
Open Live Script

This example shows the workflow to price an OptionEmbeddedRangeAccrualNote instrument object for three OptionEmbeddedRangeAccrualNote instruments when you use a HullWhite model and an IRMonteCarlo pricing method.

Create OptionEmbeddedRangeAccrualNote Instrument Object

Use fininstrument to create an OptionEmbeddedRangeAccrualNote instrument object for three OptionEmbeddedRangeAccrualNote instruments. 

Maturity = datetime([2026,9,15; 2027,10,15 ; 2028,11,15]);

Strike = [1000; 1000; 1000 ];
ExerciseDates = [datetime(2025,12,1); datetime(2026,12,1); datetime(2026,12,1)];
CallSchedule =  timetable(ExerciseDates,Strike,'VariableNames',{'Strike Schedule'});

OptionEmbeddedRangeAccrualNoteInstrument = fininstrument("OptionEmbeddedRangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=10,CouponRate=0.4, ...
    TargetRange=[0,3.25/100],Principal=1000,CallSchedule=CallSchedule,Name="optionembedded_rangeaccrualnote_instrument")
OptionEmbeddedRangeAccrualNoteInstrument=3×1 OptionEmbeddedRangeAccrualNote array with properties:
    ReferenceType
    Period
    Basis
    Principal
    CMSReferenceReset
    DaycountAdjustedCashFlow
    BusinessDayConvention
    Holidays
    EndMonthRule
    ReferenceTenor
    Maturity
    CouponRate
    TargetRange
    CallSchedule
    StartDate
    Name

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2024,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:3)]';
ZeroRates = [0.0055 0.0061 0.0073]';
ZeroDates = Settle + ZeroTimes;

myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

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

Create a HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",Alpha=0.02,Sigma=0.03)
HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0200
    Sigma: 0.0300

Create IRMonteCarlo Pricer Object

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

SimulationDates = Settle:caldays(1):Maturity(end);
SimulationDates = busdate(SimulationDates,"follow");
outPricer = finpricer("IRMonteCarlo",Model=HullWhiteModel,DiscountCurve=myRC,SimulationDates=SimulationDates)
outPricer = 
  HWMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [16-Sep-2024    17-Sep-2024    18-Sep-2024    19-Sep-2024    20-Sep-2024    23-Sep-2024    24-Sep-2024    25-Sep-2024    26-Sep-2024    27-Sep-2024    30-Sep-2024    01-Oct-2024    02-Oct-2024    …    ] (1×1049 datetime)
              Model: [1×1 finmodel.HullWhite]

Price OptionEmbeddedRangeAccrualNote Instruments

Use price to compute the price and sensitivities for the three OptionEmbeddedRangeAccrualNote instruments.

[Price,outPR] = price(outPricer,OptionEmbeddedRangeAccrualNoteInstrument,"all")
Price = 3×1
103 ×

    1.2778
    1.4474
    1.4255


outPR=3×1 priceresult array with properties:
    Results
    PricerData


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

    1277.8    6384.4    -5.8772e+05    -2057.4


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

    1447.4    10450    8.0477e+06    -3696.6


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

    1425.5    10347    -1.2139e+07    -4281.8
Open Live Script

This example shows the workflow to price a OptionEmbeddedangeAccrualNote instrument when you use a LinearGaussian2F model and an IRMonteCarlo pricing method.

Create OptionEmbeddedRangeAccrualNote Instrument Object

Use fininstrument to create a OptionEmbeddedRangeAccrualNote instrument object. 

Maturity = datetime(2026,9,15);

Strike = [1000; 1000 ];
ExerciseDates = [datetime(2025,12,1); datetime(2026,12,1)];
CallSchedule =  timetable(ExerciseDates,Strike,'VariableNames',{'Strike Schedule'});

OptionEmbeddedRangeAccrualNoteInstrument = fininstrument("OptionEmbeddedRangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=10,CouponRate=0.4, ...
    TargetRange=[0,3.25/100],Principal=1000,CallSchedule=CallSchedule,Name="optionembedded_rangeaccrualnote_instrument")
OptionEmbeddedRangeAccrualNoteInstrument = 
  OptionEmbeddedRangeAccrualNote with properties:

               ReferenceType: "cms"
                      Period: 2
                       Basis: 0
                   Principal: 1000
           CMSReferenceReset: 2
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
              ReferenceTenor: 10
                    Maturity: 15-Sep-2026
                  CouponRate: 0.4000
                 TargetRange: [0 0.0325]
                CallSchedule: [1×1 timetable]
                   StartDate: NaT
                        Name: "optionembedded_rangeaccrualnote_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2024,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:3)]';
ZeroRates = [0.0055 0.0061 0.0073]';
ZeroDates = Settle + ZeroTimes;

myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

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

Create LinearGaussian2F Model Object

Use finmodel to create a LinearGaussian2F model object.

LinearGaussian2FModel = finmodel("LinearGaussian2F",Alpha1=0.07,Sigma1=0.01,Alpha2=0.5,Sigma2=0.006,Correlation=-0.7)
LinearGaussian2FModel = 
  LinearGaussian2F with properties:

         Alpha1: 0.0700
         Sigma1: 0.0100
         Alpha2: 0.5000
         Sigma2: 0.0060
    Correlation: -0.7000

Create IRMonteCarlo Pricer Object

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

SimulationDates = Settle:caldays(1):Maturity;
SimulationDates = busdate(SimulationDates,"follow",OptionEmbeddedRangeAccrualNoteInstrument.Holidays);
outPricer = finpricer("IRMonteCarlo",Model=LinearGaussian2FModel,DiscountCurve=myRC,SimulationDates=SimulationDates,NumTrials=1e3)
outPricer = 
  G2PPMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [16-Sep-2024    17-Sep-2024    18-Sep-2024    19-Sep-2024    20-Sep-2024    23-Sep-2024    24-Sep-2024    25-Sep-2024    26-Sep-2024    27-Sep-2024    30-Sep-2024    01-Oct-2024    02-Oct-2024    03-Oct-2024    …    ] (1×523 datetime)
              Model: [1×1 finmodel.LinearGaussian2F]

Price OptionEmbeddedRangeAccrualNote Instrument

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

[Price,outPR] = price(outPricer,OptionEmbeddedRangeAccrualNoteInstrument,"all")
Price = 
1.3754e+03

outPR = 
  priceresult with properties:

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


outPR.Results
ans=1×4 table
    Price     Delta        Gamma              Vega       
    ______    ______    ___________    __________________

    1375.4    5374.4    -2.8115e+06    -5334.9     5964.5

More About

expand all

Version History

Introduced in R2026a

See Also

Functions

Topics