aion: An R Package to Represent Archaeological Time
Series

Nicolas Frerebeau

<figure><img src="image_1.png" /></figure>

To cite this version:

Nicolas Frerebeau. aion: An R Package to Represent Archaeological Time Series. Journal of Open Source Software, 2024, 9 (96), pp.6210. 10.21105/joss.06210. hal-04542155

HAL Id: hal-04542155

https://hal.science/hal-04542155

Submitted on 11 Apr 2024

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_2.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
# aion: An R Package to Represent Archaeological Time Series

Nicolas Frerebeau <fnref n="1" />

1 UMR 6034 Archéosciences Bordeaux, Maison de l'Archéologie, Université Bordeaux Montaigne, 33607 Pessac cedex, France

DOI: 10.21105/joss.06210

Software

- Review ⚗

- Repository ⚗

- Archive ⚗

Editor: Martin Fleischmann ⚗

Reviewers:

- @sebastien-plutniak

- @steko

Submitted: 27 October 2023

Published: 11 April 2024

License

Authors of papers retain copyright and release the work under a Creative Commons Attribution 4.0 International License (CC BY 4.0).

## Summary

aion is designed to provide a consistent framework for representing archaeological time series that can extend very far in the past. aion provides a system of classes and methods to represent and work with such time series. This package does not provide tools for temporal analysis or modeling. Instead, it offers a system of classes and methods to represent and work with archaeological time series. This API can be extended and used by other specialized packages (see *kairos* v2.0 as an example).

## Statement of need

R ships with a lot of functionality useful for time series, in particular in the base stats (R Core Team, 2023), or in the zoo (Zeileis & Grothendieck, 2005) packages<fnref n="1" />. However, these features are not adapted to most archaeological time series. At the same time, numerous R packages have been developed to describe, analyze, and model temporal data in the context of archaeological studies in the broadest sense. These packages encompass various functionalities, including handling radiocarbon data (e.g., Bchron by Haslett & Parnell, 2008; rcarbon by Crema & Bevan, 2021), Optically Stimulated Luminescence dating (Luminescence by Kreutzer et al., 2012), Bayesian chronological modeling (ArchaeoPhases by Philippe & Vibet, 2020), using paleoenvironmental proxies (e.g., shoredate by Roalkvam, 2023), or other temporal data (e.g., kairos by Frerebeau, 2023). This multitude of packages underscores the significance of computational approaches in archaeology (Schmidt & Marwick, 2020). However, it also presents a major challenge as each package employs its own representation of temporal information. Consequently, exchanging data between different packages within the same data workflow becomes even more arduous.

Archaeological data is typically collected through field excavations or surveys, resulting in irregularly spaced observation times. Although several packages can handle irregular time series, the way they represent dates means they cannot easily be used for archaeological series. These are indeed defined for a given calendar era and more importantly they can involve dates very far in the past.

## Functionality

In base R, dates are represented by default as the number of days since 1970-01-01 (Gregorian), with negative values for earlier dates. aion uses a different approach: it allows to create date vectors represented as *rata die* (Reingold & Dershowitz, 2018), i.e. as number of days since

<footnote n="1">¹See the CRAN Task View about time series analysis: https://cran.r-project.org/view=TimeSeries.</footnote>
DOI: 10.21105/joss.06210

Software

- Review 🔖

- Repository 🔖

- Archive 🔖

Editor: Martin Fleischmann 🔖

Reviewers:

- @sebastien-plutniak

- @steko

Submitted: 27 October 2023

Published: 11 April 2024

License

Authors of papers retain copyright
and release the work under a
Creative Commons Attribution 4.0
International License (CC BY 4.0).

# aion: An R Package to Represent Archaeological Time Series

Nicolas Frerebeau <fnref n="1" />

1 UMR 6034 Archéosciences Bordeaux, Maison de l'Archéologie, Université Bordeaux Montaigne, 33607 Pessac cedex, France

## Summary

aion is designed to provide a consistent framework for representing archaeological time series that can extend very far in the past. aion provides a system of classes and methods to represent and work with such time series. This package does not provide tools for temporal analysis or modeling. Instead, it offers a system of classes and methods to represent and work with archaeological time series. This API can be extended and used by other specialized packages (see *kairos* v2.0 as an example).

