README.md

In chiefmurph/mondate: Keep track of dates in terms of months

mondate

mondate is an R package that keeps track of dates in units of elapsed fractional months. mondate is motivated by Damien Laker's 2008 paper "Time Calculations for Annualizing Returns: the Need for Standardization" in The Journal of Performance Measurement.

zoo has similar functionality via the 'frac=' argument of as.Date.yearmon.

Beginning of the day or end of the day?

R's Date class identifies a calendar day with a numeric value corresponding to the beginning of the day. This agrees with an ISO-8601 recommendation, which itself conforms with the tradition of identifying a scientific experiment with the date it begins. mondate, on the other hand, adopts the accounting perspective that measures actual performance in hindsight, using words such as "as of January" or "as of year end."

Under the hood

The numeric value in a Date or POSIX object is the number of seconds since the beginning of UNIX. The numeric value in a mondate object is the number of elapsed months since the end of 1999. It's easier to quickly see that mondate(12) equals year end 2000 than to have to remember when UNIX was invented.

Date format

If you instantiate mondates using the international standard YYYY-MM-DD, it will assume that's how you want to show them later. If instantiated in US format MM/DD/YYYY, it will show them that way. If you don't specify the format -- mondate(12) for example -- mondate will attempt to determine your preference by reading something from your OS. But that is a difficult feature for this author to test as they have not yet had the opportunity to maintain mondate ouside North America.

Arithmetic

The difference between two mondates is the number of months between those days. That makes it easy to measure the age of an accounting object relative to the month or year it arose. For instance, the distance between two year-end accounting statements is always a multiple of 12. A year equals 12 months in mondate by definition.

However, specifying the beginning date for mondate's arithmetic can trip up a user. The reason is perhaps best explained with a simple word problem.

Your son Jacob was born on January 1, 2021. How old will Jacob be at the end of the year? Isn't that just

mondate("12/31/2021") - mondate("1/1/2021")

No, that will be one thirty-firsts of a month short because mondate("1/1/2021") corresponds to the end of January 1st, not the beginning. To measure the age from the beginning of a period to the end of another period, use

mondate(end_of_period) - mondate(day_before(beginning_of_period))

where day_before(Date) = Date - 1 for objects of class Date.

Homework

What is the numeric value under the hood of mondate("1/1/2021")? (Hint: There are 31 days in January.)

Check that your answer equals 21*12+1/31 with as.numeric(mondate("1/1/2021")).

chiefmurph/mondate documentation built on Aug. 29, 2022, 4:13 p.m.