Main Content

oas

Compute option adjusted spread for OptionEmbeddedFixedBond instrument using interest-rate tree

Since R2023a

Description

[OAS,OAD,OAC] = oas(IRTreePricer,OptionEmbeddedFixedBondInstrument,MarketPrice) computes the option adjusted spread (OAS), option adjusted duration (OAD), and option adjusted convexity (OAC) of an OptionEmbeddedFixedBond instrument using a HullWhite, BlackKarasinski, or BlackDermanToy model with an IRTree pricer.

example

Examples

collapse all

This example shows how to compute the option adjusted spread (OAS) with American, European, and Bermudan exercise styles for three callable OptionEmbeddedFixedBond instruments. For this example, 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 OptionEmbeddedFixedBond Instrument Objects

Use fininstrument to create two OptionEmbeddedFixedBond instrument objects with the three different exercise styles.

Maturity = datetime(2024,1,1);

% Option embedded bond (American callable bond)
Strike = 100;
ExerciseDates = datetime(2024,1,1);
CallSchedule =  timetable(ExerciseDates,Strike,VariableNames={'Strike Schedule'}); 
Period = 1;

CallableBondAmerican = fininstrument("OptionEmbeddedFixedBond",Maturity=Maturity, ...
                              CouponRate=0.025,Period=Period, ...
                              CallSchedule=CallSchedule,CallExerciseStyle="american")
CallableBondAmerican = 
  OptionEmbeddedFixedBond 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
                   CallDates: 01-Jan-2024
                    PutDates: [0×1 datetime]
                CallSchedule: [1×1 timetable]
                 PutSchedule: [0×0 timetable]
           CallExerciseStyle: "american"
            PutExerciseStyle: [0×0 string]
                        Name: ""

% Option embedded bond (European callable bond)
Strike = 100;
ExerciseDates = datetime(2024,1,1);
CallSchedule =  timetable(ExerciseDates,Strike,VariableNames={'Strike Schedule'}); 
Period = 1;

CallableBondEuropean = fininstrument("OptionEmbeddedFixedBond",Maturity=Maturity,...
                              CouponRate=0.025,Period=Period, ...
                              CallSchedule=CallSchedule)                          
CallableBondEuropean = 
  OptionEmbeddedFixedBond 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
                   CallDates: 01-Jan-2024
                    PutDates: [0×1 datetime]
                CallSchedule: [1×1 timetable]
                 PutSchedule: [0×0 timetable]
           CallExerciseStyle: "european"
            PutExerciseStyle: [0×0 string]
                        Name: ""

% Option embedded bond (Bermudan callable bond)
Strike = [100; 100];
ExerciseDates = [datetime(2020,1,1); datetime(2024,1,1)];
Period = 1;
CallSchedule =  timetable(ExerciseDates,Strike,VariableNames={'Strike Schedule'}); 

CallableBondBermudan = fininstrument("OptionEmbeddedFixedBond",Maturity=Maturity, ...
                              CouponRate=0.025,Period=Period, ...
                              CallSchedule=CallSchedule,CallExerciseStyle="bermudan")
CallableBondBermudan = 
  OptionEmbeddedFixedBond 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
                   CallDates: [2×1 datetime]
                    PutDates: [0×1 datetime]
                CallSchedule: [2×1 timetable]
                 PutSchedule: [0×0 timetable]
           CallExerciseStyle: "bermudan"
            PutExerciseStyle: [0×0 string]
                        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 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]

Compute OAS for OptionEmbeddedFixedBond Instruments

Use oas to compute the OAS, OAD, and OAC for the three OptionEmbeddedFixedBond instruments.

MarketPriceAmerican = 98;
MarketPrice = 105.25;

[OAS,OAD,OAC] = oas(HWTreePricer,CallableBondAmerican,MarketPriceAmerican)
OAS = 
0.0139
OAD = 
3.9445
OAC = 
11.7023
[OAS,OAD,OAC] = oas(HWTreePricer,CallableBondEuropean,MarketPrice)
OAS = 
0.0041
OAD = 
5.5673
OAC = 
18.7972
[OAS,OAD,OAC] = oas(HWTreePricer,CallableBondBermudan,MarketPrice)
OAS = 
-0.0072
OAD = 
2.0486
OAC = 
3.2698

Input Arguments

collapse all

Pricer object, specified as a scalar IRTree pricer object. Use finpricer to create the IRTree pricer object.

Note

The IRTree pricer must use a HullWhite, BlackKarasinski, or BlackDermanToy model.

Data Types: object

OptionEmbeddedFixedBond instrument object, specified as scalar or a vector of previously created instrument objects. Create the instrument objects using fininstrument and OptionEmbeddedFixedBond.

Data Types: object

Market price of OptionEmbeddedFixedBond instrument, specified as a scalar numeric or N-by-1 vector of numeric values.

Data Types: double

Output Arguments

collapse all

Option adjusted spread (OAS), returned as a numeric decimal value.

Option adjusted duration (OAD), returned as a numeric decimal value.

Option adjusted convexity (OAC), returned as a numeric decimal value.

More About

collapse all

Version History

Introduced in R2023a