/
xronos.Rmd
142 lines (103 loc) · 5.19 KB
/
xronos.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
---
title: "Chronological data from XRONOS in R"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Chronological data from XRONOS in R}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
[XRONOS](https://xronos.ch) 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
```{r setup}
library(xronos)
```
## Get chronological data
`chron_data()` provides an R interface to [XRONOS' REST API](https://xronos.ch/api) for retrieving chronological data.
Without further parameters, it will request all available data from XRONOS.
```{r get-all-data, eval=FALSE}
chron_data()
```
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()](https://vincentarelbundock.github.io/countrycode/reference/countryname.html))
* `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:
```{r get-swiss-data}
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):
```{r show-swiss-data}
chron_ch
```
## 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:
```{r calibrate, message=FALSE}
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:
```{r plot-cal}
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:
```{r as-sf}
library(sf)
chron_as_sf(chron_ch)
```
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](https://epsg.io/2056)):
```{r as-sf-projected}
chron_as_sf(chron_ch, crs = 2056)
```
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()`:
```{r as-sf-complete}
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):
```{r plot-sf}
plot(sf::st_geometry(chron_ch), graticule = TRUE, axes = TRUE)
```
See the [sf documentation](https://r-spatial.github.io/sf/articles/sf5.html) 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()`:
```{r undo-sf}
chron_ch <- st_drop_geometry(chron_ch)
```
Note that this does *not* restore any records that were dropped by `chron_as_sf()`.