cfamounts

Cash flow and time mapping for bond portfolio

In R2017b, the specification of optional input arguments has changed. While the previous ordered inputs syntax is still supported, it may no longer be supported in a future release. Use the optional name-value pair inputs: Period, Basis, EndMonthRule, IssueDate,FirstCouponDate, LastCouponDate, StartDate,Face, AdjustCashFlowsBasis, BusinessDayConvention, CompoundingFrequency, DiscountBasis, Holidays, and PrincipalType.

Syntax

[CFlowAmounts,CFlowDates,TFactors,CFlowFlags,CFPrincipal] = cfamounts(CouponRate,Settle,Maturity)

[CFlowAmounts,CFlowDates,TFactors,CFlowFlags,CFPrincipal] = cfamounts(___,Name,Value)

Description

[CFlowAmounts,CFlowDates,TFactors,CFlowFlags,CFPrincipal] = cfamounts(CouponRate,Settle,Maturity) returns matrices of cash flow amounts, cash flow dates, time factors, and cash flow flags for a portfolio of NUMBONDS fixed-income securities.

The elements contained in the cfamounts outputs for the cash flow matrix, time factor matrix, and cash flow flag matrix correspond to the cash flow dates for each security. The first element of each row in the cash flow matrix is the accrued interest payable on each bond. This accrued interest is zero in the case of all zero coupon bonds. cfamounts determines all cash flows and time mappings for a bond whether or not the coupon structure contains odd first or last periods. All output matrices are padded with NaNs as necessary to ensure that all rows have the same number of elements.

[CFlowAmounts,CFlowDates,TFactors,CFlowFlags,CFPrincipal] = cfamounts(___,Name,Value) adds optional name-value arguments.

Examples

Compute the Cash Flow Structure and Time Factors for a Bond Portfolio

This example shows how to compute the cash flow structure and time factors for a bond portfolio that contains a corporate bond paying interest quarterly and a Treasury bond paying interest semiannually.

Settle = '01-Nov-1993';
Maturity = ['15-Dec-1994';'15-Jun-1995'];
CouponRate= [0.06; 0.05];
Period = [4; 2];
Basis = [1; 0];
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = ...
cfamounts(CouponRate,Settle, Maturity, Period, Basis)

CFlowAmounts = 2×6

   -0.7667    1.5000    1.5000    1.5000    1.5000  101.5000
   -1.8989    2.5000    2.5000    2.5000  102.5000       NaN

CFlowDates = 2×6

      728234      728278      728368      728460      728552      728643
      728234      728278      728460      728643      728825         NaN

TFactors = 2×6

         0    0.2404    0.7403    1.2404    1.7403    2.2404
         0    0.2404    1.2404    2.2404    3.2404       NaN

CFlowFlags = 2×6

     0     3     3     3     3     4
     0     3     3     3     4   NaN

Compute the Cash Flow Structure and Time Factors for a Bond Portfolio and Return a datetime array for CFlowDates

This example shows how to compute the cash flow structure and time factors for a bond portfolio that contains a corporate bond paying interest quarterly and a Treasury bond paying interest semiannually and CFlowDates is returned as a datetime array.

Settle = datetime('01-Nov-1993','Locale','en_US');
Maturity = ['15-Dec-1994';'15-Jun-1995'];
CouponRate= [0.06; 0.05];
Period = [4; 2];
Basis = [1; 0];
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = cfamounts(CouponRate,...
Settle, Maturity, Period, Basis)

CFlowAmounts = 2×6

   -0.7667    1.5000    1.5000    1.5000    1.5000  101.5000
   -1.8989    2.5000    2.5000    2.5000  102.5000       NaN

CFlowDates = 2x6 datetime
Columns 1 through 5

   01-Nov-1993   15-Dec-1993   15-Mar-1994   15-Jun-1994   15-Sep-1994
   01-Nov-1993   15-Dec-1993   15-Jun-1994   15-Dec-1994   15-Jun-1995

Column 6

   15-Dec-1994
   NaT        

TFactors = 2×6

         0    0.2404    0.7403    1.2404    1.7403    2.2404
         0    0.2404    1.2404    2.2404    3.2404       NaN

CFlowFlags = 2×6

     0     3     3     3     3     4
     0     3     3     3     4   NaN

Compute the Cash Flow Structure and Time Factors for a Bond Portfolio Using Optional Name-Value Pairs

This example shows how to compute the cash flow structure and time factors for a bond portfolio that contains a corporate bond paying interest quarterly and a Treasury bond paying interest semiannually. This example uses the following Name-Value pairs for Period, Basis, BusinessDayConvention, and AdjustCashFlowsBasis.

