mbsyield

Mortgage-backed security yields given price

Syntax

``[MYield,BEMBSYield] = mbsyield(Price,Settle,Maturity,IssueDate,GrossRate)``
``[MYield,BEMBSYield] = mbsyield(___CouponRate,Delay,PrepaySpeed,PrepayMatrix)``

Description

example

````[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. ```

example

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

collapse all

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

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

collapse all

Clean price for every \$100 face value, specified as an `NMBS`-by-`1` vector.

Data Types: `double`

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

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.

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) 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).

References

[1] PSA Uniform Practices, SF-49

Version History

Introduced before R2006a

expand all