# mbsoas2yield

Yield given option-adjusted spread

## Syntax

## Description

`[`

specifies options using one or more optional arguments in addition to the input
arguments in the previous syntax. `MYield`

,`BEMBSYield`

] = mbsoas2yield(___,`CouponRate`

,`Delay`

,`Interpolation`

,`PrepaySpeed`

,`PrepayMatrix`

)

## Examples

### Compute the Theoretical Yield to Maturity of a Mortgage Pool

Given an option-adjusted spread, a spot curve, and a prepayment assumption, compute the theoretical yield to maturity of a mortgage pool. First, create the bonds matrix:

Bonds = [datenum('11/21/2002') 0 100 0 2 1; datenum('02/20/2003') 0 100 0 2 1; datenum('07/31/2004') 0.03 100 2 3 1; datenum('08/15/2007') 0.035 100 2 3 1; datenum('08/15/2012') 0.04875 100 2 3 1; datenum('02/15/2031') 0.05375 100 2 3 1];

Choose a settlement date.

`Settle = datenum('20-Aug-2002');`

Assume the following clean prices for the bonds:

Prices = [ 98.97467; 98.58044; 100.10534; 98.18054; 101.38136; 99.25411];

Use the following formula to compute spot compounding for the bonds:

SpotCompounding = 2*ones(size(Prices));

Compute the zero curve.

[ZeroRatesP, CurveDatesP] = zbtprice(Bonds, Prices, Settle); ZeroCurve = [CurveDatesP, ZeroRatesP, SpotCompounding]

ZeroCurve =6×310^{5}× 7.3154 0.0000 0.0000 7.3163 0.0000 0.0000 7.3216 0.0000 0.0000 7.3327 0.0000 0.0000 7.3510 0.0000 0.0000 7.4185 0.0000 0.0000

Assign the following parameters:

OAS = [26.0502; 28.6348; 31.2222]; Maturity = datenum('02-Jan-2030'); IssueDate = datenum('02-Jan-2000'); GrossRate = 0.08125; CouponRate = 0.075; Delay = 14; Interpolation = 1; PrepaySpeed = [0 50 100];

Compute the mortgage yield and bond equivalent mortgage yield.

[MYield BEMBSYield] = mbsoas2yield(ZeroCurve, OAS, Settle, ... Maturity, IssueDate, GrossRate, CouponRate, Delay, ... Interpolation, PrepaySpeed)

`MYield = `*3×1*
0.0527
0.0513
0.0499

`BEMBSYield = `*3×1*
0.0533
0.0518
0.0504

## Input Arguments

`ZeroCurve`

— Zero curve

matrix

Zero curve, specified as a three-column matrix, where:

Column 1 is dates using serial date numbers.

Column 2 is spot rates with maturities corresponding to the dates in Column 1, in decimal (for example, 0.075).

Column 3 is the compounding value of the rates in Column 2. (This is the agency spot rate on the settlement date.) Allowable compounding values are:

`1`

(annual),`2`

(semiannual,`3`

(three times per year),`4`

(quarterly),`6`

(bimonthly),`12`

(monthly), and`-1`

(continuous).

For example:

[datenum('11/21/2002') 0 100 0 2 1; datenum('02/20/2003') 0 100 0 2 1; datenum('07/31/2004') 0.03 100 2 3 1; datenum('08/15/2007') 0.035 100 2 3 1; datenum('08/15/2012') 0.04875 100 2 3 1; datenum('02/15/2031') 0.05375 100 2 3 1];

**Data Types: **`double`

| `cell`

`OAS`

— Option-adjusted spreads

vector

Option-adjusted spreads, in basis points, specified as an
`NMBS`

-by-`1`

vector.

**Data Types: **`double`

`Settle`

— Settlement date

serial date number | date character vector

Settlement date, specified as an
`NMBS`

-by-`1`

vector using serial date
numbers or date character vectors. `Settle`

must be earlier
than `Maturity`

.

**Data Types: **`double`

| `char`

`Maturity`

— Maturity date

serial date number | date character vector

Maturity date, specified as an
`NMBS`

-by-`1`

vector using serial date
numbers or date character vectors.

**Data Types: **`double`

| `char`

`IssueDate`

— Issue date

serial date number | date character vector

Issue date, specified as an
`NMBS`

-by-`1`

vector using serial date
numbers or date character vectors.

**Data Types: **`double`

| `char`

`GrossRate`

— Gross coupon rate (including fees)

vector of decimal values

Gross coupon rate (including fees), specified as an
`NMBS`

-by-`1`

vector of decimal
values.

**Data Types: **`double`

`CouponRate`

— Net coupon rate

`GrossRate`

(default) | vector of decimal values

(Optional) Net coupon rate, specified as an
`NMBS`

-by-`1`

vector of decimal
values.

**Data Types: **`double`

`Delay`

— Delay (in days) between payment from homeowner and receipt by bondholder

`0`

(no delay between payment and
receipt) (default) | vector

(Optional) Delay (in days) between payment from homeowner and receipt by
bondholder, specified as an `NMBS`

-by-`1`

vector.

**Data Types: **`double`

`Interpolation`

— Interpolation method to compute the corresponding spot rates for the bond's cash flow

`1`

(linear) (default) | vector

(Optional) Interpolation method to compute the corresponding spot rates
for the bond's cash flow, specified as an
`NMBS`

-by-`1`

vector. Available
methods are (`0`

) nearest, (`1`

) linear,
and (`2`

) cubic spline. For more information on the
supported interpolation methods, see `interp1`

.

**Data Types: **`double`

`PrepaySpeed`

— Speed relative to PSA standard

`0`

(no prepayment) (default) | vector

(Optional) Speed relative to PSA standard, specified as an
`NMBS`

-by-`1`

vector. The PSA standard
is `100`

.

**Note**

Set the `PrepaySpeed`

to `[]`

if
you input a customized `PrepayMatrix`

.

**Data Types: **`double`

`PrepayMatrix`

— Customized prepayment vector

matrix

(Optional) Customized prepayment vector, specified as a
`NaN`

-padded matrix of size
`max(TermRemaining)`

-by-`NMBS`

. Each
column corresponds to each mortgage-backed security, and each row
corresponds to each month after settlement.

**Note**

Use `PrepayMatrix`

only when
`PrepaySpeed`

is unspecified.

**Data Types: **`double`

## Output Arguments

`MYield`

— Yield to maturity of the mortgage-backed security

vector

Yield to maturity of the mortgage-backed security, returned as a
`NMBS`

-by-`1`

vector. This yield is
compounded monthly (12 times a year).

`BEMBSYield`

— Bond equivalent yield of the mortgage-backed security

vector

Bond equivalent yield of the mortgage-backed security, returned as a
`NMBS`

-by-`1`

vector. This yield is
compounded semiannually (two times a year).

## References

[1] *PSA Uniform
Practices*, SF-49

## Version History

**Introduced before R2006a**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)