library(aion)
library(methods)
aion offers a simple API that can be extended and used by other specialized packages.
The following packages rely on aion:
An epoch is an instant in time chosen as the origin of a particular calendar era. With aion, you can work with different Gregorian calendar epochs: BC(), BCE(), AD(), CE(), BP(), b2k().
It is also possible to create objects representing specific periods of the Gregorian calendar. Simply create a GregorianCalendar class object:
## Years since 753 BC (the traditional founding of Rome)
AUC <- new(
Class = "GregorianCalendar",
label = "AUC", # Abbreviated label
name = "Ab urbe condita", # Name of the time scale
epoch = 753, # Epoch from which years are counted
direction = 1L # Count years forwards from epoch
)
AUC
#> Ab urbe condita (AUC): Années grégoriennes comptées à partir de 753.
The following example is used to build a simple solar calendar with 365 days each year and no leap-year rule. This is the ancient Egyptian calendar. You will find full details of the calculations and detailed explanations in Reingold and Dershowitz (2018, p. 29).
You can define additional calendars by creating S4 classes that inherit from the TimeScale class exported by aion:
## Egyptian calendar
E <- setClass(
Class = "EgyptianCalendar",
prototype = list(
name = "Egyptian",
fixed = -272787,
direction = 1L,
year = 365
),
contains = "TimeScale"
)
Once the calendar has been defined, you need to build methods for converting rata die to and from this calendar:
## Convert Egyptian dates to rata die
## NB: this method MUST return a RataDie object
setMethod(
f = "fixed",
signature = c(
year = "numeric",
month = "numeric",
day = "numeric",
calendar = "EgyptianCalendar"
),
definition = function(year, month, day, calendar) {
rd <- calendar_fixed(calendar) +
365 * (year - 1) +
30 * (month - 1) +
day - 1
as_fixed(rd)
}
)
## Convert rata die to Egyptian dates
## NB: this method MUST return a data.frame
setMethod(
f = "as_date",
signature = c(object = "numeric", calendar = "EgyptianCalendar"),
definition = function(object, calendar) {
day <- object - calendar_fixed(calendar)
year <- day %/% 365 + 1
month <- (day %% 365) %/% 30 + 1
day <- day - 365 * (year - 1) - 30 * (month - 1) + 1
data.frame(year = year, month = month, day = day)
}
)
## Convert rata die to Egyptian years
setMethod(
f = "as_year",
signature = c(object = "numeric", calendar = "EgyptianCalendar"),
definition = function(object, calendar, ...) {
(object - calendar_fixed(calendar)) %/% 365 + 1
}
)
Now you can use your calendar:
## Create a calendar object
cal <- E()
## Convert 161/7/15 in rata die
fixed(
year = 161,
month = 7,
day = 15,
calendar = cal
)
#> Rata die : nombre de jours depuis le 01-01-01 (grégorien).
#> [1] -214193
## Convert -214193 r.d. to an Egyptian date
as_date(-214193, calendar = cal)
#> year month day
#> 1 161 7 15
The definition of new calendars, combined with the Julian and Gregorian calendars already included in aion, allows you to build conversion tools:
## Build a conversion function from Gregorian CE years to Egyptian years
Gregorian_to_Egyptian <- convert(CE(), E())
## Convert 2023 (Gregorian) to the Egyptian calendar
Gregorian_to_Egyptian(2023)
#> [1] 2771
A time series object is simply an \(n \times m \times p\) array, with \(n\) being the number of observations, \(m\) being the number of series and with the \(p\) columns of the third dimension containing extra variables for each series. This array comes with an extra time slot that store the observations times expressed in rata die. You can create classes that inherits from the TimeSeries class.
As an example, you can create a class that represent the results of the calibration of radiocarbon dates (this code comes from the ananke package):
.CalibratedAges <- setClass(
Class = "CalibratedAges",
slots = c(
ages = "numeric", # Stores the radiocarbon ages to be calibrated
errors = "numeric", # Store the standard deviation of the radiocarbon ages
curves = "character" # Store the name of the calibration curve
),
contains = "TimeSeries"
)
All methods defined in aion can then be used on objects belonging to this new class (e.g. plot()).
Reingold, Edward M., and Nachum Dershowitz. 2018. Calendrical Calculations: The Ultimate Edition. 4th ed. Cambridge University Press. https://doi.org/10.1017/9781107415058.