mbsyield

Mortgage-backed security yields given price

Syntax

[MYield,BEMBSYield] = mbsyield(Price,Settle,Maturity,IssueDate,GrossRate)

[MYield,BEMBSYield] = mbsyield(___CouponRate,Delay,PrepaySpeed,PrepayMatrix)

Description

[MYield,BEMBSYield] = mbsyield(Price,Settle,Maturity,IssueDate,GrossRate) computes a mortgage-backed security yield to maturity and the bond equivalent yield, given time information, and price at settlement.

[MYield,BEMBSYield] = mbsyield(___CouponRate,Delay,PrepaySpeed,PrepayMatrix) specifies options using one or more optional arguments in addition to the input arguments in the previous syntax.

Examples

Determine a Mortgage-Backed Security Yield Given the Price

This example shows how to determine the mortgage-backed security yield, given a mortgage-backed security with the following characteristics.

Price = 102;
Settle = '15-Apr-2002';
Maturity = '1 Jan 2030';
IssueDate = '1-Jan-2000';
GrossRate = 0.08125;
CouponRate = 0.075;
Delay = 14;
Speed = 100;

[MYield, BEMBSYield] = mbsyield(Price, Settle, Maturity, ... 
IssueDate, GrossRate, CouponRate, Delay,  Speed)

MYield = 0.0715

BEMBSYield = 0.0725

Determine Multiple Mortgage-Backed Securities Yields Given the Price

This example shows how to determine multiple mortgage-backed securities yields, given a portfolio of mortgage-backed securities with the following characteristics.

Price = 102;
Settle = datenum(['13-Feb-2000';'17-Apr-2002';'17-May-2002';... 
'13-Jan-2000']);
Maturity  = datenum('1-Jan-2030');
IssueDate = datenum('1-Jan-2000');
GrossRate = 0.08125;
CouponRate = [0.075; 0.07875; 0.0775; 0.08125];
Delay = 14;
Speed = 100;

[MYield, BEMBSYield] = mbsyield(Price, Settle, Maturity,... 
IssueDate, GrossRate, CouponRate, Delay,  Speed)

MYield = 4×1

    0.0717
    0.0751
    0.0739
    0.0779

BEMBSYield = 4×1

    0.0728
    0.0763
    0.0750
    0.0791

Input Arguments

Price — Clean price for every $100 face value

vector

Clean price for every $100 face value, 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

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