# mbsoas2yield

## Syntax

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

## Description

example

````[MYield,BEMBSYield] = mbsoas2yield(ZeroCurve,OAS,Settle,Maturity,IssueDate,GrossRate)` computes the mortgage and bond-equivalent yields of a pass-through security.```

example

````[MYield,BEMBSYield] = mbsoas2yield(___,CouponRate,Delay,Interpolation,PrepaySpeed,PrepayMatrix)` specifies options using one or more optional arguments in addition to the input arguments in the previous syntax. ```

## Examples

collapse all

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×3 105 × 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

collapse all

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`

Option-adjusted spreads, in basis points, specified as an `NMBS`-by-`1` vector.

Data Types: `double`

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 date, specified as an `NMBS`-by-`1` vector using serial date numbers or date character vectors.

Data Types: `double` | `char`

Issue date, specified as an `NMBS`-by-`1` vector using serial date numbers or date character vectors.

Data Types: `double` | `char`

Gross coupon rate (including fees), specified as an `NMBS`-by-`1` vector of decimal values.

Data Types: `double`

(Optional) Net coupon rate, specified as an `NMBS`-by-`1` vector of decimal values.

Data Types: `double`

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

Data Types: `double`

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

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

(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

collapse all

Yield to maturity of the mortgage-backed security, returned as a `NMBS`-by-`1` vector. This yield is compounded monthly (12 times a year).

Bond equivalent yield of the mortgage-backed security, returned as a `NMBS`-by-`1` vector. This yield is compounded semiannually (two times a year).

 PSA Uniform Practices, SF-49