# oas

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

Since R2023a

## Syntax

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

## Description

example

````[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

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: [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

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.

collapse all

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