mbsoas2yield

Yield given option-adjusted spread

Syntax

[MYield,BEMBSYield] = mbsoas2yield(ZeroCurve,OAS,Settle,Maturity,IssueDate,GrossRate)

[MYield,BEMBSYield] = mbsoas2yield(___,CouponRate,Delay,Interpolation,PrepaySpeed,PrepayMatrix)

Description

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

[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

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

ZeroCurve — Zero curve

matrix

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

• Column 1 is 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('1-Jan-2003')  0.0154  12;
 datenum('1-Jan-2004')  0.0250  12;
 ......
 datenum('1-Jan-2020')  0.0675   2];
 

Data Types: double | char | 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

cell array of date character vectors | vector of serial date numbers

Settlement date, specified as an NMBS-by-1 vector using serial date numbers or a cell array of date character vectors. Settle must be earlier than Maturity.

Data Types: double | char | cell

Maturity — Maturity date

cell array of date character vectors | vector of serial date numbers

Maturity date, specified as an NMBS-by-1 vector using serial date numbers or a cell array of date character vectors.

Data Types: double | char | cell

IssueDate — Issue date

cell array of date character vectors | vector of serial date numbers

Issue date, specified as an NMBS-by-1 vector using serial date numbers or a cell array of date character vectors.

Data Types: double | char | cell

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