Settle = '01-Jun-2010';
Maturity = ['15-Dec-2011';'15-Jun-2012'];
CouponRate= [0.06; 0.05];
Period = [4; 2];
Basis = [1; 0];
 
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = ...
cfamounts(CouponRate,Settle, Maturity, 'Period',Period, ... 
'Basis', Basis, 'AdjustCashFlowsBasis', true,...
'BusinessDayConvention','modifiedfollow')

CFlowAmounts = 2×8

   -1.2667    1.5000    1.5000    1.5000    1.5000    1.5000    1.5000  101.5000
   -2.3077    2.4932    2.5068    2.4932    2.5000  102.5000       NaN       NaN

CFlowDates = 2×8

      734290      734304      734396      734487      734577      734669      734761      734852
      734290      734304      734487      734669      734852      735035         NaN         NaN

TFactors = 2×8

         0    0.0778    0.5778    1.0778    1.5778    2.0778    2.5778    3.0778
         0    0.0769    1.0769    2.0769    3.0769    4.0769       NaN       NaN

CFlowFlags = 2×8

     0     3     3     3     3     3     3     4
     0     3     3     3     3     4   NaN   NaN

Use cfamounts With a CouponRate Schedule

This example shows how to use cfamounts with a CouponRate schedule. For CouponRate and Face that change over the life of the bond, schedules for CouponRate and Face can be specified with an NINST-by-1 cell array, where each element is a NumDates-by-2 matrix where the first column is dates and the second column is associated rates.

CouponSchedule = {[datenum('15-Mar-2012') .04;datenum('15- Mar -2013') .05;...
datenum('15- Mar -2015') .06]}

CouponSchedule = 1x1 cell array
    {3x2 double}

cfamounts(CouponSchedule,'01-Mar-2011','15-Mar-2015' )

ans = 1×10

   -1.8453    2.0000    2.0000    2.0000    2.5000    2.5000    3.0000    3.0000    3.0000  103.0000

Use cfamounts With a Face Schedule

This example shows how to use cfamounts with a Face schedule. For CouponRate and Face that change over the life of the bond, schedules for CouponRate and Face can be specified with an NINST-by-1 cell array, where each element is a NumDates-by-2 matrix where the first column is dates and the second column is associated rates.

FaceSchedule = {[datenum('15-Mar-2012') 100;datenum('15- Mar -2013') 90;...
datenum('15- Mar -2015') 80]}

FaceSchedule = 1x1 cell array
    {3x2 double}

cfamounts(.05,'01-Mar-2011','15-Mar-2015', 'Face', FaceSchedule)

ans = 1×10

   -2.3066    2.5000    2.5000   12.5000    2.2500   12.2500    2.0000    2.0000    2.0000   82.0000

Use cfamounts to Generate the Cash Flows for a Sinking Bond

This example shows how to use cfamounts to generate the cash flows for a sinking bond.

[CFlowAmounts,CFDates,TFactors,CFFlags,CFPrincipal] = cfamounts(.05,'04-Nov-2010',...
{'15-Jul-2014';'15-Jul-2015'},'Face',{[datenum('15-Jul-2013') 100;datenum('15-Jul-2014')...
90;datenum('15-Jul-2015') 80]})

CFlowAmounts = 2×11

   -1.5217    2.5000    2.5000    2.5000    2.5000    2.5000   12.5000    2.2500   92.2500       NaN       NaN
   -1.5217    2.5000    2.5000    2.5000    2.5000    2.5000   12.5000    2.2500   12.2500    2.0000   82.0000

CFDates = 2×11

      734446      734518      734699      734883      735065      735249      735430      735614      735795         NaN         NaN
      734446      734518      734699      734883      735065      735249      735430      735614      735795      735979      736160

TFactors = 2×11

         0    0.3913    1.3913    2.3913    3.3913    4.3913    5.3913    6.3913    7.3913       NaN       NaN
         0    0.3913    1.3913    2.3913    3.3913    4.3913    5.3913    6.3913    7.3913    8.3913    9.3913

CFFlags = 2×11

     0     3     3     3     3     3    13     3     4   NaN   NaN
     0     3     3     3     3     3    13     3    13     3     4

CFPrincipal = 2×11

     0     0     0     0     0     0    10     0    90   NaN   NaN
     0     0     0     0     0     0    10     0    10     0    80

Input Arguments

CouponRate — Annual percentage rate used to determine coupons payable on a bond

decimal

Annual percentage rate used to determine the coupons payable on a bond, specified as decimal using a scalar or a NBONDS-by-1 vector.

