mbscfamounts
Cash flow and time mapping for mortgage pool
Syntax
Description
[
computes cash flows between CFlowAmounts
,CFlowDates
,TFactors
,Factors
,Payment
,Principal
,Interest
,Prepayment
] = mbscfamounts(Settle
,Maturity
,IssueDate
,GrossRate
)Settle
and
Maturity
dates, the corresponding time factors in months
from Settle
and the mortgage factor (the fraction of loan
principal outstanding).
Note
Unlike mbspassthrough
,
mbscfamounts
does not accept an original balance
amount as an input. mbscfamounts
assumes an original
balance of 1.
[
specifies options using one or more optional arguments in addition to the input
arguments in the previous syntax. CFlowAmounts
,CFlowDates
,TFactors
,Factors
,Payment
,Principal
,Interest
,Prepayment
] = mbscfamounts(___,CouponRate
,Delay
,PrepaySpeed
,PrepayMatrix
)
Examples
Calculate Cash Flow Amounts and Dates, Time Factors, and Mortgage Factors for a Single Mortgage
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.
Compute Cash Flow Amounts and Dates, Time Factors, and Mortgage Factors for a Mortgage Portfolio
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.
Calculate Payment, Principal, Interest, and Prepayment for a Single Mortgage
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
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, mbscfamounts
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, mbscfamounts
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, mbscfamounts
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
CFlowDates
— Cash flow dates
matrix
Cash flow dates (including at Settle
), returned as a
NMBS
-by-P
matrix.
TFactors
— Time factors
matrix
Time factors (in months from Settle
), returned as a
NMBS
-by-P
matrix.
Factors
— Mortgage factors (the fraction of the balance still outstanding at the end of each month)
matrix
Mortgage factors (the fraction of the balance still outstanding at the end
of each month), returned as a
NMBS
-by-P
matrix.
Payment
— Total monthly payment
matrix
Total monthly payment, returned as a
NMBS
-by-P
matrix.
Principal
— Principal portion of the payment
matrix
Principal portion of the payment, returned as a
NMBS
-by-P
matrix.
Interest
— Interest portion of the payment
matrix
Interest portion of the payment, returned as a
NMBS
-by-P
matrix.
Prepayment
— Unscheduled payment of principal
matrix
Unscheduled payment of principal, returned as a
NMBS
-by-P
matrix.
References
[1] PSA Uniform Practices, SF-49
Version History
Introduced in R2012aR2022b: Serial date numbers not recommended
Although mbscfamounts
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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)