cfdatesq

Quasi-coupon dates for fixed-income security

Syntax

QuasiCouponDates = cfdatesq(Settle,Maturity)

QuasiCouponDates = cfdatesq(___,Period,Basis,EndMonthRule,IssueDate,FirstCouponDate,LastCouponDate,PeriodsBeforeSettle,PeriodsAfterMaturity)

Description

QuasiCouponDates = cfdatesq(Settle,Maturity) returns a matrix of quasi-coupon dates expressed in datetime format (if any inputs are in datetime format).

Successive quasi-coupon dates determine the length of the standard coupon period for the fixed-income security of interest, and do not necessarily coincide with actual coupon payment dates. Quasi-coupon dates are determined regardless of whether the first or last coupon periods are normal, long, or short.

QuasiCouponDates has NUMBONDS rows and the number of columns is determined by the maximum number of quasi-coupon dates required to hold the bond portfolio. NaNs are padded for bonds which have less than the maximum number quasi-coupon dates. By default, quasi-coupon dates after settlement and on or preceding maturity are returned. If settlement occurs on maturity, and maturity is a quasi-coupon date, then the maturity date is returned.

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

Examples

Obtain Quasi-Coupon Dates for Fixed-Income Security

Compute the quasi-coupon dates given the Settle and Maturity dates.

QuasiCouponDates = cfdatesq('14-Mar-1997', '30-Nov-1998', 2, 0, 1)

QuasiCouponDates = 1×4

      729541      729724      729906      730089

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

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

QuasiCouponDates = 1x4 datetime
   31-May-1997   30-Nov-1997   31-May-1998   30-Nov-1998

Input Arguments

Settle — Settlement date

datetime array | string array | date character vector

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

To support existing code, cfdatesq also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

Maturity — Maturity date

datetime array | string array | date character vector

Maturity date, specified as an NINST-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, cfdatesq also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | 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) | datetime array | string array | date character vector

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

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

To support existing code, cfdatesq also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

FirstCouponDate — Irregular or normal first coupon date

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

Irregular or normal first coupon date, specified as a scalar or a NUMBONDS-by-1 or 1-by-NUMBONDS vector using a datetime array, string array, or date character vectors.

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

To support existing code, cfdatesq also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

LastCouponDate — Irregular or normal last coupon date

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

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

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

To support existing code, cfdatesq also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

PeriodsBeforeSettle — Number of quasi-coupon dates on or before settlement to include

0 (default) | nonnegative integer

(Optional) Number of quasi-coupon dates on or before settlement to include, specified as a nonnegative integer.

Data Types: double

PeriodsAfterMaturity — Number of quasi-coupon dates after maturity to include

0 (default) | nonnegative integer

(Optional) Number of quasi-coupon dates after maturity to include, specified as a nonnegative integer.

Data Types: double

Output Arguments

QuasiCouponDates — Quasi-coupon dates

matrix

Quasi-coupon dates, returned as a N-row matrix of dates in datetime format (if any inputs are in datetime format). QuasiCouponDates has NUMBONDS rows and the number of columns is determined by the maximum number of quasi-coupon dates required to hold the bond portfolio. NaNs are padded for bonds which have less than the maximum number quasi-coupon dates. By default, quasi-coupon dates after settlement and on or preceding maturity are returned. If settlement occurs on maturity, and maturity is a quasi-coupon date, then the maturity date is returned.

If all of the inputs for Settle, Maturity, IssueDate, FirstCouponDate, or LastCouponDate are either strings or date character vectors, then QuasiCouponDates is returned as a serial date number. Use the function datetime to convert serial date numbers to formatted datetime arrays.

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

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although cfdatesq supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.