cfamounts (Financial Toolbox)

Cash flow and time mapping for bond portfolio (SIA compliant)

Syntax

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

Arguments

CouponRate
Decimal number indicating the annual percentage rate used to determine the coupons payable on a bond.

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

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

Period
(Optional) Coupons per year of the bond. A vector of integers. Allowed values are 0, 1, 2, 3, 4, 6, and 12. Default = 2.

Basis
(Optional) Day-count basis of the bond. A vector of integers. 0 = actual/actual (default), 1 = 30/360, 2 = actual/360, 3 = actual/365.

EndMonthRule
(Optional) 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's coupon payment date is always the same numerical day of the month. 1 = set rule on (default), meaning that a bond's coupon payment date is always the last actual day of the month.

IssueDate
(Optional) Date when a bond was issued.

FirstCouponDate
(Optional) Date when a bond makes its first coupon payment. When FirstCouponDate and LastCouponDate are both specified, FirstCouponDate takes precedence in determining the coupon payment structure.

LastCouponDate
(Optional) Last coupon date of a bond prior to the maturity date. 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 will be followed only by the bond's maturity cash flow date.

StartDate
(Future implementation; optional) Date when a bond actually starts (the date from which a bond's cash flows can be considered). To make an instrument forward-starting, specify this date as a future date. If StartDate is not explicitly specified, the effective start date is the settlement date.

Face
(Optional) Face or par value. Default = 100.

`CouponRate`	Decimal number indicating the annual percentage rate used to determine the coupons payable on a bond.
`Settle`	Settlement date. A vector of serial date numbers or date strings. `Settle` must be earlier than or equal to `Maturity`.
`Maturity`	Maturity date. A vector of serial date numbers or date strings.
`Period`	(Optional) Coupons per year of the bond. A vector of integers. Allowed values are 0, 1, 2, 3, 4, 6, and 12. Default = 2.
`Basis`	(Optional) Day-count basis of the bond. A vector of integers. 0 = actual/actual (default), 1 = 30/360, 2 = actual/360, 3 = actual/365.
`EndMonthRule`	(Optional) 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's coupon payment date is always the same numerical day of the month. 1 = set rule on (default), meaning that a bond's coupon payment date is always the last actual day of the month.
`IssueDate`	(Optional) Date when a bond was issued.
`FirstCouponDate`	(Optional) Date when a bond makes its first coupon payment. When `FirstCouponDate` and `LastCouponDate` are both specified, `FirstCouponDate` takes precedence in determining the coupon payment structure.
`LastCouponDate`	(Optional) Last coupon date of a bond prior to the maturity date. 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 will be followed only by the bond's maturity cash flow date.
`StartDate`	(Future implementation; optional) Date when a bond actually starts (the date from which a bond's cash flows can be considered). To make an instrument forward-starting, specify this date as a future date. If `StartDate` is not explicitly specified, the effective start date is the settlement date.
`Face`	(Optional) Face or par value. Default = 100.

Required arguments must be number of bonds (NUMBONDS) by 1 or 1-by-NUMBONDS conforming vectors or scalars. Optional arguments must be either NUMBONDS-by-1 or 1-by-NUMBONDS conforming vectors, scalars, or empty matrices.

Description

[CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = 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. The elements contained in 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 is zero in the case of all zero coupon bonds. This function 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 is the 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 is the 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 is the 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 are useful in determining the present value of a stream of cash flows. The term "time factor" refers to the exponent TF in the discounting equation

```
PV = CF / (1 + z/2)^TF
```

where:

PV =
present value of a cash flow

CF =
the cash flow amount

z =
the risk-adjusted annualized rate or yield corresponding to given cash flow. The yield is quoted on a semi-annual basis.

TF =
time factor for a given cash flow. Time is measured in semi-annual periods from the settlement date to the cash flow date.

`PV =`	present value of a cash flow
`CF =`	the cash flow amount
`z =`	the risk-adjusted annualized rate or yield corresponding to given cash flow. The yield is quoted on a semi-annual basis.
`TF =`	time factor for a given cash flow. Time is measured in semi-annual periods from the settlement date to the cash flow date.

CFlowFlags is the 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 (e.g., nominal coupon cash flow, front or end partial or "stub" coupon, maturity cash flow). Possible values are shown in the table.

Flag
Cash Flow Type

0
Accrued interest due on a bond at settlement.

1
Initial cash flow amount smaller than normal due to "stub" coupon period. A stub period is created when the time from issue date to first coupon is shorter than normal.

2
Larger than normal initial cash flow amount because 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 abnormally short and actual maturity cash flow is smaller than normal).

6
Larger than normal maturity cash flow because 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 bond has less than one coupon period to maturity.

9
Larger than normal maturity cash flow when bond has less than one coupon period to maturity.

10
Maturity cash flow on a zero coupon bond.

Flag	Cash Flow Type
`0`	Accrued interest due on a bond at settlement.
`1`	Initial cash flow amount smaller than normal due to "stub" coupon period. A stub period is created when the time from issue date to first coupon is shorter than normal.
`2`	Larger than normal initial cash flow amount because 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 abnormally short and actual maturity cash flow is smaller than normal).
`6`	Larger than normal maturity cash flow because 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 bond has less than one coupon period to maturity.
`9`	Larger than normal maturity cash flow when bond has less than one coupon period to maturity.
`10`	Maturity cash flow on a zero coupon bond.

Examples

Consider a portfolio containing a corporate bond paying interest quarterly and a treasury bond paying interest semi-annually. Compute the cash flow structure and the time factors for each bond.

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

See Also

accrfrac, cfdates, cpncount, cpndaten, cpndatenq, cpndatep, cpndatepq, cpndaysn, cpndaysp, cpnpersz

candle cfconv