# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

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

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 `NaN`s as necessary to ensure that all rows have the same number of elements.

```[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, date character vectors, or datetime arrays. `Settle` must be earlier than `Maturity`.

`Maturity`

Maturity date. A vector of serial date numbers, date character vectors, or datetime arrays.

### 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 (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 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, specified as a serial date number, date character vector, or datetime array. `FirstCouponDate` is used when a 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, specified as a serial date number, date character vector, or datetime array. `LastCouponDate` is used when a 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, specified as a serial date number, date character vector, or datetime array, 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'` — 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. Default: `'actual'` `CompoundingFrequency` Compounding frequency for yield calculation. Possible values include: `1`, `2`, `3`, `4`, `6`, `12`. Default: SIA bases (0–7) and BUS/252 use a semiannual compounding convention and ICMA bases (8–12) use an annual compounding convention. `DiscountBasis` Basis used to compute the discount factors for computing the yield. The possible values for `DiscountBasis` are:0 = actual/actual 1 = 30/360 (SIA)2 = actual/3603 = actual/3654 = 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 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. 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 amounts. 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 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.

If all of 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. 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.

## Examples

collapse all

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

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 datatime 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 = -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 datetime array 01-Nov-1993 15-Dec-1993 15-Mar-1994 15-Jun-1994 15-Sep-1994 15-Dec-1994 01-Nov-1993 15-Dec-1993 15-Jun-1994 15-Dec-1994 15-Jun-1995 NaT ```
```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 ```

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 = -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 = 734290 734304 734396 734487 734577 734669 734761 734852 734290 734304 734487 734669 734852 735035 NaN NaN ```
```TFactors = 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 = 0 3 3 3 3 3 3 4 0 3 3 3 3 4 NaN NaN ```

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 = cell [3×2 double] ```
`cfamounts(CouponSchedule,'01-Mar-2011','15-Mar-2015' )`
```ans = -1.8453 2.0000 2.0000 2.0000 2.5000 2.5000 3.0000 3.0000 3.0000 103.0000 ```

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 = cell [3×2 double] ```
`cfamounts(.05,'01-Mar-2011','15-Mar-2015', 'Face', FaceSchedule)`
```ans = -2.3066 2.5000 2.5000 12.5000 2.2500 12.2500 2.0000 2.0000 2.0000 82.0000 ```

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 = -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 = 734446 734518 734699 734883 735065 735249 735430 735614 735795 NaN NaN 734446 734518 734699 734883 735065 735249 735430 735614 735795 735979 736160 ```
```TFactors = 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 = 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.