Accelerating the pace of engineering and science

# cfamounts

Cash flow and time mapping for bond portfolio

## Syntax

[CFlowAmounts, CFlowDates, TFactors, CFlowFlags,
CFPrincipal] = cfamounts(CouponRate, Settle, Maturity)
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags,
CFPrincipal] = cfamounts(CouponRate, Settle, Maturity, Period,
Basis, EndMonthRule, IssueDate, FirstCouponDate,
LastCouponDate, StartDate, Face)
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags,
CFPrincipal] = cfamounts(CouponRate, Settle, Maturity,
'ParameterName', 'ParameterValue ...)

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

[CFlowAmounts, CFlowDates, TFactors, CFlowFlags,
CFPrincipal] = cfamounts(CouponRate, Settle, Maturity, Period,
Basis, EndMonthRule, IssueDate, FirstCouponDate,
LastCouponDate, StartDate, Face)
returns matrices of cash flow amounts, cash flow dates, time factors, and cash flow flags for a portfolio of NUMBONDS fixed-income securities defined using required and optional inputs.

[CFlowAmounts, CFlowDates, TFactors, CFlowFlags,
CFPrincipal] = cfamounts(CouponRate, Settle, Maturity,
'ParameterName', 'ParameterValue ...)
accepts optional inputs as one or more comma-separated parameter/value pairs. 'ParameterName' is the name of the parameter inside single quotes. ParameterValue is the value corresponding to 'ParameterName'. Specify parameter/value pairs in any order. Names are case-insensitive.

## Input Arguments

CouponRate

Decimal number indicating the annual percentage rate used to determine the coupons payable on a bond. 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 NINST-by-1 cell array, where each element is a NumDates-by-2 matrix or cell array, where the first column is dates and the second column is associated rates. The date indicates the last day that the coupon rate or face value is valid.

Settle

Settlement date. A vector of serial date numbers or date strings. Settle must be earlier than Maturity.

Maturity

Maturity date. A vector of serial date numbers or date strings.

### Ordered Input or Parameter–Value Pairs

Enter the following inputs using an ordered syntax or as parameter/value pairs. You cannot mix ordered syntax with parameter/value pairs.

Period

Coupons per year of the bond. A vector of integers. Values are 0, 1, 2, 3, 4, 6, and 12.

Default: 2

Basis

Day-count basis of the instrument. A vector of integers.

• 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 (ISMA)

• 9 = actual/360 (ISMA)

• 10 = actual/365 (ISMA)

• 11 = 30/360E (ISMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

Default: 0

EndMonthRule

End-of-month rule. A 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.

Default: 1

IssueDate

Issue date for a bond.

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

FirstCouponDate

Date when a bond makes its first coupon payment; used when bond has an irregular first coupon period. When FirstCouponDate and LastCouponDate are both specified, FirstCouponDate takes precedence in determining the coupon payment structure.

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

LastCouponDate

Last coupon date of a bond before the maturity date; used when bond has an irregular last coupon period. In the absence of a specified FirstCouponDate, a specified LastCouponDate determines the coupon structure of the bond. The coupon structure of a bond is truncated at the LastCouponDate, regardless of where it falls, and is followed only by the bond's maturity cash flow date.

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

StartDate

Date when a bond actually starts (the date from which a bond cash flow is considered). To make an instrument forward-starting, specify this date as a future date.

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

Face

Face or par value.

 Note:   CouponRate and Face can 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 or cell array, where the first column is dates and the second column is associated rates. The date indicates the last day that the coupon rate or face value is valid.

Default: 100

### Parameter–Value Pairs

Enter the following inputs only as parameter/value pairs.

 AdjustCashFlowsBasis Adjust the cash flows based on the actual period day count. NINST-by-1 of logicals. Default: False BusinessDayConvention Require payment dates to be business dates. NINST-by-1 cell array with possible choices of business day convention:actual followmodifiedfollowpreviousmodifiedprevious Default: actual CompoundingFrequency Compounding frequency for yield calculation. Default: SIA bases (0-7) and BUS/252 use a semiannual compounding convention and ISMA bases (8-12) use an annual compounding convention. DiscountBasis Basis used to compute the discount factors for computing the yield. If you use ISMA day counts and BUS/252, the specified basis are used. Default: SIA bases use the actual/actual day count to compute discount factors. Holidays Holidays used for business day convention. NHOLIDAYS-by-1 of MATLAB® date numbers. Default: If no dates are specified, holidays.m is used. PrincipalType Type of principal for case when a Face schedule is specified. The principal type is either sinking or bullet. If sinking, principal cash flows are returned throughout the life of the bond. If bullet, principal cash flow is only returned at maturity. Default: sinking

## Output Arguments

CFlowAmounts

Cash flow matrix of a portfolio of bonds. Each row represents the cash flow vector of a single bond. Each element in a column represents a specific cash flow for that bond.

CFlowDates

Cash flow date matrix of a portfolio of bonds. Each row represents a single bond in the portfolio. Each element in a column represents a cash flow date of that bond.

TFactors

Matrix of time factors for a portfolio of bonds. 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 help determine the present value of a stream of cash flows. The term time factor refers to the exponent TF in the discounting equation

$PV=\sum _{i=1}^{n}\left(\frac{CF}{{\left(1+\frac{z}{f}\right)}^{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 input Basis for Basis values 8 to 12.

 Note:   The Basis is always used to compute accrued interest.

CFlowFlags

Matrix of cash flow flags for a portfolio of bonds. 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

CFPrincipal contains the principal cash flows. If PrincipalType is bullet, CFPrincipal is all zeros and, at Maturity, the appropriate Face value.

## Definitions

The elements contained in the cfamounts 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.

## Examples

expand all

### 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 =

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

CFlowDates =

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

TFactors =

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

CFlowFlags =

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, ...
```
```CFlowAmounts =

Columns 1 through 7

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

Column 8

101.5000
NaN

CFlowDates =

Columns 1 through 6

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

Columns 7 through 8

734761      734852
NaN         NaN

TFactors =

Columns 1 through 7

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

Column 8

3.0778
NaN

CFlowFlags =

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]}
cfamounts(CouponSchedule,'01-Mar-2011','15-Mar-2015' )
```
```CouponSchedule =

[3x2 double]

ans =

Columns 1 through 7

-1.8453    2.0000    2.0000    2.0000    2.5000    2.5000    3.0000

Columns 8 through 10

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]}
cfamounts(.05,'01-Mar-2011','15-Mar-2015', 'Face', FaceSchedule)
```
```FaceSchedule =

[3x2 double]

ans =

Columns 1 through 7

-2.3066    2.5000    2.5000   12.5000    2.2500   12.2500    2.0000

Columns 8 through 10

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 =

Columns 1 through 7

-1.5217    2.5000    2.5000    2.5000    2.5000    2.5000   12.5000
-1.5217    2.5000    2.5000    2.5000    2.5000    2.5000   12.5000

Columns 8 through 11

2.2500   92.2500       NaN       NaN
2.2500   12.2500    2.0000   82.0000

CFDates =

Columns 1 through 6

734446      734518      734699      734883      735065      735249
734446      734518      734699      734883      735065      735249

Columns 7 through 11

735430      735614      735795         NaN         NaN
735430      735614      735795      735979      736160

TFactors =

Columns 1 through 7

0    0.3913    1.3913    2.3913    3.3913    4.3913    5.3913
0    0.3913    1.3913    2.3913    3.3913    4.3913    5.3913

Columns 8 through 11

6.3913    7.3913       NaN       NaN
6.3913    7.3913    8.3913    9.3913

CFFlags =

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

CFPrincipal =

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

```

## References

Krgin, Dragomir, Handbook of Global Fixed Income Calculations, John Wiley & Sons, 2002.

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

Stigum, Marcia, and Franklin Robinson, Money Market and Bond Calculations, McGraw-Hill, 1996.