Extending aion

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:

ananke (quantitative chronology in archaeology).
kairos v2.0 (analysis of chronological patterns from archaeological count data).
ArchaeoPhases v2.0 (post-processing of MCMC simulations for chronological modelling).

Epochs

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 epochs 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): Gregorian years counted forwards from 753

Calendars and Dates

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: number of days since 01-01-01 (Gregorian)
#> [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

Time Series

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()).

References

Reingold, Edward M., and Nachum Dershowitz. 2018. Calendrical Calculations: The Ultimate Edition. 4th ed. Cambridge University Press. https://doi.org/10.1017/9781107415058.

N. Frerebeau

2024-12-10

Epochs

Calendars and Dates

Time Series

References