Beta release of era
era is a small R package for working with different year numbering systems. There are a few systems in use in archaeology, geology, and other palaeosciences; for example, the year 10,000 BCE is 11,950 Before Present or 11.95 ka. 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. I wrote it to support two other packages I’m working on, stratigraphr and rintchron, because whilst converting between any two eras (e.g. BP→BCE) is trivial, I wanted something more generalised and predictable when encountering lots of them. It was also a good way to learn more about vctrs, the new backend package used to implement S3 vector classes in the tidyverse, which I found very useful for getting a grip on how size and type stability works (or doesn’t work) in R at a low level, and how to write classes that behave consistently and intuitively.
I released the first beta version of era today. You can install it from GitHub with the remotes package:
remotes::install_github("joeroe/era")
library("era")
I plan to submit the next release to CRAN; so please, try it out and submit an issue if you find any bugs!
Using era
The introductory vignette details the main features of the package, but briefly,
yr() defines the era associated with a vector of years:
yr(10010:10001, "cal BP")
#> # cal BP years <yr[10]>:
#> [1] 10010 10009 10008 10007 10006 10005 10004 10003 10002 10001
#> # Era: Before Present (cal BP): calendar years, counted backwards from 1950
yr is a vector class is based on vctrs.
This means it behaves in a consistent, type-stable way across base R and other packages.
Some common calendar systems and time scales are built into the package (see ?eras()) and can be referenced by simply passing their abbreviated label to yr().
Other eras can be defined using the era() function directly, which allows for arbitrary user-defined eras:
era("T.A.", epoch = -9021, name = "Third Age", direction = "forwards")
#> <era[1]>
#> [1] Third Age (T.A.): calendar years, counted forwards from -9021
The yr_transform() is used to convert between eras, included user-defined ones:
yr(10010:10001, "cal BP") %>%
yr_transform(era("BCE"))
#> # BCE years <yr[10]>:
#> [1] 8060 8059 8058 8057 8056 8055 8054 8053 8052 8051
#> # Era: Before Common Era (BCE): calendar years, counted backwards from 0
yr vectors fit nicely into tables, both base data frames and tibbles:
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
) %>%
mutate(start_ka = yr(start_ka, "ka")) %>%
mutate(start_bp = yr_transform(start_ka, era("BP")),
start_bce = yr_transform(start_ka, era("BCE")))
#> # A tibble: 6 x 4
#> period start_ka start_bp start_bce
#> <chr> <yr> <yr> <yr>
#> 1 Late Holocene 4.200 4200 2250
#> 2 Mid Holocene 8.326 8326 6376
#> 3 Early Holocene 11.700 11700 9750
#> 4 Younger Dryas 12.900 12900 10950
#> 5 Bølling-Allerød 14.700 14700 12750
#> 6 Heinrich 1 17.000 17000 15050