joeroe / era Goto Github PK

View Code? Open in Web Editor NEW

11.0 3.0 0.0 813 KB

R package for year-based time scales

Home Page: https://era.joeroe.io

License: Other

R 100.00%

r r-package archaeology geology paleontology paleoclimate vctrs

era's Introduction

👋 Hi, I'm Joe.

I'm a computational archaeologist and research software engineer at the University of Bern.

I use GitHub for software packages, research compendiums and various other projects. I try to work in the open as much as possible, so please be aware that many of my repositories are unpublished experiments, works-in-progress or abandonded ideas. Below you can find a curated list of my more 'mature' projects.

More info & contacts:

Software

R packages (stable)

era – year-based time scales
rpaleoclim – download paleoclimate data from PaleoClim

R packages (experimental)

c14 – tidy radiocarbon data
controller – tools for controlled vocabularies
fieldwalkr – spatial sampling and survey simulation
rintchron – interface to IntChron
stratigraphr – archaeological stratigraphy and chronological sequences

Other

ruby-radiocarbon – Ruby gem for fast radiocarbon calibration
piwigo-3dhop – Piwigo plugin for viewing 3D models using 3DHOP
risotto – minimalist hugo theme inspired by terminal ricing aesthetics. Originally developed for the CAA/SSLA website

Data

xronos – an open repository for chronometric data in archaeology (incl. R package, web app)
tavo-a27 – data from Uerpmann 1987, The Ancient Distribution of Ungulate Mammals in the Middle East (TAVO A27)
swapdata – Southwest Asian palaeoarchaeology data

Research compendiums

Published

SWAsiaNeolithicFounderCrops – data and code for Arranz-Otaegui & Roe (2023), 'Revisiting the concept of the "Neolithic Founder Crops" in southwest Asia', Vegetation History & Archaeobotany, https://doi.org/10.1007/s00334-023-00917-1
MartinHinz/bayesian.demographic.reconstruction.2022 – data and code for 'Bayesian inference of prehistoric population dynamics from multiple proxies: a case study from the North of the Swiss Alps' (preprint)

Conference papers

dabawa23_enm, paper presented at "Digital Archaeology Bern – Ancient West Asia", Bern, 6–7 October 2023, 'Modelling the range of wild plants and crop progenitors in the Late Epipalaeolithic–Early Neolithic Levant'

Teaching materials

gis_in_archaeology – course website for 'GIS in Archaeology' (437571) at the University of Bern
smada – course website for 'Statistical Methods for Archaeological Data Analysis' (452240) at the University of Bern
r4r_visualisation – slides, code examples, and exercises for the visualisation module of R for Archaeologists, a winter school held at the University of Pisa.

Lists

Of handy GitHub repositories:

era's People

Contributors

Stargazers

Watchers

era's Issues

S4 compatibility

The vctrs S3 vectors vignette suggests adding this lines to internal constructors for compatibility with S4:

methods::setOldClass(c("pizza_percent", "vctrs_vctr"))

But when I've tried it in new_yr I get an error:

era:::new_yr()
#> Error in assign(".S3MethodsClasses", S3table, envir = where): 
#>   cannot add bindings to a locked environment

Switch to native pipe

And eliminate magrittr dependency.

Write package vignette

Year zero problem

When converting between CE-based and BP-based eras, yr_transform() does not account for the absence of a year zero.

library("era")
yr_transform(yr(10000, "BP"), era("BCE"))
#> # BCE years <yr[1]>:
#> [1] 8051
#> # Era: Before Common Era (BCE): calendar years, counted backwards from 1

OxCal is good at this kind of thing.

Inconsistent warnings when combining eras with different labels/names

Arithmetic with yrs with functionally equivalent, but differently named, eras throws a warning as expected:

library("era")
yr(1, "BP") + yr(1, "cal BP")
#> Warning: `era(x)` and `era(y)` have different label or name parameters.
#> # BP years <yr[1]>:
#> [1] 2
#> # Era: Before Present (BP): calendar years, counted backwards from 1950

But combining the same vectors doesn't:

c(yr(1, "BP"), yr(1, "cal BP"))
#> # BP years <yr[2]>:
#> [1] 1 1
#> # Era: Before Present (BP): calendar years, counted backwards from 1950

^{Created on 2020-12-08 by the reprex package (v0.3.0)}

The check currently in vec_arith.era_yr.era_yr() should be moved lower, to catch all instances of combination.

Should epoch parameter of eras also have an era?

Currently era() assumes the epoch parameter is a year in the Common Era, but we could make this itself a yr object (defaulting to CE).

Add function for validating era_yrs

Which would check that:

