Handle and Convert Dates
Virtually all financial data derives from a time series, functions in Financial Toolbox™ have extensive date-handling capabilities. The toolbox functions support date or date-and-time formats as character vectors, datetime arrays, or serial date numbers.
Date character vectors are text that represent date and time, which you can use with multiple formats. For example,
'mm/dd/yyyy'are all supported text formats for a date character vector. Most often, you work with date character vectors (such as
14-Sep-1999) when dealing with dates.
Datetime arrays, created using
datetime, are the best data type for representing points in time.
datetimevalues have flexible display formats and up to nanosecond precision, and can account for time zones, daylight saving time, and leap seconds. When
datetimeobjects are used as inputs to other Financial Toolbox functions, the format of the input
datetimeobject is preserved. For example:
originalDate = datetime('now','Format','yyyy-MM-dd HH:mm:ss'); % Find the next business day b = busdate(originalDate)
b = datetime 2021-05-04 15:59:34
Serial date numbers represent a calendar date as the number of days that have passed since a fixed base date. In MATLAB® software, serial date number
1is January 1,0000 A.D. Financial Toolbox works internally with serial date numbers (such as,
730377). MATLAB also uses serial time to represent fractions of days beginning at midnight. For example, 6 p.m. equals
0.75serial days, so 6:00 p.m. on
14-Sep-1999, in MATLAB, is serial date number
If you specify a two-digit year, MATLAB assumes that the year lies within the 100-year period centered on the current year. See the function
datenum for specific information. MATLAB internal date handling and calculations generate no ambiguous values. However, whenever possible, use serial date numbers or date character vectors containing four-digit years.
Many Financial Toolbox functions that require dates as input arguments accept date character vectors, datetime arrays, or serial date numbers. If you are dealing with a few dates at the MATLAB command-line level, date character vectors are more convenient. If you are using Financial Toolbox functions on large numbers of dates, as in analyzing large portfolios or cash flows, performance improves if you use datetime arrays or serial date numbers. For more information, see Represent Dates and Times in MATLAB.
Financial Toolbox provides functions that convert date character vectors to or from serial date numbers. In addition, you can convert character vectors or serial date numbers to datetime arrays.
Functions that convert between date formats are:
Displays a numeric matrix with date entries formatted as date character vectors.
Converts a date character vector to a serial date number.
Converts a serial date number to a date character vector.
Converts from date character vectors or serial date numbers to create a datetime array.
|Converts a serial date number or date character vector to a date vector whose elements are |
Converts MATLAB serial date number to Excel® serial date number.
Converts Microsoft® Excel serial date number to MATLAB serial date number.
For more information, see Convert Between Datetime Arrays, Numbers, and Text.
Convert Between Datetime Arrays and Character Vectors
A date can be a character vector composed of fields related to a specific date and time. There are several ways to represent dates and times in several text formats. For example, all the following are character vectors represent August 23, 2010 at 04:35:42 PM:
'23-Aug-2010 04:35:06 PM' 'Wednesday, August 23' '08/23/10 16:35' 'Aug 23 16:35:42.946'
A date character vector includes characters that separate the fields, such as the hyphen, space, and colon used here:
d = '23-Aug-2010 16:35:42'
The specifiers that
datetime uses to describe date and time formats differ from the specifiers that the
datenum functions accept.
t = datetime(d,'InputFormat','dd-MMM-yyyy HH:mm:ss')
t = 23-Aug-2010 16:35:42
Although the date string,
d, and the
t, look similar, they are not equal. View the size and data type of each variable.
whos d t
Name Size Bytes Class Attributes d 1x20 40 char t 1x1 121 datetime
t = datetime('now','Format','yyyy-MM-dd''T''HHmmss')
t = datetime 2016-12-11T125628
S = char(t); filename = ['myTest_',S]
filename = 'myTest_2016-12-11T125628'
Convert Serial Date Numbers to Datetime Arrays
Serial time can represent fractions of days beginning at midnight. For example, 6 p.m. equals
0.75 serial days, so the character vector
'31-Oct-2003, 6:00 PM' in MATLAB is date number
Convert one or more serial date numbers to a
datetime array using the
datetime function. Specify the type of date number that is being converted:
t = datetime(731885.75,'ConvertFrom','datenum')
t = datetime 31-Oct-2003 18:00:00
Convert Datetime Arrays to Numeric Values
Some MATLAB functions accept numeric data types but not datetime values as inputs. To apply these functions to your date and time data, first, convert datetime values to meaningful numeric values, and then call the function. For example, the
log function accepts
double inputs but not
datetime inputs. Suppose that you have a
datetime array of dates spanning the course of a research study or experiment.
t = datetime(2014,6,18) + calmonths(1:4)
t = 1×4 datetime array 18-Jul-2014 18-Aug-2014 18-Sep-2014 18-Oct-2014
Subtract the origin value. For example, the origin value can be the starting day of an experiment.
dt = t - datetime(2014,7,1)
dt = 1×4 duration array 408:00:00 1152:00:00 1896:00:00 2616:00:00
dt is a
duration array. Convert
dt to a
double array of values in units of years, days, hours, minutes, or seconds by using the
seconds function, respectively.
x = hours(dt)
x = 408 1152 1896 2616
double array as the input to the
y = log(x)
y = 6.0113 7.0493 7.5475 7.8694
Input Conversions with
datenum function is important for using Financial Toolbox software efficiently.
datenum takes an input date character vector in any of several formats, with
'dd-mmm-yyyy, hh:mm:ss.ss' formats being the most common. The input date character vector can have up to six fields formed by letters and numbers separated by any other characters, such that:
The day field is an integer from
The month field is either an integer from
12or an alphabetical character vector with at least three characters.
The year field is a nonnegative integer. If only two numbers are specified, then the year is assumed to lie within the 100-year period centered on the current year. If the year is omitted, the current year is the default.
The hours, minutes, and seconds fields are optional. They are integers separated by colons or followed by
For example, if the current year is 1999, then all these dates are equivalent:
'17-May-1999' '17-May-99' '17-may' 'May 17, 1999' '5/17/99' '5/17'
Also, both of these formats represent the same time.
'17-May-1999, 18:30' '5/17/99/6:30 pm'
The default format for numbers-only input follows the US convention. Therefore, 3/6 is March 6, not June 3.
datenum, you can convert dates into serial date format, store them in a matrix variable, and then later pass the variable to a function. Alternatively, you can use
datenum directly in a function input argument list.
For example, consider the function
bndprice that computes the price of a bond given the yield to maturity. First set up variables for the yield to maturity, coupon rate, and the necessary dates.
Yield = 0.07; CouponRate = 0.08; Settle = datenum('17-May-2000'); Maturity = datenum('01-Oct-2000');
Then call the function with the variables.
ans = 100.3503
Alternatively, convert date character vectors to serial date numbers directly in the function input argument list.
ans = 100.3503
bndprice is an example of a function designed to detect the presence of date character vectors and make the conversion automatically. For functions like
bndprice, date character vectors can be passed directly.
ans = 100.3503
The decision to represent dates as either date character vectors or serial date numbers is often a matter of convenience. For example, when formatting data for visual display or for debugging date-handling code, you can view dates more easily as date character vectors because serial date numbers are difficult to interpret. Alternately, serial date numbers are just another type of numeric data, which you can place in a matrix along with any other numeric data for convenient manipulation.
Remember that if you create a vector of input date character vectors, use a column vector, and be sure that all character vectors are the same length. To ensure that the character vectors are the same length, fill the character vectors with spaces or zeros. For more information, see Character Vector Input.
Output Conversions with
datestr function converts a serial date number to one of 19 different date character vector output formats showing date, time, or both. The default output for dates is a day-month-year character vector, for example,
datestr function is useful for preparing output reports.
month, three letters
month, single letter
day of month
day of week, three letters
day of week, single letter
year, four numbers
year, two numbers
hour:minute:second AM or PM
hour:minute AM or PM
Current Date and Time
ans = 736675
ans = 7.3668e+05
The MATLAB function
date returns a character vector for the current date.
ans = '11-Dec-2016'
Determining Specific Dates
Financial Toolbox provides many functions for determining specific dates. For example, assume that you schedule an accounting procedure for the last Friday of every month. Use the
lweekdate function to return those dates for the year 2000. The input argument
6 specifies Friday.
Fridates = lweekdate(6,2000,1:12); Fridays = datestr(Fridates)
Fridays = 12×11 char array '28-Jan-2000' '25-Feb-2000' '31-Mar-2000' '28-Apr-2000' '26-May-2000' '30-Jun-2000' '28-Jul-2000' '25-Aug-2000' '29-Sep-2000' '27-Oct-2000' '24-Nov-2000' '29-Dec-2000'
Another example of needing specific dates could be that your company closes on Martin Luther King Jr. Day, which is the third Monday in January. You can use the
nweekdate function to determine those specific dates for 2011 through 2014.
MLKDates = nweekdate(3,2,2011:2014,1); MLKDays = datestr(MLKDates)
MLKDays = 4×11 char array '17-Jan-2011' '16-Jan-2012' '21-Jan-2013' '20-Jan-2014'
Accounting for holidays and other nontrading days is important when you examine financial dates. Financial Toolbox provides the
holidays function, which contains holidays and special nontrading days for the New York Stock Exchange from 1950 through 2030, inclusive. In addition, you can use
nyseclosures to evaluate all known or anticipated closures of the New York Stock Exchange from January 1, 1885, to December 31, 2050.
nyseclosures returns a vector of serial date numbers corresponding to market closures between the dates
In this example, use
holidays to determine the standard holidays in the last half of 2012.
LHHDates = holidays('1-Jul-2012','31-Dec-2012'); LHHDays = datestr(LHHDates)
LHHDays = 6×11 char array '04-Jul-2012' '03-Sep-2012' '29-Oct-2012' '30-Oct-2012' '22-Nov-2012' '25-Dec-2012'
You can then use the
busdate function to determine the next business day in 2012 after these holidays.
LHNextDates = busdate(LHHDates); LHNextDays = datestr(LHNextDates)
LHNextDays = 6×11 char array '05-Jul-2012' '04-Sep-2012' '31-Oct-2012' '31-Oct-2012' '23-Nov-2012' '26-Dec-2012'
Determining Cash-Flow Dates
To determine cash-flow dates for securities with periodic payments, use
cfdates. This function accounts for the coupons per year, the day-count basis, and the end-of-month rule. For example, you can determine the cash-flow dates for a security that pays four coupons per year on the last day of the month using an
actual/365 day-count basis. To do so, enter the settlement date, the maturity date, and the parameters for
PayDates = cfdates('14-Mar-2000','30-Nov-2001',4,3,1); PayDays = datestr(PayDates)
PayDays = 7×11 char array '31-May-2000' '31-Aug-2000' '30-Nov-2000' '28-Feb-2001' '31-May-2001' '31-Aug-2001' '30-Nov-2001'
- Convert Between Datetime Arrays, Numbers, and Text
- Read Collection or Sequence of Spreadsheet Files
- Trading Calendars User Interface
- UICalendar User Interface
- Convert Dates Between Microsoft Excel and MATLAB (Spreadsheet Link)