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:

  • labnr
  • site
  • site_type
  • country (ideally a two-letter country code, otherwise the function will attempt to interpret it as one using countrycode::countryname())
  • feature
  • material
  • species

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, ³​material

Calibrating 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, ³​material

The 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, ³​material

Sometimes 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_ch

sf 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().