---
title: "Years with an era"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 2
vignette: >
%\VignetteIndexEntry{Years with an era}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r include=FALSE}
this_year <- as.integer(format(Sys.Date(), "%Y"))
```
Archaeologists, geologists, and other palaeoscientists use different systems for numbering years in the distant past.
For example, the year 10,000 BCE is 11,950 [Before Present](https://en.wikipedia.org/wiki/Before_Present) or 11.95 [ka](https://en.wikipedia.org/wiki/Year#Symbols).
It is usually fine to store years as a plain numeric vector in R, but sometimes it helps to be explicit about which system is being used:
* When you have data that mixes different systems
* When you want to transform years between different systems
* When you need to do arithmetic with years
The **era** package helps in these cases by providing classes which define the 'era' associated with a vector of years and functions for formatting, combining, and transforming years with different eras.
This vignette is an introduction to the main features of the package.
```{r setup, message=FALSE}
library("era")
library("tibble")
library("dplyr")
```
## Years with an era {#yr}
Vectors of years with an era are represented by the `yr` (`era_yr`) class, which is constructed with `yr()`:
```{r yr}
yr(c(10000, 11000, 12000), "BP")
```
The first argument is a numeric vector of years.
These can be integers or doubles.
The second argument, `era`, defines the numbering system associated with the years.
This is an object of class `era` which defines the [parameters of the calendar, epoch and time scale](#era).
Most of the time, you can simply specify the abbreviated label of the era, which will be looked up in the standard eras defined by `eras()`:
```{r yr-era-eg}
yr(c(10000, 11000, 12000), "BCE")
yr(c(10000, 11000, 12000), "uncal BP")
yr(c(10000, 11000, 12000), "ka")
```
`yr_era()` returns details of the era associated with a `yr` vector:
```{r yr-era-get}
neolithic <- yr(11700:7500, "BP")
yr_era(neolithic)
```
`yr_era()`, and its pipe-friendly alias `yr_set_era()`, can also be used to set the era of an existing object:
```{r yr-era-set}
chalcolithic <- 7500:6000
yr_era(chalcolithic) <- yr_era(neolithic)
yr_era(chalcolithic)
```
Note that this only updates the vector's era attribute; it doesn't change the data itself.
To *convert* years from one era to another, you need to use [the `yr_transform()` function](#yr_transform).
`yr` vectors fit nicely into tables, both base data frames and tibbles:
```{r eg-tbl}
postglacial <- tribble(
~period, ~start_ka,
"Late Holocene", 4.2,
"Mid Holocene", 8.326,
"Early Holocene", 11.7,
"Younger Dryas", 12.9,
"Bølling-Allerød", 14.7,
"Heinrich 1", 17.0
)
postglacial |>
mutate(start_ka = yr(start_ka, "ka"))
```
## Era definitions {#era}
era includes built-in definitions of many time scales and year numbering systems from contemporary and historic calendars.
`eras()` returns the [full list](#era-list) of built-in definitions.
You can use any definition in this list by passing its abbreviated `label` to `era()` or as the `era` argument of `yr()` or any other function in the package:
```{r eg-use-era}
era("BP")
yr(10000, "BP")
yr_transform(yr(10000, "BP"), "BCE")
```
If you need to use a time scale that is not in this list, you can [define it yourself](#defining-other-eras) with `era()`.
Suggestions for new eras to include in the package are also welcome; please [create an issue](https://github.com/joeroe/era/issues) on GitHub with suggestions.
### List of built-in eras {#era-list}
```{r era-table, echo=FALSE}
all_eras <- eras()
all_eras$this_year <- NA
na_era <- is.na(era_year_days(all_eras$unit))
all_eras$this_year[!na_era] <- this_year(all_eras$label[!na_era])
knitr::kable(all_eras)
```
### Defining other eras
Eras are defined by the `era` class with the following parameters:
* **label**: an abbreviated label that uniquely identifies the era
* **name**: the full name of the era
* **epoch**: the origin year from which years are counted (in Gregorian astronomical years)
* **unit**: the unit of years counted, defined as its length in solar days
* **scale**: the number of years represented by one unit
* **direction**: whether years are counted forwards (`1`) or backwards (`-1`) from the epoch
These parameters are passed to `era()` to construct an `era` object.
`epoch`, `unit`, `scale`, and `direction` determine the transformation between eras;
`label` and `name` are purely descriptive.
You can define arbitrary eras by using the `era()` function directly:
```{r custom-era}
era("T.A.", epoch = -9021, name = "Third Age", direction = 1)
```
As long as all the parameters are specified correctly, user-defined eras can also be used in `yr_transform()`.
## Converting between eras: `yr_transform()` {#yr_transform}
Use `yr_transform()` to convert between eras:
```{r transform}
postglacial |>
mutate(start_ka = yr(start_ka, "ka")) |>
mutate(start_bp = yr_transform(start_ka, era("BP")),
start_bce = yr_transform(start_ka, era("BCE")))
```
This function implements a generic algorithm for transforming years based on the era parameters described above.
This means that, with a few exceptions (see [invalid transformations](#invalidtransform), you can transform between any two eras that can be described by the `era` class.
### Transformation precision
By default, era transformations are exact:
```{r yr-transform-precision1}
yr(500000, "BCE") |>
yr_transform(era("ka"))
```
Often, this precision is not necessary.
For example, when converting years between calendar- and present-based eras, the `r this_year - 1950` year difference between the formal definition of "Present" and the actual present is rarely significant on a geologic time scale.
Use the `precision` argument of `yr_transform` to get rounded results:
```{r yr-transform-precision2}
yr(10000, "BP") |>
yr_transform(era("BCE"), precision = 1000)
yr(500000, "BCE") |>
yr_transform(era("mya"), precision = 0.1)
```
### Invalid transformations {#invalidtransform}
Some transformations are not possible.
Notably, the length of a 'radiocarbon year' is not well defined on a calendar time scale without [calibration](https://en.wikipedia.org/wiki/Radiocarbon_calibration).
Eras that use non-calendar year unit are represented with an `NA` and will cause an error if passed to `yr_transform()`:
```{r transform-unit, error=TRUE}
era_unit(era("uncal BP"))
yr_transform(yr(9000, "uncal BP"), era("cal BP"))
```
`c14_calibrate()` from the [stratigraphr](https://stratigraphr.joeroe.io) package implements radiocarbon calibration with `yr` objects.
Conversion between eras that both have an `NA` unit are also an error, following the R convention that `NA == NA` is `NA`.
In other words, we don't know whether two non-calendar units are the *same* non-calendar unit.
This means that it is not possible to use `yr_transform()` to convert bp (radiocarbon years Before Present) to bce (radiocarbon years before the Common Era) years, for example.
## Arithmetic with year vectors {#arithmetic}
The `yr` class is based on [vctrs](https://vctrs.r-lib.org/), ensuring type- and size-stable computations.
For example, you can do arithmetic with year vectors:
```{r yr-arith}
a <- yr(1500, "CE")
b <- yr(2020, "CE")
b - a
```
But only when they have the same era:
```{r yr-arith-error, error=TRUE}
c <- yr(0.5, "ka")
b - c
```
Note that, when comparing eras, only the parameters significant to the transformation are considered (i.e. not `label` or `name`).
This means that it is possible to combine year vectors with differently-named but functionally equivalent eras, for example `era("BP")` and `era("cal BP")`, although doing so will print a warning about the loss of information:
```{r era-equality}
era("BP") == era("BC")
era("BP") == era("cal BP")
yr(1000, "BP") + yr(1000, "cal BP")
```
Years will be coerced to a plain numeric vector if a computation means their era no longer makes sense:
```{r yr-multiply}
a * b
```