# mbscfamounts

Cash flow and time mapping for mortgage pool

## Syntax

``[CFlowAmounts,CFlowDates,TFactors,Factors,Payment,Principal,Interest,Prepayment] = mbscfamounts(Settle,Maturity,IssueDate,GrossRate)``
``[CFlowAmounts,CFlowDates,TFactors,Factors,Payment,Principal,Interest,Prepayment] = mbscfamounts(___,CouponRate,Delay,PrepaySpeed,PrepayMatrix)``

## Description

example

````[CFlowAmounts,CFlowDates,TFactors,Factors,Payment,Principal,Interest,Prepayment] = mbscfamounts(Settle,Maturity,IssueDate,GrossRate)` computes cash flows between `Settle` and `Maturity` dates, the corresponding time factors in months from `Settle` and the mortgage factor (the fraction of loan principal outstanding). NoteUnlike `mbspassthrough`, `mbscfamounts` does not accept an original balance amount as an input. `mbscfamounts` assumes an original balance of 1. ```

example

````[CFlowAmounts,CFlowDates,TFactors,Factors,Payment,Principal,Interest,Prepayment] = mbscfamounts(___,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

Given a mortgage with the following characteristics, compute the cash flow amounts and dates, the time factors, and the mortgage factors.

Define the mortgage characteristics.

```Settle = datetime(2002,4,17); Maturity = datetime(2030,1,1); IssueDate = datetime(2000,1,1); GrossRate = 0.08125; CouponRate = 0.075; Delay = 14; PrepaySpeed = 100;```

Use `mbscfamonts` to evaluate the mortgage.

```[CFlowAmounts, CFLowDates, TFactors, Factors] = ... mbscfamounts(Settle, Maturity, IssueDate, GrossRate, ... CouponRate, Delay, PrepaySpeed)```
```CFlowAmounts = 1×334 -0.0033 0.0118 0.0120 0.0121 0.0120 0.0119 0.0119 0.0118 0.0117 0.0117 0.0116 0.0115 0.0115 0.0114 0.0114 0.0113 0.0112 0.0112 0.0111 0.0110 0.0110 0.0109 0.0109 0.0108 0.0107 0.0107 0.0106 0.0106 0.0105 0.0105 0.0104 0.0103 0.0103 0.0102 0.0102 0.0101 0.0101 0.0100 0.0099 0.0099 0.0098 0.0098 0.0097 0.0097 0.0096 0.0096 0.0095 0.0095 0.0094 0.0094 ```
```CFLowDates = 1×334 731323 731337 731368 731398 731429 731460 731490 731521 731551 731582 731613 731641 731672 731702 731733 731763 731794 731825 731855 731886 731916 731947 731978 732007 732038 732068 732099 732129 732160 732191 732221 732252 732282 732313 732344 732372 732403 732433 732464 732494 732525 732556 732586 732617 732647 732678 732709 732737 732768 732798 ```
```TFactors = 1×334 0 0.9333 1.9333 2.9333 3.9333 4.9333 5.9333 6.9333 7.9333 8.9333 9.9333 10.9333 11.9333 12.9333 13.9333 14.9333 15.9333 16.9333 17.9333 18.9333 19.9333 20.9333 21.9333 22.9333 23.9333 24.9333 25.9333 26.9333 27.9333 28.9333 29.9333 30.9333 31.9333 32.9333 33.9333 34.9333 35.9333 36.9333 37.9333 38.9333 39.9333 40.9333 41.9333 42.9333 43.9333 44.9333 45.9333 46.9333 47.9333 48.9333 ```
```Factors = 1×334 1.0000 0.9944 0.9887 0.9828 0.9769 0.9711 0.9653 0.9595 0.9538 0.9481 0.9424 0.9368 0.9311 0.9255 0.9199 0.9144 0.9089 0.9034 0.8979 0.8925 0.8871 0.8817 0.8763 0.8710 0.8657 0.8604 0.8552 0.8499 0.8447 0.8396 0.8344 0.8293 0.8242 0.8191 0.8140 0.8090 0.8040 0.7990 0.7941 0.7892 0.7842 0.7794 0.7745 0.7697 0.7649 0.7601 0.7553 0.7506 0.7458 0.7411 ```

The result is contained in four 334-element row vectors.

Given a portfolio of mortgage-backed securities, use `mbscfamounts` to compute the cash flows and other factors from the portfolio.

Define characteristics for a mortgage portfolio.

```Settle = [datetime(2000,1,13) ; datetime(2002,4,17) ; datetime(2002,5,17)]; Maturity = datetime(2030,1,1); IssueDate = datetime(2000,1,1); GrossRate = 0.08125; CouponRate = [0.075; 0.07875; 0.0775]; Delay = 14; PrepaySpeed = 100;```

Use `mbscfamonts` to evaluate the mortgage.

```[CFlowAmounts, CFlowDates, TFactors, Factors] = ... mbscfamounts(Settle, Maturity, IssueDate, GrossRate, ... CouponRate, Delay, PrepaySpeed)```
```CFlowAmounts = 3×361 -0.0025 0.0071 0.0072 0.0074 0.0076 0.0077 0.0079 0.0080 0.0082 0.0084 0.0085 0.0087 0.0088 0.0090 0.0091 0.0093 0.0094 0.0095 0.0097 0.0098 0.0099 0.0101 0.0102 0.0103 0.0104 0.0106 0.0107 0.0108 0.0109 0.0110 0.0111 0.0110 0.0110 0.0109 0.0109 0.0108 0.0107 0.0107 0.0106 0.0106 0.0105 0.0104 0.0104 0.0103 0.0103 0.0102 0.0102 0.0101 0.0101 0.0100 -0.0035 0.0121 0.0123 0.0124 0.0123 0.0122 0.0122 0.0121 0.0120 0.0120 0.0119 0.0118 0.0118 0.0117 0.0116 0.0116 0.0115 0.0115 0.0114 0.0113 0.0113 0.0112 0.0111 0.0111 0.0110 0.0110 0.0109 0.0108 0.0108 0.0107 0.0107 0.0106 0.0105 0.0105 0.0104 0.0104 0.0103 0.0103 0.0102 0.0101 0.0101 0.0100 0.0100 0.0099 0.0099 0.0098 0.0098 0.0097 0.0096 0.0096 -0.0034 0.0122 0.0123 0.0123 0.0122 0.0121 0.0121 0.0120 0.0119 0.0119 0.0118 0.0117 0.0117 0.0116 0.0116 0.0115 0.0114 0.0114 0.0113 0.0112 0.0112 0.0111 0.0111 0.0110 0.0109 0.0109 0.0108 0.0108 0.0107 0.0106 0.0106 0.0105 0.0105 0.0104 0.0103 0.0103 0.0102 0.0102 0.0101 0.0101 0.0100 0.0099 0.0099 0.0098 0.0098 0.0097 0.0097 0.0096 0.0096 0.0095 ```
```CFlowDates = 3×361 730498 730517 730546 730577 730607 730638 730668 730699 730730 730760 730791 730821 730852 730883 730911 730942 730972 731003 731033 731064 731095 731125 731156 731186 731217 731248 731276 731307 731337 731368 731398 731429 731460 731490 731521 731551 731582 731613 731641 731672 731702 731733 731763 731794 731825 731855 731886 731916 731947 731978 731323 731337 731368 731398 731429 731460 731490 731521 731551 731582 731613 731641 731672 731702 731733 731763 731794 731825 731855 731886 731916 731947 731978 732007 732038 732068 732099 732129 732160 732191 732221 732252 732282 732313 732344 732372 732403 732433 732464 732494 732525 732556 732586 732617 732647 732678 732709 732737 732768 732798 731353 731368 731398 731429 731460 731490 731521 731551 731582 731613 731641 731672 731702 731733 731763 731794 731825 731855 731886 731916 731947 731978 732007 732038 732068 732099 732129 732160 732191 732221 732252 732282 732313 732344 732372 732403 732433 732464 732494 732525 732556 732586 732617 732647 732678 732709 732737 732768 732798 732829 ```
```TFactors = 3×361 0 1.0667 2.0667 3.0667 4.0667 5.0667 6.0667 7.0667 8.0667 9.0667 10.0667 11.0667 12.0667 13.0667 14.0667 15.0667 16.0667 17.0667 18.0667 19.0667 20.0667 21.0667 22.0667 23.0667 24.0667 25.0667 26.0667 27.0667 28.0667 29.0667 30.0667 31.0667 32.0667 33.0667 34.0667 35.0667 36.0667 37.0667 38.0667 39.0667 40.0667 41.0667 42.0667 43.0667 44.0667 45.0667 46.0667 47.0667 48.0667 49.0667 0 0.9333 1.9333 2.9333 3.9333 4.9333 5.9333 6.9333 7.9333 8.9333 9.9333 10.9333 11.9333 12.9333 13.9333 14.9333 15.9333 16.9333 17.9333 18.9333 19.9333 20.9333 21.9333 22.9333 23.9333 24.9333 25.9333 26.9333 27.9333 28.9333 29.9333 30.9333 31.9333 32.9333 33.9333 34.9333 35.9333 36.9333 37.9333 38.9333 39.9333 40.9333 41.9333 42.9333 43.9333 44.9333 45.9333 46.9333 47.9333 48.9333 0 0.9333 1.9333 2.9333 3.9333 4.9333 5.9333 6.9333 7.9333 8.9333 9.9333 10.9333 11.9333 12.9333 13.9333 14.9333 15.9333 16.9333 17.9333 18.9333 19.9333 20.9333 21.9333 22.9333 23.9333 24.9333 25.9333 26.9333 27.9333 28.9333 29.9333 30.9333 31.9333 32.9333 33.9333 34.9333 35.9333 36.9333 37.9333 38.9333 39.9333 40.9333 41.9333 42.9333 43.9333 44.9333 45.9333 46.9333 47.9333 48.9333 ```
```Factors = 3×361 1.0000 0.9992 0.9982 0.9970 0.9957 0.9942 0.9925 0.9907 0.9887 0.9865 0.9841 0.9816 0.9789 0.9761 0.9731 0.9699 0.9666 0.9631 0.9594 0.9556 0.9517 0.9475 0.9433 0.9389 0.9343 0.9296 0.9247 0.9197 0.9146 0.9093 0.9039 0.8985 0.8932 0.8878 0.8825 0.8772 0.8720 0.8668 0.8616 0.8564 0.8512 0.8461 0.8410 0.8359 0.8309 0.8258 0.8208 0.8159 0.8109 0.8060 1.0000 0.9944 0.9887 0.9828 0.9769 0.9711 0.9653 0.9595 0.9538 0.9481 0.9424 0.9368 0.9311 0.9255 0.9199 0.9144 0.9089 0.9034 0.8979 0.8925 0.8871 0.8817 0.8763 0.8710 0.8657 0.8604 0.8552 0.8499 0.8447 0.8396 0.8344 0.8293 0.8242 0.8191 0.8140 0.8090 0.8040 0.7990 0.7941 0.7892 0.7842 0.7794 0.7745 0.7697 0.7649 0.7601 0.7553 0.7506 0.7458 0.7411 1.0000 0.9942 0.9883 0.9824 0.9766 0.9707 0.9649 0.9592 0.9534 0.9477 0.9420 0.9364 0.9307 0.9251 0.9195 0.9140 0.9085 0.9030 0.8975 0.8921 0.8866 0.8813 0.8759 0.8706 0.8653 0.8600 0.8547 0.8495 0.8443 0.8391 0.8339 0.8288 0.8237 0.8186 0.8136 0.8085 0.8035 0.7985 0.7936 0.7887 0.7837 0.7789 0.7740 0.7692 0.7643 0.7595 0.7548 0.7500 0.7453 0.7406 ```

Each output is a 3-by-361 element matrix padded with `NaN`'s wherever elements are missing.

Given a mortgage with the following characteristics, compute payments, principal, interest, and prepayment.

Define the mortgage characteristics.

```Settle = datetime(2002,4,17); Maturity = datetime(2030,1,1); IssueDate = datetime(2000,1,1); GrossRate = 0.08125; CouponRate = 0.075; Delay = 14; PrepaySpeed = 100;```

Use `mbscfamonts` to evaluate the mortgage.

```[Payment, Principal, Interest, Prepayment] = ... mbscfamounts(Settle, Maturity, IssueDate, GrossRate, ... CouponRate, Delay, PrepaySpeed)```
```Payment = 1×334 -0.0033 0.0118 0.0120 0.0121 0.0120 0.0119 0.0119 0.0118 0.0117 0.0117 0.0116 0.0115 0.0115 0.0114 0.0114 0.0113 0.0112 0.0112 0.0111 0.0110 0.0110 0.0109 0.0109 0.0108 0.0107 0.0107 0.0106 0.0106 0.0105 0.0105 0.0104 0.0103 0.0103 0.0102 0.0102 0.0101 0.0101 0.0100 0.0099 0.0099 0.0098 0.0098 0.0097 0.0097 0.0096 0.0096 0.0095 0.0095 0.0094 0.0094 ```
```Principal = 1×334 731323 731337 731368 731398 731429 731460 731490 731521 731551 731582 731613 731641 731672 731702 731733 731763 731794 731825 731855 731886 731916 731947 731978 732007 732038 732068 732099 732129 732160 732191 732221 732252 732282 732313 732344 732372 732403 732433 732464 732494 732525 732556 732586 732617 732647 732678 732709 732737 732768 732798 ```
```Interest = 1×334 0 0.9333 1.9333 2.9333 3.9333 4.9333 5.9333 6.9333 7.9333 8.9333 9.9333 10.9333 11.9333 12.9333 13.9333 14.9333 15.9333 16.9333 17.9333 18.9333 19.9333 20.9333 21.9333 22.9333 23.9333 24.9333 25.9333 26.9333 27.9333 28.9333 29.9333 30.9333 31.9333 32.9333 33.9333 34.9333 35.9333 36.9333 37.9333 38.9333 39.9333 40.9333 41.9333 42.9333 43.9333 44.9333 45.9333 46.9333 47.9333 48.9333 ```
```Prepayment = 1×334 1.0000 0.9944 0.9887 0.9828 0.9769 0.9711 0.9653 0.9595 0.9538 0.9481 0.9424 0.9368 0.9311 0.9255 0.9199 0.9144 0.9089 0.9034 0.8979 0.8925 0.8871 0.8817 0.8763 0.8710 0.8657 0.8604 0.8552 0.8499 0.8447 0.8396 0.8344 0.8293 0.8242 0.8191 0.8140 0.8090 0.8040 0.7990 0.7941 0.7892 0.7842 0.7794 0.7745 0.7697 0.7649 0.7601 0.7553 0.7506 0.7458 0.7411 ```

## Input Arguments

collapse all

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

Cash flows starting from `Settle` through end of the last month (`Maturity`), returned as a `NMBS`-by-`P` matrix.

Cash flow dates (including at `Settle`), returned as a `NMBS`-by-`P` matrix.

Time factors (in months from `Settle`), returned as a `NMBS`-by-`P` matrix.

Mortgage factors (the fraction of the balance still outstanding at the end of each month), returned as a `NMBS`-by-`P` matrix.

Total monthly payment, returned as a `NMBS`-by-`P` matrix.

Principal portion of the payment, returned as a `NMBS`-by-`P` matrix.

Interest portion of the payment, returned as a `NMBS`-by-`P` matrix.

Unscheduled payment of principal, returned as a `NMBS`-by-`P` matrix.

## References

[1] PSA Uniform Practices, SF-49

## Version History

Introduced in R2012a

expand all