forked from GawainAntell/divvy
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
146 lines (106 loc) · 8.87 KB
/
README.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
143
144
145
146
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = '#>',
fig.path = 'man/figures',
out.width = '40%'
)
```
# divvy
<!-- badges: start -->
[](https://CRAN.R-project.org/package=divvy)
[](https://github.com/GawainAntell/divvy/actions/workflows/R-CMD-check.yaml)
[](https://github.com/GawainAntell/divvy/actions/workflows/test-coverage.yaml)
[](https://app.codecov.io/gh/GawainAntell/divvy)
<!-- badges: end -->
<img src='man/figures/divvy_hex_sticker.png' width='300px' align='right'>
Divvy up diversity into geographic regions of fair comparison!
## Overview
An R package offering spatial subsampling functions for biogeography and biodiversity studies, whether analysing fossil or modern taxon occurrence data, as described by Antell et al. (2023), 'Spatial standardization of taxon occurrence data---a call to action'. A preprint of the *Paleobiology* paper is available at [Earth ArXiv](https://doi.org/10.31223/X5997Z).
Three types of subsampling are available to to standardise the number and maximum spread (dispersion) of sites within a region of specified size:
* `cookies`: Imposes a radial constraint on the spatial bounds of a subsample and standardises area by rarefying the number of localities
* `clustr`: Aggregates sites that are nearest neighbours (connecting them with a minimum spanning tree) to impose a maximum diameter on the spatial bounds of a subsample, and optionally rarefies localities
* `bandit`: Rarefies the number of localities within bands of equal latitude
Additional functions include `uniqify` to subset an occurrence dataset to unique taxon-coordinate combinations, `sdSumry` to calculate basic spatial coverage and diversity metadata for a dataset or its subsamples, `rangeSize` to calculate five measures of geographic range size, and `classRast` to generate a raster containing the most common environment or trait for point occurrences falling in each grid cell.
There are vignettes accompanying the package, to demonstrate use cases of `divvy` functions and describe common considerations for analyses of taxonomic occurrence data. You can view the compiled documents at the [package website](https://gawainantell.github.io/divvy/) under ['Getting started'](https://gawainantell.github.io/divvy/articles/).
## Installation
You can install the newest release of `divvy` from CRAN:
``` r
install.packages('divvy')
```
Alternatively, you can install the development version of `divvy` from [GitHub](https://github.com/) with help from `devtools`:
``` r
# install.packages('devtools')
devtools::install_github('GawainAntell/divvy')
```
## Usage examples
### `bivalves`: Package data
(Palaeo)ecologists often want to inspect basic information about taxon occurrence datasets such as number of occurrences, number of unique localities, general size and position of the study region, and biodiversity. This may be an initial step to become acquainted with the data, or it may be a final step of analysis to estimate ecological variables of interest. Let's load one of the example datasets in with `divvy` to demonstrate some functions that may help analyse it. The occurrences are latitude-longitude point coordinates of Pliocene bivalves from the Paleobiology Database; before proceeding further, let's rasterise these into an equal-area grid, a common starting point for biogeography analysis.
```{r data prep, message=FALSE}
library(divvy)
data('bivalves')
# initialise Equal Earth projected coordinates
library(terra)
rWorld <- rast()
prj <- 'EPSG:8857'
rPrj <- project(rWorld, prj, res = 200000) # 200,000m is approximately 2 degrees
values(rPrj) <- 1:ncell(rPrj)
# coordinate column names for the current and target coordinate reference system
xyCartes <- c('paleolng','paleolat')
xyCell <- c('cellX','cellY')
# extract cell number and centroid coordinates associated with each occurrence
llOccs <- vect(bivalves, geom = xyCartes, crs = 'epsg:4326')
prjOccs <- project(llOccs, prj)
bivalves$cell <- cells(rPrj, prjOccs)[,'cell']
bivalves[, xyCell] <- xyFromCell(rPrj, bivalves$cell)
```
### `uniqify`: Subset to unique occurrences
Now let's examine the data with some `divvy` functions. First, we can apply `uniqify` to leave out any duplicate occurrences of a taxon within a grid cell. This shortens the dataset (and thereby reduces memory use) by more than half.
```{r uniqify example}
nrow(bivalves)
bivalves <- uniqify(bivalves, taxVar = 'genus', xy = xyCell)
nrow(bivalves)
```
### `sdSumry`: Summary spatial and diversity metrics
How many taxa are there? Over how many sites (equal-area grid cells)? How many degrees of latitude do those sites span? The `sdSumry` function returns this and related spatial and diversity metadata.
```{r sdSumry example}
sdSumry(bivalves, taxVar = 'genus', xy = xyCell, crs = prj)
```
There are just over 3000 unique taxon-site occurrences, including 550 genera from 157 grid cells across 137 degrees latitude.
### `rangeSize`: Calculate geographic range size
Maybe we aren't interested in community ecology and instead care about the geographic distribution of focal taxa, such as the mussel *Mytilus* and scallop *Yabepecten*. Provide the coordinates for these two taxa to `divvy`'s `rangeSize` function:
```{r rangeSize example}
myti <- bivalves[bivalves$genus == 'Mytilus', xyCell]
yabe <- bivalves[bivalves$genus == 'Yabepecten', xyCell]
rangeSize(myti, crs = prj)
rangeSize(yabe, crs = prj)
```
*Mytilus* is observed in 18 grid cells spread over tens of thousands of kilometers. In contrast, *Yabepecten* occurs in only two localities, 200 km apart at their grid cell centroids.
If we back-transform the two locality's coordinates from Equal Earth projection to familiar latitude-longitude, we can tell *Yabepecten* has been reported only in northern Honshu, Japan (140-141 E longitude, 40-42 N latitude).
```{r inspect Yabepecten coordinates}
yabeVect <- vect(yabe, geom = xyCell, crs = prj)
project(yabeVect, 'epsg:4326')
```
### `cookies`: Subsample global data into equivalent regions
The `bivalves` dataset spans most of the world's oceans. If we were interested in a question such as how diversity at this Pliocene time step compares against diversity from an earlier interval when geographic sampling coverage was much more limited, we'd have to account for this different data distribution---otherwise, we'd unfairly estimate the well-sampled Pliocene to be far more diverse. Geographic standardisation of both area (acreage or number of sites studied) and dispersion (amount sites are spread apart) allows fair comparisons of ecological variables like richness, whether between time steps, environments, or other comparison groups with heterogeneous spatial coverage.
`divvy` offers three functions for subsampling (`cookies`, `clustr`, and `bandit`) which differ in how they standardise for dispersion. The easiest form of subsampling to visualise is applying a circular constraint to define the bounds of a subsample region. Within that region, a given number of sites are selected, to standardise area. Here, let's take 10 subsamples of the `bivalves` occurrences, each containing 12 sites within a circular region of 1500km (about the size of Australia.)
```{r cookies example}
set.seed(1)
circLocs <- cookies(dat = bivalves, xy = xyCell,
iter = 10, nSite = 12, r = 1500,
crs = prj, output = 'full')
```
Below is a map of one possible subsample (red, with regional constraint drawn around it). Sites not included in the subsample, including one within the regional constraint, are plotted in blue.
<img src='man/figures/bivalves-subsample-map.png' width='600px' align='center'>
An individual subsample (one `data.frame` element of the returned `list` object) contains all occurrences from the subsampled sites. Here's a peek at the first subsample, to show it's just a subset of `bivalves`.
```{r inspect a subsample}
str(circLocs[[1]])
```
Because each subsample has the same information structure as the original dataset, we can analogously calculate summary spatial and diversity data for them using `sdSumry`. Each row of the returned matrix corresponds to one of the ten subsamples. In this small group of replicate subsamples, regional richness ranges from 117 to 194 genera. The number of localities is always 12, as was specified above, and the dispersion of subsamples is always within the upper bound set by the diameter of 3,000km (e.g. maximum great circle distance across any subsample's sites is 2807km).
```{r sdSumry on subsamples}
sdSumry(circLocs, taxVar = 'genus', xy = xyCell, crs = prj)
```