# era

[![DOI](https://zenodo.org/badge/311391850.svg)](https://doi.org/10.5281/zenodo.7327395)
[![CRAN
downloads](https://cranlogs.r-pkg.org/badges/grand-total/era)](https://cranlogs.r-pkg.org/)

**era** is an R package that provides a consistent representation of
year-based time scales as a numeric vector with an associated *era* –
the [yr class](https://era.joeroe.io/reference/yr.html).

It includes built-in [era
definitions](https://era.joeroe.io/reference/eras.html) for many year
numbering systems used in contemporary and historic calendars
(e.g. Common Era, Islamic ‘Hijri’ years); year-based time scales used in
archaeology, astronomy, geology, and other palaeosciences (e.g. Before
Present, SI-prefixed *annus*); and support for [arbitrary user-defined
eras](https://era.joeroe.io/reference/era.html). Years can converted
from any one era to another using the generalised transformation
function
[yr_transform()](https://era.joeroe.io/reference/yr_transform.html).

era’s classes are based on [vctrs](https://vctrs.r-lib.org/), and come
with methods for robust casting and coercion between years and other
numeric types, type-stable arithmetic with years, and pretty-printing in
tables.

## Installation

You can install the released version of era [from
CRAN](https://cran.r-project.org/package=era) with:

``` r

install.packages("era")
```

Or the development version from [GitHub](https://github.com/joeroe/era)
using the [remotes](https://remotes.r-lib.org/) package:

``` r

# install.packages("remotes")
remotes::install_github("joeroe/era")
```

## Basic usage

[`yr()`](https://era.joeroe.io/reference/yr.md) defines the era
associated with a vector of years:

``` r

library(era)
x <- yr(c(9000, 8000, 7000), "cal BP")
x
#> # cal BP years <yr[3]>:
#> [1] 9000 8000 7000
#> # Era: Before Present (cal BP): Gregorian years (365.2425 days), counted backwards from 1950
```

Use [`yr_transform()`](https://era.joeroe.io/reference/yr_transform.md)
to convert between eras:

``` r

yr_transform(x, "BCE")
#> # BCE years <yr[3]>:
#> [1] 7051 6051 5051
#> # Era: Before Common Era (BCE): Gregorian years (365.2425 days), counted backwards from 1
```

Many common calendar systems and time scales are predefined (see
`?eras()`) and can be referenced by their abbreviated labels. Other eras
can be defined using the
[`era()`](https://era.joeroe.io/reference/era.md) function directly.

For further usage, see the [package
introduction](https://era.joeroe.io/articles/era.html)
([`vignette("era")`](https://era.joeroe.io/articles/era.md)).

# Package index

## Years with era

Functions for constructing and transforming `yr` objects, representing
years with an associated era.

- [`yr()`](https://era.joeroe.io/reference/yr.md) : Create a vector of
  years with era
- [`yr_era()`](https://era.joeroe.io/reference/yr_era.md)
  [`yr_set_era()`](https://era.joeroe.io/reference/yr_era.md)
  [`` `yr_era<-`() ``](https://era.joeroe.io/reference/yr_era.md) : Get
  or set the era of a vector of years
- [`yr_transform()`](https://era.joeroe.io/reference/yr_transform.md) :
  Convert years from one era to another

## Era definitions

Functions for defining calendar eras and time scales.

- [`era()`](https://era.joeroe.io/reference/era.md) : Create an era
  object
- [`eras()`](https://era.joeroe.io/reference/eras.md) : Standard era
  definitions

## Chronological sorting and extremes

Functions for sorting and calculating the extreme values of `yr` vectors
that take into account the direction of its era.

- [`yr_difference()`](https://era.joeroe.io/reference/yr_difference.md)
  : Chronological difference between year vectors
- [`yr_earlier_than()`](https://era.joeroe.io/reference/yr_earlier_than.md)
  [`yr_later_than()`](https://era.joeroe.io/reference/yr_earlier_than.md)
  [`yr_not_earlier_than()`](https://era.joeroe.io/reference/yr_earlier_than.md)
  [`yr_not_later_than()`](https://era.joeroe.io/reference/yr_earlier_than.md)
  : Chronological comparison of years
- [`yr_earliest()`](https://era.joeroe.io/reference/yr_extremes.md)
  [`yr_latest()`](https://era.joeroe.io/reference/yr_extremes.md)
  [`yr_range()`](https://era.joeroe.io/reference/yr_extremes.md) :
  Chronological minima and maxima
- [`yr_sort()`](https://era.joeroe.io/reference/yr_sort.md) :
  Chronological ordering of year vectors

## Helper functions

Miscellaneous utility functions for working with `yr` and `era` objects.

- [`era()`](https://era.joeroe.io/reference/era.md) : Create an era
  object

- [`era_label()`](https://era.joeroe.io/reference/era_parameters.md)
  [`era_epoch()`](https://era.joeroe.io/reference/era_parameters.md)
  [`era_name()`](https://era.joeroe.io/reference/era_parameters.md)
  [`era_unit()`](https://era.joeroe.io/reference/era_parameters.md)
  [`era_scale()`](https://era.joeroe.io/reference/era_parameters.md)
  [`era_direction()`](https://era.joeroe.io/reference/era_parameters.md)
  : Get parameters of an era

- [`era_year()`](https://era.joeroe.io/reference/era_year.md) : Year
  units

- [`era_year_label()`](https://era.joeroe.io/reference/era_year_parameters.md)
  [`era_year_days()`](https://era.joeroe.io/reference/era_year_parameters.md)
  :

  Get the parameters of an `era_year` object.

- [`is_era()`](https://era.joeroe.io/reference/is_era.md)
  [`validate_era()`](https://era.joeroe.io/reference/is_era.md)
  [`is_valid_era()`](https://era.joeroe.io/reference/is_era.md) :

  Validation functions for `era` objects

- [`is_era_year()`](https://era.joeroe.io/reference/is_era_year.md) :

  Validation functions for `era_year` objects

- [`is_yr()`](https://era.joeroe.io/reference/is_yr.md)
  [`validate_yr()`](https://era.joeroe.io/reference/is_yr.md)
  [`is_valid_yr()`](https://era.joeroe.io/reference/is_yr.md) :

  Validation functions for `yr` objects

- [`this_year()`](https://era.joeroe.io/reference/this_year.md) :
  Current year

# Articles

### All vignettes

- [Years with an era](https://era.joeroe.io/articles/era.md):