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

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

Note

Unlike mbspassthrough, mbscfamounts does not accept an original balance amount as an input. mbscfamounts assumes an original balance of 1.

[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

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

CFlowAmounts — Cash flow amounts

matrix

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

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 R2012a

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