date2time

Time and frequency from dates

Syntax

[TFactors,F] = date2time(Settle,Maturity)

[TFactors,F] = date2time(___,Compounding,Basis,EndMonthRule)

Description

[TFactors,F] = date2time(Settle,Maturity) computes time factors appropriate to compounded rate quotes between the Settle and Maturity dates. date2time is the inverse of time2date.

[TFactors,F] = date2time(___,Compounding,Basis,EndMonthRule) computes time factors appropriate to compounded rate quotes between the Settle and Maturity dates using optional input arguments for Compounding, Basis, and EndMonthRule. date2time is the inverse of time2date.

Examples

Compute date2time Using an actual/actual Basis

To get the date2time period between '31-Jul-2015' and '30-Sep-2015' using an actual/actual basis:

date2time(datetime(2015,7,31),datetime(2015,9,30), 2, 0, 1)

ans = 
0.3333

When using date2time quasi coupon, two quasi coupon dates are computed for a bond with a maturity corresponding to the Dates input. In this case, that would be "30-Sep-2015". Assuming that the compounding frequency is 2, the other quasi coupon date is six months prior to this date. Assuming the end of month rule is in place, then the other quasi coupon date is "31-Mar-2015". You can use these two dates to compute the total number of actual days in a period (which is 183). Given this, the fraction of time between the start and end date for the actual/actual basis is computed as follows.

(Actual Days between Start Date and End Date)/(Actual Number of Days between Quasi Coupon Dates)

There are 61 days between 31-Jul-2015 and 30-Sep-2015 and 183 days between the quasi coupon dates ("31-Mar-2015" and "30-Sep-2015") which leads to a final result of 61/183 or exactly 1/3.

Input Arguments

Settle — Settlement date

datetime scalar | string scalar | date character vector

Settlement date, specified as a scalar datetime, string, or date character vector.

To support existing code, date2time 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 a scalar or N-by-1 vector using a datetime array, string array, or date character vectors.

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

Data Types: char | string | datetime

Compounding — Rate at which input zero rates are compounded when annualized

2 (Semiannual compounding) (default) | scalar with numeric values of 0, 1, 2, 3, 4, 5, 6, 12, 365, –1

Rate at which input zero rates are compounded when annualized, specified as a scalar with numeric values of: 0, 1, 2, 3, 4, 5, 6, 12, 365, or –1. Allowed values are defined as:

• 0 — Simple interest (no compounding)

• 1 — Annual compounding

• 2 — Semiannual compounding (default)

• 3 — Compounding three times per year

• 4 — Quarterly compounding

• 6 — Bimonthly compounding

• 12 — Monthly compounding

• 365 — Daily compounding

• -1 — Continuous compounding

The optional Compounding argument determines the formula for the discount factors (Disc):

• Compounding = 0 for simple interest

  • Disc = 1/(1 + Z * T), where T is time in years and simple interest assumes annual times F = 1.

• Compounding = 1, 2, 3, 4, 6, 12

  • Disc = (1 + Z/F)^(-T), where F is the compounding frequency, Z is the zero rate, and T is the time in periodic units, for example, T = F is one year.

• Compounding = 365

  • Disc = (1 + Z/F)^(-T), where F is the number of days in the basis year and T is a number of days elapsed computed by basis.

• Compounding = -1

  • Disc = exp(-T*Z), where T is time in years.

Basis — Day-count basis

0 (actual/actual) (default) | numeric with value 0 through 13 | vector of numerics with values 0 through 13

Day-count basis, specified as an integer with a value 0 through 13 or a N-by-1 vector of integers with values 0 through 13.

• 0 = actual/actual (default)

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (BMA)

• 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: single | double

EndMonthRule — End-of-month rule flag for month having 30 or fewer days

1 (in effect) (default) | nonnegative integer [0,1]

End-of-month rule flag for month having 30 or fewer days, specified as scalar nonnegative integer [0, 1] or a using a N-by-1 vector of values. 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 payment date is always the same numerical day of the month.

• 1 = Set rule on, meaning that a payment date is always the last actual day of the month.

Data Types: logical

Output Arguments

TFactors — Time factors

vector

Time factors, appropriate to compounded rate quotes between Settle and Maturity dates, returned as a vector.

F — Compounding frequencies

scalar

Compounding frequencies, returned as a scalar.

More About

Difference Between yearfrac and date2time

The difference between yearfrac and date2time is that date2time counts full periods as a whole integer, even if the number of actual days in the periods are different. yearfrac does not count full periods.

For example,

yearfrac('1/1/2000', '1/1/2001', 9)

ans =

    1.0167

yearfrac for Basis 9 (ACT/360 ICMA) calculates 366/360 = 1.0167. So, even if the dates have the same month and date, with a difference of 1 in the year, the returned value may not be exactly 1. On the other hand, date2time calculates one full year period:

date2time('1/1/2000', '1/1/2001', 1, 9)

ans =

     1

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although date2time 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.