## Statement of need

R ships with a lot of functionality useful for time series, in particular in the base stats (R Core Team, 2023), or in the zoo (Zeileis & Grothendieck, 2005) packages<fnref n="1" />. However, these features are not adapted to most archaeological time series. At the same time, numerous R packages have been developed to describe, analyze, and model temporal data in the context of archaeological studies in the broadest sense. These packages encompass various functionalities, including handling radiocarbon data (e.g., Bchron by Haslett & Parnell, 2008; rcarbon by Crema & Bevan, 2021), Optically Stimulated Luminescence dating (Luminescence by Kreutzer et al., 2012), Bayesian chronological modeling (ArchaeoPhases by Philippe & Vibet, 2020), using paleoenvironmental proxies (e.g., shoredate by Roalkvam, 2023), or other temporal data (e.g., kairos by Frerebeau, 2023). This multitude of packages underscores the significance of computational approaches in archaeology (Schmidt & Marwick, 2020). However, it also presents a major challenge as each package employs its own representation of temporal information. Consequently, exchanging data between different packages within the same data workflow becomes even more arduous.

Archaeological data is typically collected through field excavations or surveys, resulting in irregularly spaced observation times. Although several packages can handle irregular time series, the way they represent dates means they cannot easily be used for archaeological series. These are indeed defined for a given calendar era and more importantly they can involve dates very far in the past.

## Functionality

In base R, dates are represented by default as the number of days since 1970-01-01 (Gregorian), with negative values for earlier dates. aion uses a different approach: it allows to create date vectors represented as *rata die* (Reingold & Dershowitz, 2018), i.e. as number of days since

<footnote n="1">¹See the CRAN Task View about time series analysis: https://cran.r-project.org/view=TimeSeries.</footnote>
01-01-01 (Gregorian). This allows to represent dates independently of any calendar and makes calculations and comparisons easier.

The *rata die* vector provides the internal time representation of the aion time series (note that the era (Roe, 2022) package allows to work with numeric vectors that represent year-based time scales). The *fixed()* function allows to create such a vector from dates that can then be converted back into dates (or years) of a particular calendar.

In aion a time series is represented by an S4 class that inherits from the base array. A time series object can be created with the *series()* function that returns an *n × m × 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*. It be created with the *series()* function.

All output produced by aion can be formatted with (virtually) any calendar, as long as the calendar has been defined and the associated conversion methods are available. aion natively supports both Julian and Gregorian calendars (with the most common eras for the latter, e.g. Before 2000, Before Present, (Before) Common Era...) and allows to create custom calendars.

## Acknowledgements

The author would like to thank Brice Lebrun for creating the package logo. Joe Roe also deserves a special mention for the development of the era (Roe, 2022) package, which inspired the present work.

## References

* Crema, E. R., & Bevan, A. (2021). Inference from large sets of radiocarbon dates: Software and methods. *Radiocarbon, 63*, 23–39. https://doi.org/10.1017/RDC.2020.95

* Frerebeau, N. (2023). *kairos: Analysis of Chronological Patterns from Archaeological Count Data*. Université Bordeaux Montaigne. https://doi.org/10.5281/zenodo.5653896

* Haslett, J., & Parnell, A. C. (2008). A simple monotone process with application to radiocarbon-dated depth chronologies. *Journal of the Royal Statistical Society: Series C (Applied Statistics)*, 57(4), 399–418. https://doi.org/10.1111/j.1467-9876.2008.00623.x

* Kreutzer, S., Schmidt, C., Fuchs, M. C., Dietze, M., Fischer, M., & Fuchs, M. (2012). Introducing an r package for luminescence dating analysis. *Ancient TL*, 30(1), 1–8.

* Philippe, A., & Vibet, M.-A. (2020). Analysis of Archaeological Phases Using the R Package *ArchaeoPhases*. *Journal of Statistical Software, Code Snippets*, 93(1). https://doi.org/10.18637/jss.v093.c01

* R Core Team. (2023). *R: A language and environment for statistical computing*. R Foundation for Statistical Computing. https://www.R-project.org/

