|On this page…|
Since virtually all financial data is dated or derives from a time series, financial functions must have extensive date-handling capabilities. You most often work with date strings (14-Sep-1999) when dealing with dates. Financial Toolbox™ software works internally with serial date numbers (for example, 730377). A serial date number represents a calendar date as the number of days that has passed since a fixed base date. In MATLAB® software, serial date number 1 is January 1, 0000 A.D. 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 date number 730377.75.
Note If you specify a two-digit year, MATLAB assumes that the year lies within the 100-year period centered about the current year. See the function datenum for specific information. MATLAB internal date handling and calculations generate no ambiguous values. However, whenever possible, programmers should use serial date numbers or date strings containing four-digit years.
Many toolbox functions that require dates accept either date strings or serial date numbers. If you are dealing with a few dates at the MATLAB command-line level, date strings are more convenient. If you are using toolbox functions on large numbers of dates, as in analyzing large portfolios or cash flows, performance improves if you use date numbers.
The Financial Toolbox software provides functions that convert date strings to serial date numbers, and vice versa.
Functions that convert between date formats are
Displays a numeric matrix with date entries formatted as date strings
Converts a date string to a serial date number
Converts a serial date number to a date string
Converts MATLAB serial date number to Excel® serial date number
Converts Excel serial date number to MATLAB serial date number
Another function, datevec, converts a date number or date string to a date vector whose elements are [Year Month Day Hour Minute Second]. Date vectors are mostly an internal format for some MATLAB functions; you would not often use them in financial calculations.
The datenum function is important for using Financial Toolbox software efficiently. datenum takes an input string in any of several formats, with 'dd-mmm-yyyy', 'mm/dd/yyyy' or 'dd-mmm-yyyy, hh:mm:ss.ss' most common. The input string can have up to six fields formed by letters and numbers separated by any other characters:
The day field is an integer from 1 through 31.
The month field is either an integer from 1 through 12 or an alphabetical string 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 about the current year; if the year is omitted, the current year is used as the default.
The hours, minutes, and seconds fields are optional. They are integers separated by colons or followed by 'am' or 'pm'.
For example, if the current year is 1999, then these are all equivalent
'17-May-1999' '17-May-99' '17-may' 'May 17, 1999' '5/17/99' '5/17'
and both of these represent the same time.
'17-May-1999, 18:30' '5/17/99/6:30 pm'
Note that the default format for numbers-only input follows the American convention. Thus 3/6 is March 6, not June 3.
With datenum you can convert dates into serial date format, store them in a matrix variable, 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
bndprice(Yield, CouponRate, Settle, Maturity)
Alternatively, convert date strings to serial date numbers directly in the function input argument list.
bndprice(0.07, 0.08, datenum('17-May-2000'),... datenum('01-Oct-2000'))
bndprice is an example of a function designed to detect the presence of date strings and make the conversion automatically. For these functions date strings may be passed directly.
bndprice(0.07, 0.08, '17-May-2000', '01-Oct-2000')
The decision to represent dates as either date strings or serial date numbers is often a matter of convenience. For example, when formatting data for visual display or for debugging date-handling code, it is often much easier to view dates as date strings because serial date numbers are difficult to interpret. Alternatively, serial date numbers are just another type of numeric data, and can be placed in a matrix along with any other numeric data for convenient manipulation.
Remember that if you create a vector of input date strings, use a column vector and be sure all strings are the same length. Fill with spaces or zeros. See Matrices of String Input.
The function datestr converts a serial date number to one of 19 different date string output formats showing date, time, or both. The default output for dates is a day-month-year string, for example, 24-Aug-2000. This function is quite 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 = 730693
ans = 730693.48
The MATLAB function date returns a string for today's date.
ans = 26-Jul-2000
The Financial Toolbox software provides many functions for determining specific dates, including functions which account for holidays and other nontrading days. For example, you schedule an accounting procedure for the last Friday of every month. The lweekdate function returns those dates for 2000; the 6 specifies Friday.
Fridates = lweekdate(6, 2000, 1:12); Fridays = datestr(Fridates)
Fridays = 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
Or your company closes on Martin Luther King Jr. Day, which is the third Monday in January. The nweekdate function determines those dates for 2001 through 2004.
MLKDates = nweekdate(3, 2, 2001:2004, 1); MLKDays = datestr(MLKDates)
MLKDays = 15-Jan-2001 21-Jan-2002 20-Jan-2003 19-Jan-2004
Accounting for holidays and other nontrading days is important when examining financial dates. The Financial Toolbox software provides the holidays function, which contains holidays and special nontrading days for the New York Stock Exchange between 1950 and 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 StartDate and EndDate, inclusive.
In this example, you can use holidays to determine the standard holidays in the last half of 2000:
LHHDates = holidays('1-Jul-2000', '31-Dec-2000'); LHHDays = datestr(LHHDates)
LHHDays = 04-Jul-2000 04-Sep-2000 23-Nov-2000 25-Dec-2000
Now use the toolbox busdate function to determine the next business day after these holidays.
LHNextDates = busdate(LHHDates); LHNextDays = datestr(LHNextDates)
LHNextDays = 05-Jul-2000 05-Sep-2000 24-Nov-2000 26-Dec-2000
The toolbox also provides the cfdates function to determine cash-flow dates for securities with periodic payments. This function accounts for the coupons per year, the day-count basis, and the end-of-month rule. For example, to determine the cash-flow dates for a security that pays four coupons per year on the last day of the month, on an actual/365 day-count basis, just enter the settlement date, the maturity date, and the parameters.
PayDates = cfdates('14-Mar-2000', '30-Nov-2001', 4, 3, 1); PayDays = datestr(PayDates)
PayDays = 31-May-2000 31-Aug-2000 30-Nov-2000 28-Feb-2001 31-May-2001 31-Aug-2001 30-Nov-2001