CouponRate is 0 for zero coupon bonds.

Note

CouponRate and Face can change over the life of the bond. Schedules for CouponRate and Face can be specified with an NBONDS-by-1 cell array, where each element is a NumDates-by-2 matrix or cell array, where the first column is dates (serial date numbers or character vectors) and the second column is associated rates. The date indicates the last day that the coupon rate or face value is valid. This means that the corresponding CouponRate and Face value applies "on or before" the specified ending date.

Data Types: double | cell | char

Settle — Settlement date of bond

serial date number | date character vector | datetime

Settlement date of the bond, specified as a scalar or a NBONDS-by-1 vector using serial date numbers, date character vectors, or datetime arrays. The Settle date must be before the Maturity date.

Data Types: double | char | datetime

Maturity — Maturity date of bond

serial date number | date character vector | datetime

Maturity date of the bond, specified as a scalar or a NBONDS-by-1 vector using serial date numbers, date character vectors, or datetime arrays.

Data Types: double | char | datetime

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: [CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = ... cfamounts(CouponRate,Settle, Maturity,'Period',4,'Basis',3,'AdjustCashFlowsBasis',true,'BusinessDayConvention','modifiedfollow')

'Period' — Number of coupon payments per year for bond

2 (default) | numeric with values 0, 1, 2, 3, 4, 6 or 12

Number of coupon payments per year for the bond, specified as the comma-separated pair consisting of 'Period' and a scalar or a NBONDS-by-1 vector using the values: 0, 1, 2, 3, 4, 6, or 12.

Data Types: double

'Basis' — Day-count basis of bond

0 (default) | numeric values: 0,1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13

Day-count basis of the bond, specified as the comma-separated pair consisting of 'Basis' and a scalar or a NBONDS-by-1 vector using a supported value:

• 0 = actual/actual

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (PSA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: double

'EndMonthRule' — End-of-month rule flag

1 (in effect) (default) | nonnegative integer 0 or 1

End-of-month rule flag, specified as the comma-separated pair consisting of 'EndMonthRule' and a scalar or a NBONDS-by-1 vector. This rule applies only when Maturity is an end-of-month date for a month having 30 or fewer days.

• 0 = Ignore rule, meaning that a bond coupon payment date is always the same numerical day of the month.

• 1 = Set rule on, meaning that a bond coupon payment date is always the last actual day of the month.

Data Types: logical

'IssueDate' — Bond issue date

serial date number | date character vector | datetime

Bond issue date (the date the bond begins to accrue interest), specified as the comma-separated pair consisting of 'IssueDate' and a scalar or a NBONDS-by-1 vector using serial date numbers, date character vectors, or datetime arrays. The IssueDate cannot be after the Settle date.

If you do not specify an IssueDate, the cash flow payment dates are determined from other inputs.

Data Types: double | char | datetime

'FirstCouponDate' — Irregular or normal first coupon date

serial date number | date character vector | datetime

Irregular or normal first coupon date, specified as the comma-separated pair consisting of 'FirstCouponDate' and a scalar or a NBONDS-by-1 vector using serial date numbers, date character vectors, or datetime arrays.

If you do not specify a FirstCouponDate, the cash flow payment dates are determined from other inputs.

Note

When FirstCouponDate and LastCouponDate

are both specified, the FirstCouponDate takes precedence in determining the coupon payment structure. If FirstCouponDate is not specified, then LastCouponDate determines the coupon structure of the bond.

Data Types: double | char | datetime

'LastCouponDate' — Irregular or normal last coupon date

serial date number | date character vector | datetime

Irregular or normal last coupon date, specified as the comma-separated pair consisting of 'LastCouponDate' and a scalar or a NBONDS-by-1 vector using serial date numbers, date character vectors, or datetime arrays.

Note

When FirstCouponDate and LastCouponDate are both specified, the FirstCouponDate takes precedence in determining the coupon payment structure. If FirstCouponDate is not specified, then LastCouponDate determines the coupon structure of the bond.

Data Types: double | char | datetime

'StartDate' — Forward starting date of coupon payments

serial date number | date character vector | datetime

Forward starting date of coupon payments after the Settle date, specified as the comma-separated pair consisting of 'StartDate' and a scalar or a NBONDS-by-1 vector using serial date numbers, date character vectors, or datetime arrays.

Note

To make an instrument forward starting, specify StartDate as a future date.

If you do not specify a StartDate, the effective start date is the Settle date.

Data Types: double | char | datetime

'Face' — Face value of bond

100 (default) | numeric

Face value of the bond, specified as the comma-separated pair consisting of 'Face' and a scalar or a NBONDS-by-1 vector.

Note

CouponRate and Face can change over the life of the bond. Schedules for CouponRate and Face can be specified with an NBONDS-by-1 cell array where each element is a NumDates-by-2 matrix or cell array, where the first column is dates (serial date numbers or character vectors) and the second column is associated rates. The date indicates the last day that the coupon rate or face value is valid. This means that the corresponding CouponRate and Face value applies "on or before" the specified ending date.

When the corresponding Face value is used to compute the coupon cashflow on the specified ending date. Three things happen on the specified ending date:

1. The last coupon corresponding to the current Face value is paid.

2. The principal differential (between the current and the next Face value) is paid.

3. The date marks the beginning of the period with the next Face value, for which the cashflow does not occur until later.

Data Types: double | cell | char

'AdjustCashFlowsBasis' — Adjusts cash flows according to accrual amount based on actual period day count

false (default) | logical with a value of true or false

Adjusts cash flows according to the accrual amount based on the actual period day count, specified as the comma-separated pair consisting of 'AdjustCashFlowsBasis' and a scalar or a NBONDS-by-1 vector.

Data Types: logical

'BusinessDayConvention' — Business day conventions

'actual' (default) | character vector with values'actual', 'follow', 'modifiedfollow', 'previous'or 'modifiedprevious'

Business day conventions, specified as the comma-separated pair consisting of 'BusinessDayConvention' and a scalar or NBONDS-by-1 cell array of character vectors of business day conventions to be used in computing payment dates. The selection for business day convention determines how nonbusiness days are treated. Nonbusiness days are defined as weekends plus any other date that businesses are not open (for example, statutory holidays). Values are:

• 'actual' — Nonbusiness days are effectively ignored. Cash flows that fall on non-business days are assumed to be distributed on the actual date.

• 'follow' — Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day.

• 'modifiedfollow' — Cash flows that fall on a non-business day are assumed to be distributed on the following business day. However if the following business day is in a different month, the previous business day is adopted instead.

• 'previous' — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day.

• 'modifiedprevious' — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day. However if the previous business day is in a different month, the following business day is adopted instead.

Data Types: char | cell

'CompoundingFrequency' — Compounding frequency for yield calculation

SIA uses2, ICMA uses 1 (default) | integer with value of 1, 2, 3, 4, 6, or 12

Compounding frequency for yield calculation, specified as the comma-separated pair consisting of 'CompoundingFrequency' and a scalar or a NBONDS-by-1 vector. Values are:

• 1 — Annual compounding

• 2 — Semiannual compounding

• 3 — Compounding three times per year

• 4 — Quarterly compounding

• 6 — Bimonthly compounding

• 12 — Monthly compounding

Note

By default, SIA bases (0-7) and BUS/252 use a semiannual compounding convention and ICMA bases (8-12) use an annual compounding convention.

Data Types: double

'DiscountBasis' — Basis used to compute the discount factors for computing the yield

SIA uses 0 (default) | integers of the set [0...13] | vector of integers of the set [0...13]

Basis used to compute the discount factors for computing the yield, specified as the comma-separated pair consisting of 'DiscountBasis' and a scalar or a NBONDS-by-1 vector. Values are:

• 0 = actual/actual

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (PSA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Note

If a SIA day-count basis is defined in the Basis input argument and there is no value assigned for DiscountBasis, the default behavior is for SIA bases to use the actual/actual day count to compute discount factors.

If an ICMA day-count basis or BUS/252 is defined in the Basis input argument and there is no value assigned for DiscountBasis, the specified bases from the Basis input argument are used.

Data Types: double

'Holidays' — Dates for holidays

holidays.m used (default)

Dates for holidays, specified as the comma-separated pair consisting of 'Holidays' and a NHOLIDAYS-by-1 vector of MATLAB^® dates using serial date numbers, date character vectors, or datetime arrays. Holidays are used in computing business days.

Data Types: double | char | datetime

'PrincipalType' — Type of principal when a Face schedule is specified

sinking (default) | character vector with values 'sinking' or 'bullet'

Type of principal when a Face schedule, specified as the comma-separated pair consisting of 'PrincipalType' and a value of 'sinking' or 'bullet' using a scalar or a NBONDS-by-1 vector.

If 'sinking', principal cash flows are returned throughout the life of the bond.

If 'bullet', principal cash flow is only returned at maturity.

Data Types: char | cell

Output Arguments

CFlowAmounts — Cash flow amounts

matrix

Cash flow amounts, returned as a NBONDS-by-NCFS (number of cash flows) matrix. The first entry in each row vector is the accrued interest due at settlement. This amount could be zero, positive or negative. If no accrued interest is due, the first column is zero. If the bond is trading ex-coupon then the accrued interest is negative.

CFlowDates — Cash flow dates for a portfolio of bonds

matrix

Cash flow dates for a portfolio of bonds, returned as a NBONDS-by-NCFS matrix. Each row represents a single bond in the portfolio. Each element in a column represents a cash flow date of that bond.

If all the above inputs (Settle, Maturity, IssueDate, FirstCouponDate, LastCouponDate, and StartDate) are either serial date numbers or date character vectors, then CFlowDates is returned as a serial date number. If any of these inputs are datetime arrays, then CFlowDates is returned as a datetime array.

TFactors — Matrix of time factors for a portfolio of bonds

matrix

Matrix of time factors for a portfolio of bonds, returned as a NBONDS-by-NCFS matrix. Each row corresponds to the vector of time factors for each bond. Each element in a column corresponds to the specific time factor associated with each cash flow of a bond.

Time factors are for price/yield conversion and time factors are in units of whole semiannual coupon periods plus any fractional period using an actual day count. For more information on time factors, see Time Factors.

CFlowFlags — Cash flow flags for a portfolio of bonds

matrix

Cash flow flags for a portfolio of bonds, returned as a NBONDS-by-NCFS matrix. Each row corresponds to the vector of cash flow flags for each bond. Each element in a column corresponds to the specific flag associated with each cash flow of a bond. Flags identify the type of each cash flow (for example, nominal coupon cash flow, front, or end partial, or "stub" coupon, maturity cash flow).

Flag	Cash Flow Type
0	Accrued interest due on a bond at settlement.
1	Initial cash flow amount smaller than normal due to a “stub” coupon period. A stub period is created when the time from issue date to first coupon date is shorter than normal.
2	Larger than normal initial cash flow amount because the first coupon period is longer than normal.
3	Nominal coupon cash flow amount.
4	Normal maturity cash flow amount (face value plus the nominal coupon amount).
5	End “stub” coupon amount (last coupon period is abnormally short and actual maturity cash flow is smaller than normal).
6	Larger than normal maturity cash flow because the last coupon period longer than normal.
7	Maturity cash flow on a coupon bond when the bond has less than one coupon period to maturity.
8	Smaller than normal maturity cash flow when the bond has less than one coupon period to maturity.
9	Larger than normal maturity cash flow when the bond has less than one coupon period to maturity.
10	Maturity cash flow on a zero coupon bond.
11	Sinking principal and initial cash flow amount smaller than normal due to a "stub" coupon period. A stub period is created when the time from issue date to first coupon date is shorter than normal.
12	Sinking principal and larger than normal initial cash flow amount because the first coupon period is longer than normal.
13	Sinking principal and nominal coupon cash flow amount.

CFPrincipal — Principal cash flows

matrix

Principal cash flows, returned as a NBONDS-by-NCFS matrix.

If PrincipalType is 'sinking', CFPrincipal output indicates when the principal is returned.

If PrincipalType is 'bullet', CFPrincipal is all zeros and, at Maturity, the appropriate Face value.

More About

Time Factors

Time factors help determine the present value of a stream of cash flows.

The term time factors refer to the exponent TF in the discounting equation

$$PV={\displaystyle \sum _{i=1}^n\left(\frac{CF}{{(1+\frac{z}{f})}^{TF}}\right)},$$

where:

PV =	Present value of a cash flow.
CF =	Cash flow amount.
z =	Risk-adjusted annualized rate or yield corresponding to a given cash flow. The yield is quoted on a semiannual basis.
f =	Frequency of quotes for the yield. Default is 2 for Basis values 0 to 7 and 13 and 1 for Basis values 8 to 12. The default can be overridden by specifying the CompoundingFrequency name-value pair.
TF =	Time factor for a given cash flow. The time factor is computed using the compounding frequency and the discount basis. If these values are not specified, then the defaults are as follows: CompoundingFrequency default is 2 for Basis values 0 to 7 and 13 and 1 for Basis values 8 to 12. DiscountBasis is 0 for Basis values 0 to 7 and 13 and the value of the input Basis for Basis values 8 to 12.

Note

The Basis is always used to compute accrued interest.

References

[1] Krgin, D. Handbook of Global Fixed Income Calculations. Wiley, 2002.

[2] Mayle, J. "Standard Securities Calculations Methods: Fixed Income Securities Formulas for Analytic Measures." SIA, Vol 2, Jan 1994.

[3] Stigum, M., Robinson, F. Money Market and Bond Calculation. McGraw-Hill, 1996.