In chiefmurph/mondate: Keep track of dates in terms of months
Dates and date arithmetic are implemented in
R
using international standards.
The interpretation of
those standards
in an accounting context can often be difficult
and sometimes misleading,
particularly with respect to
identifying "closing dates"
and date arithmetic measured in units of months and years.
The following example sentences are found throughout Financial Services:
A. The value of ABC Company liabilities as of December 31, 2015 is $100M.
B. The age of November receivables as of December 31, 2015 is two months.
The "asof" and "emonth" packages were written to simplify the modeling of these
two sentences in
R.
Package asof
Accounting Date
Definition: Accounting Date
An accounting date is the cutoff date for
reflecting events and recording amounts as paid or unpaid
in a financial statement or accounting system.
The accounting date is sometimes referred to as the “as of”
date.^[Casualty Actuarial Society Statement
of Principles Regarding Property and Casualty Unpaid Claims Estimates]
Although financial statements are always stated as of a date,
say, December 31, 2015,
it would be more thorough to assign a time as well,
so as to identify all transactions
impacting the financial statements as of that date.
Some say "any particular moment on the 31st" could be used.^["it
would be more accurate to write December 31, 20XX, 11:59:59,
or any particular moment on the
31st." http://www.investopedia.com/university/accounting/accounting5.asp]
However, payments can potentially occur up to and including midnight
December 31, 2015,
so if a time designator is to be used,
midnight
would be the most appropriate.
Another reason for the closing instant to be the end of the day is
for the purposes of date arithmetic.
For example,
the instant closing the month of December is 31 days from the beginning
of December.
The International Organization for Standardization (ISO) sets
the standards for computer representation of
dates and times as a string of
characters.^[ISO 8601,
Third edition, Data elements and interchange formats -- Information
interchange -- Representation of dates and times
(c) ISO 2004]
Regarding "midnight",
the standards recognize that the instant 24:00:00 (hour 24)
marking the end of one calendar day
coincides with the instant 00:00:00 (hour 00) marking the start of the next calendar day.
Furthermore,
"the choice of [hour 24 or hour 00] will depend upon any association with a date,
or a time interval.
[Hour 24] representations are preferred to represent the end
of a time interval."^[ISO 8601 4.2.3. Emphasis added.]
The concept of the closing of the books at the end of a calendar year,
calendar month or calendar day^[defined as "time intervals" by ISO 8601]
suggests that hour 24 is preferred for representing
an accounting date.
ISO 8601's representation of the accounting date referred to as
"close of the 2015 calendar year" or "as of year end 2015"
is therefore "2015-12-31 24:00:00".
On the other hand,
base
R's
implementation of the 8601 standards^[The POSIXt classes.
In R see ?DateTimeClasses.
For additional background, see https://en.wikipedia.org/wiki/Unix_time]
stores time as the number of seconds since the beginning
of 1970,
so midnight is represented as hour 00 of the beginning of each
day.
Therefore, the representation of "as of year end 2015"
in
R
is "2016-01-01 00:00:00"
which is January 1st when
shortened to just the date.^[ISO 8601 2.1.5 recognizes that a "date" can represent
an instant in time as well as a span of time ("duration").]
However,
to refer to the
accounting date "as of year end 2015" with a label that
uses the month "January"
does not
satisfactorily communicate the
"as of December 31, 2015" accounting date concept.
It would be preferable that
R
and a user be able to communicate that
concept using a label with "December" in it
and also have that label refer to the instant
in time separating calendar years 2015 and 2016
(as.Date("2016-01-01") in
R).
That is the purpose of the "asof" package.
Package emonth
Age
Definition: Age
The age of event E as of accounting date A is the
length of time from the occurrence of event E to
hour 24 on accounting date A.
Note that units are not mentioned in the definition of age.
This is because the appropriate unit should be specific to the use case.
In the vast majority of accounting situations,
age is measured in units of days, months or years, not seconds,
and the occurrence of the event is considered to coincide with hour 00.
There is little ambiguity in defining elapsed time
(durations) in units of
seconds or days.
R's
two Date/Time classes facilitate date/time
arithmetic in uits of seconds and days.
-
The POSIXt classes store time as the number of seconds
since the beginning of 1970,
so elapsed time in units of seconds is easily combined
with a POSIXt object to yield another POSIXt object unambiguously.
-
The Date class stores time as the number of days
since the beginning of 1970,
so elapsed time in units of days is easily combined
with a Date object to yield another Date object unambiguously.
It is more complicated with units of months because
month periods are comprised of different numbers of days.
But this complication can be overcome with two key observations.
-
It is commonly accepted that the length of time between
the beginning and end of a month is one "month".
-
Given any time t in any given month,
there is a unique portion p, 0<=p<=1,
that represents the portion of the month completed by time t.
Conversely, given any portion p,
the point in time of a month completed as of that portion of the month
can be easily found.
Those two observations give rise to the definition of the
"month-time" of an instant in time:
Definition: Month Time
The month time of time t is a real number
measuring the number of months since the beginning of 1970 to time t.
The fractional part of the real number represents the portion
of t's month to have expired by time t.
R
has two classes,
POSIXlt and POSIXct
Sentence B
Base R follows that standard and represents an instant of time
as the number of seconds that have transpired since the beginning of 1970.
It is well known that "months" are comprised of different
numbers of days.
Although it is widely accepted that the length of time between
the beginning and end of a month is one "month",
it is also recognized that month durations
cannot be defined consistently in units of days.
Those observations give rise to a different type of unit:
"elapsed month" or "emonth".
Definition: Elapsed Month ("emonth")
The length of time between two instants in time t1 and t2
in units of "emonths" is
mondate(t2) - mondate(t1)
where
mondate(t) is a real number representing
the number of months between the beginning of 1970 and
time t.
Example
mondate("1970-02-01") = 1
mondate("1971-01-01") = 12
mondate("1970-02-15 00:00:00") = 1.5 because the beginning of
February 15, 1970 is halfway through February 1970.
as.Date("1971-01-01") - as.Date("1971-02-01") = 10.5 emonths
Conversely, given any real number t,
it is straightforward to find the time ?YYYYMMDD?HH:MM:SS.zzzzz?
that is t months away from the beginning of 1970 by
first counting whole months,
then counting into the next month (if necessary) the number of days and
seconds corresponding to that month per the fractional value of t.
Defintion: Elapsed Years
The number of elapsed years between times t1 and t2
equals the number of elapsed months divided by 12.
Case Study:
ABC Ins. Co. started on 1/1/2010 to write earthquake insurance in California.
As claims are made,
ABC defines the occurrence date of a claim claim to be the date of
the earthquake and stores that date in an ISO-8601 compliant o
bject (POSIXt).
ABC has had good luck so far -- only 20 claims have been made.
Here are their occurrence dates and their know values as of 12/31/2015:
data ?
To complete Sentence B, we need one more definition:
Definition: The age of accident year AY as of AOD is AOD - AY-01-01.
The accident year age of the 20 claims is the vector
mondate(?2015-12-31?) ? year(occurrenceDate)-01-01
http://smallbusiness.chron.com/differences-dates-between-balance-sheet-income-sheet-24881.html
"Balance Sheet Date
A balance sheet often states that it is prepared as of a specific date, referred to as the balance sheet date. The balance sheet reports on a company’s financial conditions, namely the values of the company’s assets, liabilities and shareholders’ equity. Values are measured in terms of their monetary amounts at particular points in time rather than over any periods. At the end of an accounting cycle, with the accounting books closed to recording new business transactions, companies can summarize their financial conditions as of the cycle's end."
http://www.casact.org/professionalism/standards/princip/SOP-Regarding-Property-and-Casualty-Unpaid-Claims-Estimates_Final%204-22-2015.pdf
Bibliography
Here's a pretty good paper about dates, Lubridate, Chron:
http://biostat.mc.vanderbilt.edu/wiki/pub/Main/ColeBeck/datestimes.pdf
chiefmurph/mondate documentation built on Aug. 29, 2022, 4:13 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Dates and date arithmetic are implemented in R using international standards. The interpretation of those standards in an accounting context can often be difficult and sometimes misleading, particularly with respect to identifying "closing dates" and date arithmetic measured in units of months and years.
The following example sentences are found throughout Financial Services:
A. The value of ABC Company liabilities as of December 31, 2015 is $100M.
B. The age of November receivables as of December 31, 2015 is two months.
The "asof" and "emonth" packages were written to simplify the modeling of these two sentences in R.
Package asof
Accounting Date
Definition: Accounting Date
An accounting date is the cutoff date for reflecting events and recording amounts as paid or unpaid in a financial statement or accounting system. The accounting date is sometimes referred to as the “as of” date.^[Casualty Actuarial Society Statement of Principles Regarding Property and Casualty Unpaid Claims Estimates]
Although financial statements are always stated as of a date, say, December 31, 2015, it would be more thorough to assign a time as well, so as to identify all transactions impacting the financial statements as of that date. Some say "any particular moment on the 31st" could be used.^["it would be more accurate to write December 31, 20XX, 11:59:59, or any particular moment on the 31st." http://www.investopedia.com/university/accounting/accounting5.asp] However, payments can potentially occur up to and including midnight December 31, 2015, so if a time designator is to be used, midnight would be the most appropriate.
Another reason for the closing instant to be the end of the day is for the purposes of date arithmetic. For example, the instant closing the month of December is 31 days from the beginning of December.
The International Organization for Standardization (ISO) sets the standards for computer representation of dates and times as a string of characters.^[ISO 8601, Third edition, Data elements and interchange formats -- Information interchange -- Representation of dates and times (c) ISO 2004] Regarding "midnight", the standards recognize that the instant 24:00:00 (hour 24) marking the end of one calendar day coincides with the instant 00:00:00 (hour 00) marking the start of the next calendar day. Furthermore, "the choice of [hour 24 or hour 00] will depend upon any association with a date, or a time interval. [Hour 24] representations are preferred to represent the end of a time interval."^[ISO 8601 4.2.3. Emphasis added.] The concept of the closing of the books at the end of a calendar year, calendar month or calendar day^[defined as "time intervals" by ISO 8601] suggests that hour 24 is preferred for representing an accounting date.
ISO 8601's representation of the accounting date referred to as "close of the 2015 calendar year" or "as of year end 2015" is therefore "2015-12-31 24:00:00".
On the other hand,
base
R's
implementation of the 8601 standards^[The POSIXt classes.
In R see ?DateTimeClasses.
For additional background, see https://en.wikipedia.org/wiki/Unix_time]
stores time as the number of seconds since the beginning
of 1970,
so midnight is represented as hour 00 of the beginning of each
day.
Therefore, the representation of "as of year end 2015"
in
R
is "2016-01-01 00:00:00"
which is January 1st when
shortened to just the date.^[ISO 8601 2.1.5 recognizes that a "date" can represent
an instant in time as well as a span of time ("duration").]
However,
to refer to the
accounting date "as of year end 2015" with a label that
uses the month "January"
does not
satisfactorily communicate the
"as of December 31, 2015" accounting date concept.
It would be preferable that
R
and a user be able to communicate that
concept using a label with "December" in it
and also have that label refer to the instant
in time separating calendar years 2015 and 2016
(as.Date("2016-01-01") in
R).
That is the purpose of the "asof" package.
Package emonth
Age
Definition: Age
The age of event E as of accounting date A is the length of time from the occurrence of event E to hour 24 on accounting date A.
Note that units are not mentioned in the definition of age. This is because the appropriate unit should be specific to the use case. In the vast majority of accounting situations, age is measured in units of days, months or years, not seconds, and the occurrence of the event is considered to coincide with hour 00.
There is little ambiguity in defining elapsed time (durations) in units of seconds or days. R's two Date/Time classes facilitate date/time arithmetic in uits of seconds and days.
-
The POSIXt classes store time as the number of seconds since the beginning of 1970, so elapsed time in units of seconds is easily combined with a POSIXt object to yield another POSIXt object unambiguously.
-
The Date class stores time as the number of days since the beginning of 1970, so elapsed time in units of days is easily combined with a Date object to yield another Date object unambiguously.
It is more complicated with units of months because month periods are comprised of different numbers of days. But this complication can be overcome with two key observations.
-
It is commonly accepted that the length of time between the beginning and end of a month is one "month".
-
Given any time t in any given month, there is a unique portion p, 0<=p<=1, that represents the portion of the month completed by time t. Conversely, given any portion p, the point in time of a month completed as of that portion of the month can be easily found.
Those two observations give rise to the definition of the "month-time" of an instant in time:
Definition: Month Time
The month time of time t is a real number measuring the number of months since the beginning of 1970 to time t. The fractional part of the real number represents the portion of t's month to have expired by time t.
R has two classes, POSIXlt and POSIXct
Sentence B
Base R follows that standard and represents an instant of time as the number of seconds that have transpired since the beginning of 1970.
It is well known that "months" are comprised of different numbers of days. Although it is widely accepted that the length of time between the beginning and end of a month is one "month", it is also recognized that month durations cannot be defined consistently in units of days. Those observations give rise to a different type of unit: "elapsed month" or "emonth".
Definition: Elapsed Month ("emonth")
The length of time between two instants in time t1 and t2 in units of "emonths" is
mondate(t2) - mondate(t1) where mondate(t) is a real number representing the number of months between the beginning of 1970 and time t.Example
mondate("1970-02-01") = 1
mondate("1971-01-01") = 12 mondate("1970-02-15 00:00:00") = 1.5 because the beginning of February 15, 1970 is halfway through February 1970. as.Date("1971-01-01") - as.Date("1971-02-01") = 10.5 emonths
Conversely, given any real number t, it is straightforward to find the time ?YYYYMMDD?HH:MM:SS.zzzzz? that is t months away from the beginning of 1970 by first counting whole months, then counting into the next month (if necessary) the number of days and seconds corresponding to that month per the fractional value of t.
Defintion: Elapsed Years
The number of elapsed years between times t1 and t2 equals the number of elapsed months divided by 12.
Case Study:
ABC Ins. Co. started on 1/1/2010 to write earthquake insurance in California.
As claims are made,
ABC defines the occurrence date of a claim claim to be the date of
the earthquake and stores that date in an ISO-8601 compliant o
bject (POSIXt).
ABC has had good luck so far -- only 20 claims have been made.
Here are their occurrence dates and their know values as of 12/31/2015:
data ?
To complete Sentence B, we need one more definition:
Definition: The age of accident year AY as of AOD is AOD - AY-01-01.
The accident year age of the 20 claims is the vector
mondate(?2015-12-31?) ? year(occurrenceDate)-01-01
http://smallbusiness.chron.com/differences-dates-between-balance-sheet-income-sheet-24881.html
"Balance Sheet Date A balance sheet often states that it is prepared as of a specific date, referred to as the balance sheet date. The balance sheet reports on a company’s financial conditions, namely the values of the company’s assets, liabilities and shareholders’ equity. Values are measured in terms of their monetary amounts at particular points in time rather than over any periods. At the end of an accounting cycle, with the accounting books closed to recording new business transactions, companies can summarize their financial conditions as of the cycle's end."
http://www.casact.org/professionalism/standards/princip/SOP-Regarding-Property-and-Casualty-Unpaid-Claims-Estimates_Final%204-22-2015.pdf
Bibliography
Here's a pretty good paper about dates, Lubridate, Chron: http://biostat.mc.vanderbilt.edu/wiki/pub/Main/ColeBeck/datestimes.pdf
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.