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 = datetime(2002,4,15);
Maturity = datetime(2030,1,1);
IssueDate = datetime(2000,1,1);
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 = [datetime(2000,2,13) ; datetime(2002,4,17) ; datetime(2002,5,17) ; datetime(2000,1,13)];
Maturity  = datetime(2030,1,1);
IssueDate = datetime(2000,1,1);
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

datetime array | string array | date character vector

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

To support existing code, mbsyield also accepts serial date numbers as inputs, but they are not recommended.

Maturity — Maturity date

datetime array | string array | date character vector

Maturity date, specified as an NMBS-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, mbsyield also accepts serial date numbers as inputs, but they are not recommended.

IssueDate — Issue date

datetime array | string array | date character vector

Issue date, specified as an NMBS-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, mbsyield also accepts serial date numbers as inputs, but they are not recommended.

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

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although mbsyield supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.