cfdates

Cash flow dates for fixed-income security

Syntax

CFlowDates = cfdates(Settle,Maturity)

CFlowDates = cfdates(___,Period,Basis,EndMonthRule,IssueDate,FirstCouponDate,LastCouponDate)

Description

CFlowDates = cfdates(Settle,Maturity) generates a matrix of actual cash flow payment dates for NUMBONDS fixed income securities. All cash flow dates are determined regardless of whether the first and last coupon periods are normal, long or short.

CFlowDates = cfdates(___,Period,Basis,EndMonthRule,IssueDate,FirstCouponDate,LastCouponDate) specifies options using one or more optional arguments in addition to the input arguments in the previous syntax.

Examples

Obtain Cash Flow Dates for Fixed-Income Security

Compute the cash flow dates given the Settle and Maturity dates.

CFlowDates = cfdates('14 Mar 1997', '30 Nov 1998', 2, 0, 1)

CFlowDates = 1×4

      729541      729724      729906      730089

datestr(CFlowDates)

ans = 4x11 char array
    '31-May-1997'
    '30-Nov-1997'
    '31-May-1998'
    '30-Nov-1998'

If any of the inputs for Settle, Maturity, IssueDate, FirstCouponDate, or LastCouponDate are datetime arrays, then CFlowDates is returned as a datetime array. For example:

CFlowDates = cfdates('14-Mar-1997', datetime('30-Nov-1998','Locale','en_US'), 2, 0, 1)

CFlowDates = 1x4 datetime
   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 = 3×4

      729480      729663         NaN         NaN
      729510      729694      729875      730059
      729541      729724      729906      730089

To look at the cash-flow dates for the last security:

datestr(CFlowDates(3,:))

ans = 4x11 char array
    '31-May-1997'
    '30-Nov-1997'
    '31-May-1998'
    '30-Nov-1998'

Input Arguments

Settle — Settlement date

cell array of date character vectors | vector of serial date numbers | datetime array

Settlement date, specified as an NINST-by-1 vector using serial date numbers, cell array of date character vectors, or a datetime array. Settle must be earlier than Maturity.

Data Types: double | char | cell | datetime

Maturity — Maturity date

cell array of date character vectors | vector of serial date numbers | datetime array

Maturity date, specified as an NINST-by-1 vector using serial date numbers, cell array of date character vectors, or a datetime array.

Data Types: double | char | cell | datetime

Period — Coupons per year of the bond

2 (semiannual) (default) | vector of positive integers from the set [1,2,3,4,6,12]

(Optional) Coupons per year of the bond, specified as a vector of positive integers from the set [1,2,3,4,6,12].

Data Types: double

Basis — Day-count basis

0 (actual/actual) (default) | positive integers of the set [1...13] | vector of positive integers of the set [1...13]

(Optional) Day-count basis, specified as positive integers using a NINST-by-1 vector.

• 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

(Optional) End-of-month rule flag, specified as a scalar or a NUMBONDS-by-1 or 1-by-NUMBONDS 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

cash flow payment dates are determined from other inputs (default) | serial date number | date character vector | datetime

(Optional) Bond Issue date, specified as a scalar or a NUMBONDS-by-1 or 1-by-NUMBONDS vector using serial date numbers, date character vectors, or datetime arrays.

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

cash flow payment dates are determined from other inputs (default) | serial date number | date character vector | datetime

Irregular or normal first coupon date, specified as a scalar or a NUMBONDS-by-1 or 1-by-NUMBONDS 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.

Data Types: double | char | datetime

LastCouponDate — Irregular or normal last coupon date

cash flow payment dates are determined from other inputs (default) | serial date number | date character vector | datetime

Irregular or normal last coupon date, specified as a scalar or a NUMBONDS-by-1 or 1-by-NUMBONDS vector using serial date numbers, date character vectors, or datetime arrays.

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

Data Types: double | char | datetime

Output Arguments

CFlowDates — Actual cash flow payment dates

matrix

Actual cash flow payment dates, returned as a N-row matrix of dates in serial date format or datetime format (if any inputs are in datetime format). CFlowDates has NUMBONDS rows and the number of columns is determined by the maximum number of cash flow payment dates required to hold the bond portfolio. NaNs are padded for bonds which have less than the maximum number of cash flow payment dates. Use the function datestr to convert serial date numbers to formatted date character vectors.

If all of the inputs for Settle, Maturity, IssueDate, FirstCouponDate, or LastCouponDate are either serial date numbers or date character vectors, then CFlowDates is returned as a serial date number.

If any of the inputs for Settle, Maturity, IssueDate, FirstCouponDate, or LastCouponDate are datetime arrays, then CFlowDates is returned as a datetime array.

Note

The cash flow flags for a portfolio of bonds were formerly available as the cfdates second output argument, CFlowFlags. You can now use cfamounts to get these flags. If you specify a CFlowFlags argument, cfdates displays a message directing you to use cfamounts.