| Title: | Year-Based Time Scales |
|---|---|
| Description: | Provides a consistent representation of year-based time scales as a numeric vector with an associated 'era'. There are built-in era definitions 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. Years can converted from any one era to another using a generalised transformation function. Methods are also provided for robust casting and coercion between years and other numeric types, type-stable arithmetic with years, and pretty-printing in tables. |
| Authors: | Joe Roe [aut, cre] |
| Maintainer: | Joe Roe <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.5.0 |
| Built: | 2024-11-25 15:01:02 UTC |
| Source: | CRAN |
An era object defines the time scale associated with a vector of years
(see yr()). era() returns an era object, either by looking up
label in the standard eras defined in eras() or, if more than one
argument is given, constructing a new definition with the specified
parameters.
era( label = character(), epoch = NULL, name = label, unit = era_year("Gregorian"), scale = 1, direction = -1 )era( label = character(), epoch = NULL, name = label, unit = era_year("Gregorian"), scale = 1, direction = -1 )
label |
Character. If only one argument is given to |
epoch |
Numeric. Epoch year from which years are counted in Gregorian astronomical years (i.e. there is a "year zero"). |
name |
Character. Full name of the era. Defaults to the value of
|
unit |
An |
scale |
Integer. Number of years represented by one unit, e.g. |
direction |
Are years counted backwards ( |
An object of class era.
Other era definition functions:
eras()
Other era helper functions:
era_parameters,
era_year,
era_year_parameters,
is_era(),
is_era_year(),
is_yr(),
this_year()
era("cal BP") era("T.A.", epoch = -9021, name = "Third Age", direction = 1)era("cal BP") era("T.A.", epoch = -9021, name = "Third Age", direction = 1)
Extracts a specific parameter from an era object.
era_label(x) era_epoch(x) era_name(x) era_unit(x) era_scale(x) era_direction(x)era_label(x) era_epoch(x) era_name(x) era_unit(x) era_scale(x) era_direction(x)
x |
An |
The available parameters are:
label – unique, abbreviated label of the era, e.g. "cal BP"
epoch – year of origin of the era, e.g. 1950 for Before Present
name – full name of the era, e.g. "calendar years Before Present"
unit – unit of years used, an era_year() object
scale – multiple of years used, e.g. 1000 for ka/kiloannum
direction – whether years are counted "backwards" or "forwards" from the epoch #'
Value of the parameter.
Other era helper functions:
era,
era_year,
era_year_parameters,
is_era(),
is_era_year(),
is_yr(),
this_year()
x <- era("cal BP") era_name(x)x <- era("cal BP") era_name(x)
era_year objects describe the unit used for a year as its length in days.
This value is used in an era definition (era()) to enable conversions
between eras that use different units (with yr_transform()).
era_year(label = character(), days = 365.2425)era_year(label = character(), days = 365.2425)
label |
Character. Name of the year unit. |
days |
Numeric. Average length of the year in solar days. Defaults to a Gregorian year (365.2425 days). |
S3 vector of class era_year.
Other era helper functions:
era,
era_parameters,
era_year_parameters,
is_era(),
is_era_year(),
is_yr(),
this_year()
era_year("Julian", 365.25)era_year("Julian", 365.25)
era_year object.Extracts a specific parameter from a year unit object constructed by
era_year().
era_year_label(x) era_year_days(x)era_year_label(x) era_year_days(x)
x |
An object of class |
Value of the parameter.
Other era helper functions:
era,
era_parameters,
era_year,
is_era(),
is_era_year(),
is_yr(),
this_year()
julian <- era_year("Julian", 365.25) era_year_label(julian) era_year_days(julian)julian <- era_year("Julian", 365.25) era_year_label(julian) era_year_days(julian)
Definitions of common eras and time scales.
eras() lists all available era definitions. eras(label) looks up a
specific era by its unique, abbreviated name (e.g. "cal BP").
eras(label = NA)eras(label = NA)
label |
(Optional) Abbreviated names(s) of eras to look up. |
Looking up eras by label uses partial matching.
A table of era definitions. This can be passed to era() to construct an
era object.
Other era definition functions:
era
# List all available eras eras() # Look up a specific era by label eras("cal BP") # With partial matching eras("cal")# List all available eras eras() # Look up a specific era by label eras("cal BP") # With partial matching eras("cal")
era objectsTests whether an object is an era definition (an era object).
is_era() tests whether the object inherits from the S3 class era_yr.
is_valid_era() performs additional checks to determine whether the object
is well-formed (see details).
validate_era() throws an informative error message for invalid yrs.
is_era(x) validate_era(x) is_valid_era(x)is_era(x) validate_era(x) is_valid_era(x)
x |
Object to test. |
Valid era objects:
Must have all parameters set and not NA
Must have a character label parameter
Must have a numeric epoch parameter
Must have a character name parameter
Must have a character unit parameter that is one of the defined units
Must have a positive, integer scale parameter
Must have a direction parameter that is -1 (backwards) or 1 (forwards)
is_era() and is_valid_era() return TRUE or FALSE.
validate_era() returns x invisibly, and is used for its side-effect of
throwing an informative error for invalid objects.
Other era helper functions:
era,
era_parameters,
era_year,
era_year_parameters,
is_era_year(),
is_yr(),
this_year()
era_year objectsTests whether an object is of class era_year (constructed by era_year()).
is_era_year(x)is_era_year(x)
x |
Object to test. |
TRUE or FALSE.
Other era helper functions:
era,
era_parameters,
era_year,
era_year_parameters,
is_era(),
is_yr(),
this_year()
is_era_year(era_year("Julian", 365.25))is_era_year(era_year("Julian", 365.25))
yr objectsTests whether an object is a vector of years with an era (a yr object).
is_yr() tests whether the object inherits from the S3 class era_yr.
is_valid_yr() performs additional checks to determine whether the object
is well-formed (see details).
validate_yr() throws an informative error message for invalid yrs.
is_yr(x) validate_yr(x) is_valid_yr(x)is_yr(x) validate_yr(x) is_valid_yr(x)
x |
Object to test. |
Valid yr objects:
Must contain numeric data (NAs are allowed)
Must have the era attribute set and not NA
Must not have more than one era
Must have an era attribute that is a valid era object (see validate_era())
is_yr() and is_valid_yr() return TRUE or FALSE.
validate_yr() returns x invisibly, and is used for its side-effect of
throwing an informative error for invalid objects.
Other era helper functions:
era,
era_parameters,
era_year,
era_year_parameters,
is_era(),
is_era_year(),
this_year()
x <- yr(5000:5050, era("cal BP")) is_yr(x) is_valid_yr(x) validate_yr(x)x <- yr(5000:5050, era("cal BP")) is_yr(x) is_valid_yr(x) validate_yr(x)
Returns the current year as a year vector, in the era system specified by
era.
this_year(era = "CE")this_year(era = "CE")
era |
An |
A yr vector with the current year.
Other era helper functions:
era,
era_parameters,
era_year,
era_year_parameters,
is_era(),
is_era_year(),
is_yr()
# This year in the Common Era this_year() # This year in the Holocene Epoch this_year("HE")# This year in the Common Era this_year() # This year in the Holocene Epoch this_year("HE")
A yr object represents years with an associated calendar era or time scale.
yr(x = numeric(), era = character())yr(x = numeric(), era = character())
x |
A numeric vector of years. |
era |
The calendar era used by |
A yr (era_yr) object.
Other years with era functions:
yr_era(),
yr_transform()
# The R Age yr(1993:2020, "CE") # A bad movie yr(10000, "BC")# The R Age yr(1993:2020, "CE") # A bad movie yr(10000, "BC")
Functions for extracting or assigning the era of a vector of years.
This function does not alter the underlying values of x. Use yr_transform()
to convert the values of a yr vector to a new era.
yr_era(x) yr_set_era(x, era) yr_era(x) <- valueyr_era(x) yr_set_era(x, era) yr_era(x) <- value
x |
A vector of years. |
value, era
|
An |
yr_era(x) returns the existing era associated with x.
yr_set_era(x, era) and yr_era(x) <- era return x with the new era
assigned. If x is not already a yr vector, it will attempt to coerce it
into one.
Other years with era functions:
yr(),
yr_transform()
x <- 5000:5050 yr_era(x) <- era("cal BP") yr_era(x)x <- 5000:5050 yr_era(x) <- era("cal BP") yr_era(x)
Returns the chronologically earliest and/or latest value in a vector of
years, i.e. era-aware version min(), max(), and range().
yr_earliest(x, na.rm = FALSE) yr_latest(x, na.rm = FALSE) yr_range(x, na.rm = FALSE)yr_earliest(x, na.rm = FALSE) yr_latest(x, na.rm = FALSE) yr_range(x, na.rm = FALSE)
x |
A yr vector with era |
na.rm |
a logical indicating whether missing values should be removed |
These are implemented as prefixed functions rather than S3 min(), max(),
and range() methods for yrs to avoid surprises when numerical (i.e. not
chronological) extremes are expected.
For yr_earliest() and yr_leatest(), a yr vector of length 1 with the
earliest or latest value.
For yr_range(), a yr vector of length 2 with the earliest and latest
value (in that order).
If x contains NA values and na.rm = FALSE (the default), only NAs
will be returned.
Other functions for chronological ordering and extremes:
yr_sort()
# Forward-counting era: x <- yr(c(200, 100, 300), "CE") yr_earliest(x) yr_latest(x) yr_range(x) # Backward-counting era: y <- yr(c(200, 100, 300), "BCE") yr_earliest(y) yr_latest(y) yr_range(x)# Forward-counting era: x <- yr(c(200, 100, 300), "CE") yr_earliest(x) yr_latest(x) yr_range(x) # Backward-counting era: y <- yr(c(200, 100, 300), "BCE") yr_earliest(y) yr_latest(y) yr_range(x)
Sorts a vector of years into earliest-to-latest or latest-to-earliest chronological order based on its era.
yr_sort(x, reverse = FALSE, ...)yr_sort(x, reverse = FALSE, ...)
x |
yr vector with era |
reverse |
Set |
... |
Other arguments passed to |
This is implemented as a prefixed function rather than an S3 sort() method
for yrs to avoid surprises when numerical (i.e. not chronological) sorting
is expected.
Sorted yr vector
Other functions for chronological ordering and extremes:
yr_extremes
# Forward-counting era: x <- yr(c(200, 100, 300), "CE") yr_sort(x) yr_sort(x, reverse = TRUE) # Backward-counting era: y <- yr(c(200, 100, 300), "BCE") yr_sort(y) yr_sort(y, reverse = TRUE)# Forward-counting era: x <- yr(c(200, 100, 300), "CE") yr_sort(x) yr_sort(x, reverse = TRUE) # Backward-counting era: y <- yr(c(200, 100, 300), "BCE") yr_sort(y) yr_sort(y, reverse = TRUE)
Transform a vector of years from one era to another.
yr_transform(x, era = yr_era(x), precision = NA)yr_transform(x, era = yr_era(x), precision = NA)
x |
|
era |
|
precision |
Desired precision of the transformation, i.e. the
transformed values are rounded to the nearest |
Transformation between eras uses the scale, epoch, direction and unit
parameters of the era definition. NA values for any of these parameters in
the source or destination era will cause an error. This is most often
encountered when either are measured in 'radiocarbon years', which cannot be
related to a calendar time scale without
calibration or
un-calibration.
The transformation function is exact and treats years as a real number
scale. This means that transformations between eras with different year
units (e.g. Gregorian to Julian) and/or epochs not aligned to 1 January
in the Gregorian calendar (e.g. Common Era to Islamic calendars) will likely
return non-integer values. The precision argument provides a
convenient way to round the result if you do not need this level of
precision. It is also useful for working around the ambiguous definition of
'present' in various geological time-scales.
A yr object in the era specified by era.
Other years with era functions:
yr(),
yr_era()
x <- yr(10010:10001, "cal BP") yr_transform(x, era("BCE")) yr_transform(x, era("ka"), precision = 1)x <- yr(10010:10001, "cal BP") yr_transform(x, era("BCE")) yr_transform(x, era("ka"), precision = 1)