The vec_data() is numeric or missing
The era attribute is set
The era is valid (see #7)

It should be used in the yr() constructor, but not new_yr(), to maintain the ability to create (invalid) empty yrs internally.

Pillar printing for era

NetCDF compatability

http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html#calendar

Conversion between eras with NA units

yr_transform() currently throws an error if either the source or destination era has an NA unit, following the R convention that NA == NA is NA.

It might not be necessary to be this strict, for example to allow transformations between era("bp") and era("bce"), and just warn that there is an assumption that the units are comparable.

Add vec_proxy_compare method for era

Currently yr_era(x) == yr_era(y) is used in several places but I don't trust it.

It also might be better to only selectively compare eras, e.g. consider eras with different labels equal if all the significant parameters are the same. Then they should be able to be combined, with a warning that the labels will be changed.

Release era 0.4.1

First release:

usethis::use_cran_comments()
Update (aspirational) install instructions in README
Proofread Title: and Description:
Check that all exported functions have @return and @examples
Check that Authors@R: includes a copyright holder (role 'cph')
Check licensing of included files
Review https://github.com/DavisVaughan/extrachecks

Prepare for release:

Submit to CRAN:

usethis::use_version('patch')
devtools::submit_cran()
Approve email

Wait for CRAN...

Consider vec_proxy_compare method for era_yr

Currently:

library("era")
a <- yr(1:10, "BP")
b <- yr(1:10, "BP")
c <- yr(1:10, "BC")
a == b
#>  [1] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
a == c
#> Error: Can't combine `..1` <yr (BP)> and `..2` <yr (BC)>.
#> Reconcile eras with yr_transform() first.

The first result is correct. The second result maybe too strict and should return FALSE instead of an error.

Cast character to era_yr?

It could be possible to cast characters to era_yrs (i.e. the inverse of #11) in some circumstances. E.g. "1 BCE" could be interpreted as yr(1, "BCE"). But maybe this is too magical?

Release era 0.3.1

Prepare for release:

Submit to CRAN:

usethis::use_version('minor')
devtools::submit_cran()
Approve email

Wait for CRAN...

Add more eras

Many are dependent on #15.

General resources:

era(NA) has unexpected results

As a result of 86a6015, passing NA to era() constructs every available standard era:

library("era")
era(NA)
#> <era[24]>
#>  [1] Before Present (BP): calendar years, counted backwards from 1950                        
#>  [2] Before Present (cal BP): calendar years, counted backwards from 1950                    
#>  [3] Before Christ (BC): calendar years, counted backwards from 0                            
#>  [4] Before Common Era (BCE): calendar years, counted backwards from 0                       
#>  [5] Anno Domini (AD): calendar years, counted forwards from 0                               
#>  [6] Common Era (CE): calendar years, counted forwards from 0                                
#>  [7] kiloannum (ka): calendar (×1000) years, counted backwards from 1950                     
#>  [8] megaannum (Ma): calendar (×1e+06) years, counted backwards from 1950                    
#>  [9] gigaannum (Ga): calendar (×1e+09) years, counted backwards from 1950                    
#> [10] thousand years ago (kya): calendar (×1000) years, counted backwards from 1950           
#> [11] million years ago (mya): calendar (×1e+06) years, counted backwards from 1950           
#> [12] billion years ago (bya): calendar (×1e+09) years, counted backwards from 1950           
#> [13] years before 2000 (b2k): calendar years, counted backwards from 2000                    
#> [14] uncalibrated Before Present (uncal BP): radiocarbon years, counted backwards from 1950  
#> [15] Radiocarbon Years Before Present (RCYBP): radiocarbon years, counted backwards from 1950
#> [16] Before Present (uncalibrated) (bp): radiocarbon years, counted backwards from 1950      
#> [17] Before Christ (uncalibrated) (bc): radiocarbon years, counted backwards from 1950       
#> [18] Before Common Era (uncalibrated) (bce): radiocarbon years, counted backwards from 1950  
#> [19] Anno Domini (uncalibrated) (ad): radiocarbon years, counted forwards from 1950          
#> [20] Common Era (uncalibrated) (ce): radiocarbon years, counted forwards from 1950           
#> [21] Holocene Era (HE): calendar years, counted forwards from -10000                         
#> [22] Before Holocene Era (BHE): calendar years, counted backwards from -10000                
#> [23] Anno Lucis (AL): calendar years, counted forwards from -4000                            
#> [24] After the Development of Agriculture (ADA): calendar years, counted forwards from -8000

This is a neat trick but probably not expected from the user's point of view. It should either throw an error (could handled in validation – #7) or return an NA-era.

More informative error message for era("unknown era")

era("unknown era")
#> Error: Invalid era:
#> x `scale` must be positive
#> x `direction` must be -1 (backwards) or 1 (forwards)
#> Run `rlang::last_error()` to see where the error occurred.

Rather than trying and failing to construct an era with missing parameters, era() should recognise that the user has asked it for a predefined era that doesn't exist and give a more informative error.

CRAN checks failed

https://cran.r-project.org/web/checks/check_results_era.html

yr() does not check whether era is an era

Because using vec_assert has a puzzling result:

vctrs::vec_assert(era::era("BP"), era:::new_era())
#> Error: `era::era("BP")` must be a vector with type <era>.
#> Instead, it has type <era>.

Test coverage

Pillar printing for era_year

Add function for validating eras

eras are complicated enough that a validate_era() function is needed. This should be called in the era() constructor, but not new_era(), to maintain the ability to create (invalid) empty eras internally.

Year to date conversions

We should have a function for converting between era_yr and date/datetime classes. There should probably be plenty of warnings about the fact that it isn't precise.

Should be able to cast yr to character

Possibly adding the abbreviated era label.

yr_transform ignores direction

Add precision argument to yr_transform()

yr_transform() is precise with epoch transformations, which is appropriate for more recent years but unnecessarily messy for distant ones:

library("era")
yr(100000000, "BCE") %>% 
  yr_transform(era("mya"))
#> # mya years <yr[1]>:
#> [1] 100.0019
#> # Era: million years ago (mya): calendar (×1e+06) years, counted backwards from 1950

^{Created on 2020-11-12 by the reprex package (v0.3.0)}

It would be nice to add an option to round the output to a desired level of precision in yr_transform().

Add vec_math method for era_yr

For (better) handling of sum, mean, etc. Most should strip era and return a numeric.

Release era 0.4.0

Prepare for release:

Submit to CRAN:

usethis::use_version('minor')
devtools::submit_cran()
Approve email

Wait for CRAN...

Add CONTRIBUTING

Including #21.

Use rlang error handling

i.e. rlang::abort(), warn() and inform() over base::stop(), warning() and message(). See: https://rlang.r-lib.org/reference/abort.html

format.era fails with era vectors containing NAs

library("era")
c(era("BP"), NA)
#> <era[2]>
#> Error in unitout[era_scale(x) == 1] <- era_unit(x)[era_scale(x) == 1]: 
#>   NAs are not allowed in subscripted assignments

Document process for suggesting new eras

After 86a6015 adding new definitions of standard eras is now quite straightforward. Documenting how to do it step-by-step might be a good way to encourage new contributions.

Conversion between year units

Adding non-Gregorian calendars complicates the definition and conversion of eras. We need to account for:

The differing length of Gregorian vs. non-Gregorian years
Differing lengths within an era – leap days etc. (?)
Non-alignment of year starts, e.g. 1422 AH is either 2020 or 2021 CE, depending on where in the year we are

I haven't fully worked out how to do this. But some general principles:

The scope of this package is years; we should avoid having to explicitly consider dates if at all possible
In this context years are not dates. They are a measurement of the period of time elapsed from a particular epoch in a particular unit. They can be converted to dates, but only approximately.
It follows from this that 2020 CE is actually "2020 Gregorian years from Year Zero", and that converting it to a non-Gregorian year will probably result in a decimal value.
It's okay if conversions between eras are approximate (perhaps issue a warning about this though)
It's important that conversions between eras are symmetric

Paired eras

CE-based eras come in pairs, i.e. negative values of CE are BCE; negative values of BCE are CE. There is currently no concept of this in era. I can think of two ways to add it:

As part of the definition of an era, e.g. add an inverse attribute that contains another era.
As a function, which takes a year vector with negative values and splits it into two positive vectors with paired eras.

The underlying question is whether it makes sense to support paired eras in analytical use (in which case we'd need 1) or just for printing and plotting (then 2 would be enough).

Method for strictly comparing eras

era("AD") == era("CE")
#> [1] TRUE

But sometimes you might want it to be FALSE.

era arguments should always accept a character label

Currently:

library("era")
yr(1, "BP")
#> # BP years <yr[1]>:
#> [1] 1
#> # Era: Before Present (BP): calendar years, counted backwards from 1950

But:

yr_set_era(1, era("BP"))
#> # BP years <yr[1]>:
#> [1] 1
#> # Era: Before Present (BP): calendar years, counted backwards from 1950

^{Created on 2020-11-12 by the reprex package (v0.3.0)}

This as annoying. Every function that has an era argument should also accept a character label to look up in eras().

Era labels sometimes come before values

There should be an attribute of era that specifies whether the label is conventionally placed before or after the value, e.g. "AD 1" vs. "1 BC".

Add more units

For different definitions of a year:

Gregorian
Julian
Lunar
Astronomical

Resources:

Add ggplot2 scales extensions

They wouldn't do much, just change the default order of the sequence based on the era's direction attribute, and add abbreviated labels somewhere.

It would also be nice to support paired eras when plotting (#17).

Resources:

Extending ggplot2 vignette, "Doing more with facets"

Document standard eras

Currently the standard eras known to the package are defined internally in era_dictionary(). These should at least be documented somewhere for the user. I can see two options:

Retain era_dictionary() as an internal function, and manually update the roxygen2 documentation for era().
Turn era_dictionary() into an exported function (eras()?) which, in addition to returning a specified era, could:
- List all available eras if no argument is given
- Do partial matching

joeroe / era Goto Github PK

era's Introduction

👋 Hi, I'm Joe.

Software

R packages (stable)

R packages (experimental)

Other

Data

Research compendiums

Published

Conference papers

Teaching materials

Lists

era's People

Contributors

Stargazers

Watchers

era's Issues

Recommend Projects

Recommend Topics

Recommend Org