oas

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

Since R2023a

Syntax

[OAS,OAD,OAC] = oas(IRTreePricer,OptionEmbeddedFixedBondInstrument,MarketPrice)

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.

Examples

Compute OAS for OptionEmbeddedFixedBond Instruments Using HullWhite Model and IRTree Pricer

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: [0x1 datetime]
                CallSchedule: [1x1 timetable]
                 PutSchedule: [0x0 timetable]
           CallExerciseStyle: "american"
            PutExerciseStyle: [0x0 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: [0x1 datetime]
                CallSchedule: [1x1 timetable]
                 PutSchedule: [0x0 timetable]
           CallExerciseStyle: "european"
            PutExerciseStyle: [0x0 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: [2x1 datetime]
                    PutDates: [0x1 datetime]
                CallSchedule: [2x1 timetable]
                 PutSchedule: [0x0 timetable]
           CallExerciseStyle: "bermudan"
            PutExerciseStyle: [0x0 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: [1x1 struct]
        TreeDates: [10x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 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

IRTreePricer — Pricer object

IRTree object

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

OptionEmbeddedFixedBondInstrument — Instrument object

OptionEmbeddedFixedBond 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

MarketPrice — Market price of OptionEmbeddedFixedBond instrument

scalar numeric | vector of numeric values

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

Data Types: double

Output Arguments

OAS — Option adjusted spread

numeric decimal

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

OAD — Option adjusted duration

numeric decimal

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

OAC — Option adjusted convexity

numeric decimal

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

More About

Option Adjusted Spread

Option adjusted spread (OAS) adjusts a bond spread for the option's value and is the standard measure for valuing and comparing bonds with different redemption structures.

OAS is a measure of yield spread that accounts for embedded call or put options in the valuation of bonds. The computation of OAS is similar to computing the bond spread, with the difference being that the cash flows are nondeterministic. In other words, the OAS computation considers the possibility of a change in the bond’s cash flows due to early redemptions. To compute an OAS, you must model the future behavior of interest rates.

In general, bonds with similar characteristics and credit risks should have the same OAS. If a bond has an OAS higher than the OAS of its peers (bond with similar characteristics and credit quality), it is considered undervalued. Conversely, a bond with a low OAS relative to its peers is considered overvalued.

Option Adjusted Duration

Option adjusted duration (OAD) accounts for the effect of the call option on the expected life of a bond.

OAD weighs the probability that the bond will be called based on the spread between its coupon rate and its yield, as well as the volatility of interest rates. Generally speaking, option adjusted duration (OAD) is longer than modified duration when a bond is priced to a call date, and shorter than modified duration when a bond is priced to maturity.

Option Adjusted Convexity

Option adjusted convexity (OAC) is a measure of a bond's convexity, which account for the convexity of options embedded within the bond.

OAC captures the curvature of the price and yield relationship observed in bonds. Low values mean the relationship is near to linearity (a change in the price leads to a proportional change in the yield). The OAC can vary from the negative to the positive, depending on the yield’s amount and the time to call or time to put. In contrast with modified convexity, OAC assumes that the cash flows of a bond change when yields change.

Version History

Introduced in R2023a