XRONOS is a worldwide database of chronological data (such as radiocarbon or dendrochronological dates) from archaeological contexts. The xronos package allows you to retrieve data from XRONOS directly using R. It also provides tools for inspecting and transforming this data for analysis with commonly-used packages.
This vignette introduces the main features of the xronos package. It covers:
- Querying and retrieving chronological data from XRONOS with
chron_data() - Calibrating radiocarbon dates with xronos and c14
- Mapping chronological data with xronos and sf
Get chronological data
chron_data() provides an R interface to XRONOS’ REST API for retrieving
chronological data. Without further parameters, it will request all
available data from XRONOS.
Since this takes some time, you will be prompted to confirm this
request. Use chron_data(.everything = TRUE) to confirm that
you do want to download all records from XRONOS and suppress this
prompt.
In practice, you’ll probably want to narrow down the dataset with a
search query. You can use the following parameters, passed as arguments
to chron_data(), to filter the results:
labnrsitesite_type-
country(ideally a two-letter country code, otherwise the function will attempt to interpret it as one using countrycode::countryname()) featurematerialspecies
You can combine any number of parameters, and each parameter can take either a single value or a vector of values that should be included in the results.
For example, to get all radiocarbon dates from Switzerland on either charcoal or bone:
chron_ch <- chron_data(country = "CH", material = c("charcoal", "bone"))The results of the query are returned as a table of records (a
tibble if tibble is installed, otherwise a data frame):
chron_ch
#> # A tibble: 1,847 × 21
#> id labnr bp std cal_bp cal_std delta…¹ reference sourc…² mater…³
#> <int> <chr> <int> <int> <lgl> <lgl> <dbl> <list> <chr> <chr>
#> 1 4946 ETH-63… 9044 35 NA NA NA <named list> AgriCh… charco…
#> 2 4947 ETH-63… 8912 33 NA NA NA <named list> AgriCh… charco…
#> 3 4948 ETH-63… 8909 47 NA NA NA <named list> AgriCh… charco…
#> 4 4949 ETH-63… 8812 33 NA NA NA <named list> AgriCh… charco…
#> 5 5070 VERA-2… 235 35 NA NA NA <named list> AgriCh… charco…
#> 6 5134 UZ-2480 5020 75 NA NA NA <named list> AgriCh… charco…
#> 7 5155 CRG-582 5950 100 NA NA NA <named list> AgriCh… charco…
#> 8 5156 CRG-580 5980 175 NA NA NA <named list> AgriCh… charco…
#> 9 5157 CRG-581 5715 160 NA NA NA <named list> AgriCh… charco…
#> 10 5158 CRG-430 5484 128 NA NA NA <named list> AgriCh… charco…
#> # … with 1,837 more rows, 11 more variables: species <chr>, feature <chr>,
#> # periods <list>, typochronological_units <list>,
#> # ecochronological_units <list>, site <chr>, country <chr>, lat <chr>,
#> # lng <chr>, site_type <chr>, feature_type <chr>, and abbreviated variable
#> # names ¹delta_c13, ²source_database, ³materialCalibrating radiocarbon data
There are several R packages that include functions for radicarbon
calibration, including rcarbon, oxcAAR (requires external software), and
BChron. Calibrating radiocarbon data from XRONOS should follow the same
general principle whichever is used: pass the columns bp
and std—and possibly also labnr as a unique
ID—as arguments to the calibration function. For example, using
rcarbon:
library(rcarbon)
chron_moos <- chron_data(site = "Moos")
chron_moos <- unique(chron_moos[c("labnr", "bp", "std")]) # Remove duplicates
chron_moos_cal <- calibrate(x = chron_moos$bp,
errors = chron_moos$std,
ids = chron_moos$labnr,
verbose = FALSE)The results are best understood using a plot:
multiplot(chron_moos_cal)
Map chronological data
Wherever possible, XRONOS includes the geographic location of chrons,
stored as latitude and longitude coordinates. The convenience function
chron_as_sf() converts these coordinates into a ‘simple
features’ geometry column for use with the sf package:
library(sf)
#> Linking to GEOS 3.10.2, GDAL 3.4.1, PROJ 8.2.1; sf_use_s2() is TRUE
chron_as_sf(chron_ch)
#> Warning: 570 rows with missing or invalid coordinates were removed.
#> Simple feature collection with 1277 features and 21 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: 4.0911 ymin: 45.96543 xmax: 10.38184 ymax: 47.75
#> Geodetic CRS: WGS 84
#> # A tibble: 1,277 × 22
#> id labnr bp std cal_bp cal_std delta…¹ reference sourc…² mater…³
#> * <int> <chr> <int> <int> <lgl> <lgl> <dbl> <list> <chr> <chr>
#> 1 5204 ETH-16… 4370 70 NA NA NA <named list> AgriCh… charco…
#> 2 5205 ETH-18… 4365 65 NA NA NA <named list> AgriCh… charco…
#> 3 5206 ETH-18… 4720 60 NA NA NA <named list> AgriCh… charco…
#> 4 5207 ARC-11… 4490 55 NA NA NA <named list> AgriCh… charco…
#> 5 5208 B-4703 4430 40 NA NA NA <named list> AgriCh… charco…
#> 6 5209 ETH-11… 5140 45 NA NA NA <named list> AgriCh… charco…
#> 7 5210 ARC-10… 5070 145 NA NA NA <named list> AgriCh… charco…
#> 8 5211 ETH-16… 5990 75 NA NA NA <named list> AgriCh… charco…
#> 9 5212 B-4701 5740 50 NA NA NA <named list> AgriCh… charco…
#> 10 5213 ETH-11… 5460 45 NA NA NA <named list> AgriCh… charco…
#> # … with 1,267 more rows, 12 more variables: species <chr>, feature <chr>,
#> # periods <list>, typochronological_units <list>,
#> # ecochronological_units <list>, site <chr>, country <chr>, lat <chr>,
#> # lng <chr>, site_type <chr>, feature_type <chr>, geometry <POINT [°]>, and
#> # abbreviated variable names ¹delta_c13, ²source_database, ³materialThe result is an sf object, which includes the original
data, plus a geometry column representing the point coordinates and
information on the coordinate reference system used.
Change the crs parameter to transform the geometries
into another coordinate reference system. This can be anything
understood by sf::st_crs()). For example, to use the Swiss
National Grid (EPSG:2056):
chron_as_sf(chron_ch, crs = 2056)
#> Warning: 570 rows with missing or invalid coordinates were removed.
#> Simple feature collection with 1277 features and 21 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: 2341455 ymin: 1090462 xmax: 2825381 ymax: 1289561
#> Projected CRS: CH1903+ / LV95
#> # A tibble: 1,277 × 22
#> id labnr bp std cal_bp cal_std delta…¹ reference sourc…² mater…³
#> * <int> <chr> <int> <int> <lgl> <lgl> <dbl> <list> <chr> <chr>
#> 1 5204 ETH-16… 4370 70 NA NA NA <named list> AgriCh… charco…
#> 2 5205 ETH-18… 4365 65 NA NA NA <named list> AgriCh… charco…
#> 3 5206 ETH-18… 4720 60 NA NA NA <named list> AgriCh… charco…
#> 4 5207 ARC-11… 4490 55 NA NA NA <named list> AgriCh… charco…
#> 5 5208 B-4703 4430 40 NA NA NA <named list> AgriCh… charco…
#> 6 5209 ETH-11… 5140 45 NA NA NA <named list> AgriCh… charco…
#> 7 5210 ARC-10… 5070 145 NA NA NA <named list> AgriCh… charco…
#> 8 5211 ETH-16… 5990 75 NA NA NA <named list> AgriCh… charco…
#> 9 5212 B-4701 5740 50 NA NA NA <named list> AgriCh… charco…
#> 10 5213 ETH-11… 5460 45 NA NA NA <named list> AgriCh… charco…
#> # … with 1,267 more rows, 12 more variables: species <chr>, feature <chr>,
#> # periods <list>, typochronological_units <list>,
#> # ecochronological_units <list>, site <chr>, country <chr>, lat <chr>,
#> # lng <chr>, site_type <chr>, feature_type <chr>, geometry <POINT [m]>, and
#> # abbreviated variable names ¹delta_c13, ²source_database, ³materialSometimes you might see a warning about rows with missing or invalid
coordinates being dropped. This is because it is currently not possible
to include rows without a geometry in a simple features table. To
suppress the warning—and clarify your intent—you may want to explicitly
remove these before calling chron_as_sf():
chron_ch |>
chron_drop_na_coords() |>
chron_as_sf(crs = 2056) ->
chron_chsf and related packages offer many options for manipulating,
analysing, and mapping spatial data. As a simple example, we can plot
the location of our dates using their natural projection (here we use
sf::st_geometry() to plot only the points themselves, not
their data attributes):
plot(sf::st_geometry(chron_ch), graticule = TRUE, axes = TRUE)
See the sf documentation for more options for plotting simple features.
sf objects generally act like data frames, but if
necessary you can explicitly restore the plain table of data with
sf::st_drop_geometry():
chron_ch <- st_drop_geometry(chron_ch)Note that this does not restore any records that were
dropped by chron_as_sf().