A mondate represents a date as a numeric equalling
the number of months since the beginning of
the current millennium (the "mondate epoch").
Somewhat arbitrarily,
and at the risk of reopening a decade-old debate,
"the beginning of the current millennium"
is defined as the instant between December 31, 1999
and January 1, 2000.
The need for a "mondate" class arises in the area of actuarial analysis,
and other areas of financial modeling that need to reconcile
to a company's book of accounts.
Its motivation is based on the following presumptions:
Business accounting-wise, the closing of the books for a month,
quarter, and year are the important milestones for measuring time.
For accountants – and actuaries – it is usually not important
to measure events on an hourly basis.
All events that occur during a business day, up to and including
the closing of the books for a day, are all "accounted for" as
having occurred "at the same time."
To appreciate the difficulty in measuring the passage of time in days,
note that there are typically three fewer days in the first half of the year
(January 1 through June 30) than there are in the second half.
Yet accountants will say that on June 30th the year is half over.
For another example,
note that –
with the exception of July/August and December/January –
the same days of the month for two consecutive months are not
one "month" apart if measured in days because, with those exceptions,
consecutive months contain differing numbers of days,
so which of the two months do you choose as the yardstick?
Since changes in accounts over the course of a month, quarter and year
are the amounts by which financial results are measured,
it is important to be able to measure the passage of time
where a year is comprised of twelve months of equal "accounting weight."
That gives rise to a date as measured in months, coined "mondate".
A mondate is simply a real number whose fractional part represents
the fraction of the month as of the end of the day.
E.g., the fractional part of January 1st = 1/31; the fractional part of
February 1st = 1/28 or 1/29, depending on the year.
A mondate which is a whole number
(i.e., no fractional part) corresponds to a month
that is fully completed, whose subsequent month has not yet begun;
i.e., the instant in time between
one month and the next.
The length of time (in months) between mondate x and
mondate y is simply y-x.
An interval of time is represented in a mathematical sense
by the half-open/half-closed
interval (x,y].
For example, calendar year 2009 is
the interval
(2008-12-31, 2009-12-31]
i.e., all
events after the close of business 2008-12-31
and through and including the close
of business 2009-12-31.
The mondate vector
c(mondate("2008-12-31"), mondate("2009-12-31"))
could be used to represent such an interval.
A mondate allows "infinite dates",
which are helpful constructs for modeling "ultimate" events
in actuarial, longitudinal, and time series analyses
(see the mondate method for signature "numeric").
A mondate has two important properties (in S4 parlance, "slots").
The first is displayFormat which is the format
of the date when the mondate is printed or shown.
The other is timeunits which is the "units" reported
when date arithmetic is performed.
The default units is "months", but "years" and "days" are also allowed,
in which case the difference of two dates, say, would be reported
in "years" or "days", respectively.
Objects from the Class
Objects can be created by calls of the form mondate(x, ...).
Slots
.Data:
Object of class "numeric" or a numeric array
displayFormat:
Object of class "character".
The is the format of the date when displayed.
Currently, there are four choices:
"
"
"
"
Currently, the default displayFormat for a "United States" locale is
mm/dd/YYYY ("
in all other locales YYYY-mm-dd ("
The default can be changed to another format
using options(mondate.displayFormat = myFormat).
See Examples.
timeunits:
Object of class "character"
There are three options:
"months":
the default
"years":
although it is assumed that "month"
is the fundamental unit of time,
sometimes it is more convenient to report the result of
date arithmetic in terms of "years",
for example, in actuarial analyses when
events are measured over the course of years, not months.
Of course, one "year" = twelve "months".
"days":
mostly for convenience when the number of days
between events needs to be reported.
Of course, unlike with "years", there is no simple relationship
between "days" and "months" – it depends on the month and year of
the date.
If the fundamental unit of time for a particular problem
is "days", not "months", then a different date class
(e.g., class Date) might be a better tool for modeling
the passage of time for that problem.
The default can be changed to a different unit
using the options(mondate.timeunits = myUnits) command.
See Examples.
formatFUN:
Object of class "funcNULL"
Use this slot to store a function to format a mondate.
See Examples.
Extends
Class c("numeric","array"), from data part.
Author(s)
Dan Murphy
References
For information about how month-based time measurement can help with
standardizing rates of return, see Damien Laker,
"Time Calculations for Annualizing Returns:
the Need for Standardization,"
The Journal of Performance Measurement, Summer 2008, pp. 45-54.
See Also
yearmon in the zoo package.
Examples
# See the code{mondate-methods} section for an
# explanation of the code{mondate} method below.
# January 1, 2010 in US displayFormat
mondate("1-1-2010")
# generate 10 random dates in calendar year 2000; will be
# displayed in local format
mondate(runif(10,0,12))
# Change the default format so that the character representation of the date
# sorts in chronological order.
options(mondate.displayFormat = "%Y-%m-%d")
# January
mondate(runif(10,0,12))
# generate 10 random dates in calendar year 2010;
# date arithmetic results will be reported in units of "years"
mondate(10+runif(10),timeunits="years")