* Reingold, E. M., & Dershowitz, N. (2018). *Calendrical Calculations: The Ultimate Edition* (4th ed.). Cambridge University Press. https://doi.org/10.1017/9781107415058

* Roalkvam, I. (2023). Shoredate: An r package for shoreline dating coastal stone age sites. *Journal of Open Source Software*, 8, 5337. https://doi.org/10.21105/joss.05337

* Roe, J. (2022). *Era: Year-based time scales*. https://CRAN.R-project.org/package=era

* Schmidt, S. C., & Marwick, B. (2020). Tool-driven revolutions in archaeological science. *Journal of Computer Applications in Archaeology*. https://doi.org/10.5334/jcaa.29
01-01-01 (Gregorian). This allows to represent dates independently of any calendar and makes calculations and comparisons easier.

The *rata die* vector provides the internal time representation of the aion time series (note that the era (Roe, 2022) package allows to work with numeric vectors that represent year-based time scales). The *fixed()* function allows to create such a vector from dates that can then be converted back into dates (or years) of a particular calendar.

In aion a time series is represented by an S4 class that inherits from the base array. A time series object can be created with the *series()* function that returns an *n × m × 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*. It be created with the *series()* function.

All output produced by aion can be formatted with (virtually) any calendar, as long as the calendar has been defined and the associated conversion methods are available. aion natively supports both Julian and Gregorian calendars (with the most common eras for the latter, e.g. Before 2000, Before Present, (Before) Common Era...) and allows to create custom calendars.

## Acknowledgements

The author would like to thank Brice Lebrun for creating the package logo. Joe Roe also deserves a special mention for the development of the era (Roe, 2022) package, which inspired the present work.

## References

* Crema, E. R., & Bevan, A. (2021). Inference from large sets of radiocarbon dates: Software and methods. *Radiocarbon, 63*, 23–39. https://doi.org/10.1017/RDC.2020.95

* Frerebeau, N. (2023). *kairos: Analysis of Chronological Patterns from Archaeological Count Data*. Université Bordeaux Montaigne. https://doi.org/10.5281/zenodo.5653896

* Haslett, J., & Parnell, A. C. (2008). A simple monotone process with application to radiocarbon-dated depth chronologies. *Journal of the Royal Statistical Society: Series C (Applied Statistics)*, 57(4), 399–418. https://doi.org/10.1111/j.1467-9876.2008.00623.x

* Kreutzer, S., Schmidt, C., Fuchs, M. C., Dietze, M., Fischer, M., & Fuchs, M. (2012). Introducing an r package for luminescence dating analysis. *Ancient TL*, 30(1), 1–8.

* Philippe, A., & Vibet, M.-A. (2020). Analysis of Archaeological Phases Using the R Package *ArchaeoPhases*. *Journal of Statistical Software, Code Snippets*, 93(1). https://doi.org/10.18637/jss.v093.c01

* R Core Team. (2023). *R: A language and environment for statistical computing*. R Foundation for Statistical Computing. https://www.R-project.org/

* Reingold, E. M., & Dershowitz, N. (2018). *Calendrical Calculations: The Ultimate Edition* (4th ed.). Cambridge University Press. https://doi.org/10.1017/9781107415058

* Roalkvam, I. (2023). Shoredate: An r package for shoreline dating coastal stone age sites. *Journal of Open Source Software*, 8, 5337. https://doi.org/10.21105/joss.05337

* Roe, J. (2022). *Era: Year-based time scales*. https://CRAN.R-project.org/package=era

* Schmidt, S. C., & Marwick, B. (2020). Tool-driven revolutions in archaeological science. *Journal of Computer Applications in Archaeology*. https://doi.org/10.5334/jcaa.29
Zeileis, A., & Grothendieck, G. (2005). Zoo: S3 infrastructure for regular and irregular time series. *Journal of Statistical Software*, 14(6), 1–27. https://doi.org/10.18637/jss.v014.i06
Zeileis, A., & Grothendieck, G. (2005). Zoo: S3 infrastructure for regular and irregular time series. *Journal of Statistical Software*, 14(6), 1–27. https://doi.org/10.18637/jss.v014.i06