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
Datetime arrays, created using
datetime, are the best data type for
representing points in time.
datetime values have
flexible display formats and up to nanosecond precision, and can account
for time zones, daylight saving time, and leap seconds.
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
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.75 serial days, so
6:00 p.m. on
14-Sep-1999, in MATLAB, is serial
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
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 (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 (MATLAB).
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
t = datetime(d,'InputFormat','dd-MMM-yyyy HH:mm:ss')
t = 23-Aug-2010 16:35:42
Although the date string,
d, and the
look similar, they are not equal. View the size and data type of each
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'
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
Convert one or more serial date numbers to a
Specify the type of date number that is being converted:
t = datetime(731885.75,'ConvertFrom','datenum')
t = datetime 31-Oct-2003 18:00:00
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
double inputs but not
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
dt to a
of values in units of years, days, hours, minutes, or seconds by using
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
is important for using Financial Toolbox software efficiently.
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
The day field is an integer from
The month field is either an integer from
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
datenum directly in
a function input argument list.
For example, consider the function
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
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 Matrices of Character Vector Input.
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
ans = 736675
ans = 7.3668e+05
The MATLAB function
date returns a character
vector for the current date.
ans = '11-Dec-2016'
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
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
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.
a vector of serial date numbers corresponding to market closures between
In this example, use
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
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'
To determine cash-flow dates for securities with periodic payments,
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
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'