Cash flow dates for a fixed-income security.
Syntax
[CFlowDates, CFlowFlags] = cfdates(Settle, Maturity, Period, Basis,
EndMonthRule, IssueDate, FirstCouponDate, LastCouponDate,
StartDate)
Arguments
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
|
Coupons per year of the bond. A vector of integers. Allowed values are 1, 2, 3, 4, 6, and 12. Default = 2.
|
Basis
| Day-count basis of the bond. A vector of integers.
0 = actual/actual (default), 1 = 30/360, 2 = actual/360,
3 = actual/365.
|
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'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
|
Date when a bond was issued.
|
FirstCouponDate
|
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
|
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
|
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.
|
Settle and Maturity are required arguments. All others are optional.
Required arguments must be N-by-1 or 1-by-N conforming vectors or scalars. Optional arguments must be either N-by-1 or 1-by-N conforming vectors, scalars, or empty matrices.
Any input can contain multiple values, but if so, all other inputs must contain the same number of values or a single value that applies to all. For example, if Maturity contains N dates, then Settle must contain N dates or a single date.
Description
[CFlowDates, CFlowFlags] = cfdates(Settle, Maturity, Period, Basis,
EndMonthRule, IssueDate, FirstCouponDate, LastCouponDate,
StartDate)
returns a matrix of cash flow dates for a bond or set of bonds. cfdates determines all cash flow dates for a bond whether or not the coupon payment structure is normal or the first and/or last coupon period is long or short.
CFlowDates is an N-row matrix of serial date numbers, padded with NaNs as necessary to ensure that all rows have the same number of elements. Use the function datestr to convert serial date numbers to formatted date strings.
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.
|
Examples
CFlowDates = cfdates('14 Mar 1997', '30 Nov 1998', 2, 0, 1)
CFlowDates =
729541 729724 729906 730089
datestr(CFlowDates)
ans =
31-May-1997
30-Nov-1997
31-May-1998
30-Nov-1998
Given three securities with different maturity dates and the same default arguments:
Maturity = ['30-Sep-1997'; '31-Oct-1998'; '30-Nov-1998'];
CFlowDates = cfdates('14-Mar-1997', Maturity)
CFlowDates =
729480 729663 NaN NaN
729510 729694 729875 730059
729541 729724 729906 730089
Look at the cash-flow dates for the last security:
datestr(CFlowDates(3,:))
ans =
31-May-1997
30-Nov-1997
31-May-1998
30-Nov-1998
See Also
accrfrac,cpncount,cpndaten,cpndatep,cpndaysn,cpndaysp,cpnpersz
[ Previous | Help Desk | Next ]