-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME.Rmd
169 lines (109 loc) · 6.46 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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
---
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/README-",
out.width = "100%"
)
```
# PointedSDMs
<!-- badges: start -->
[](https://github.com/PhilipMostert/PointedSDMs/actions/workflows/R-CMD-check.yaml)[](https://app.codecov.io/gh/PhilipMostert/PointedSDMs?branch=ChangingToR6) [](https://zenodo.org/badge/latestdoi/368823136)
<!-- badges: end -->
The goal of *PointedSDMs* is to simplify the construction of integrated species distribution models (ISDMs) for large collections of heterogeneous data. It does so by building wrapper functions around [inlabru](https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.13168), which uses the [INLA methodology](https://rss.onlinelibrary.wiley.com/doi/abs/10.1111/j.1467-9868.2008.00700.x) to estimate a class of latent Gaussian models.
## Installation
You can install the development version of PointedSDMs from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("PhilipMostert/PointedSDMs")
```
or directly through CRAN using:
``` r
install.packages('PointedSDMs')
```
## Package functionality
*PointedSDMs* includes a selection of functions used to streamline the construction of ISDMs as well and perform model cross-validation. The core functions of the package are:
| Function name | Function description |
|-------------------|-----------------------------------------------------|
| `startISDM()` | Initialize and specify the components used in the integrated model. |
| `startSpecies()` | Initialize and specify the components used in the multi-species integrated model. |
| `blockedCV()` | Perform spatial blocked cross-validation. |
| `fitISDM()` | Estimate and preform inference on the integrated model. |
| `datasetOut()` | Perform dataset-out cross-validation, which calculates the impact individual datasets have on the full model. |
The function `intModel()` produces an [R6](https://github.com/r-lib/R6) object, and as a result there are various *slot functions* available to further specify the components of the model. These *slot functions* include:
| `intModel()` slot function | Function description |
|--------------------|----------------------------------------------------|
| `` `.$help()` `` | Show documentation for each of the slot functions. |
| `` `.$plot()` `` | Used to create a plot of the available data. The output of this function is an object of class [`gg`](https://github.com/tidyverse/ggplot2). |
| `` `.$addBias()` `` | Add an additional spatial field to a dataset to account for sampling bias in unstructured datasets. |
| `` `.$updateFormula()` `` | Used to update a formula for a process. The idea is to start specify the full model with `startISDM()`, and then thin components per dataset with this function. |
| `` `.$updateComponents()` `` | Change or add new components used by [inlabru](https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.13168) in the integrated model. |
| `` `.$priorsFixed()` `` | Change the specification of the prior distribution for the fixed effects in the model. |
| `` `.$specifySpatial()` `` | Specify the spatial field in the model using penalizing complexity (PC) priors. |
| `` `.$spatialBlock()` `` | Used to specify how the points are spatially blocked. Spatial cross-validation is subsequently performed using `blockedCV()`. |
| `` `.$addSamplers()` `` | Function to add an integration domain for the PO datasets. |
| `` `.$specifyRandom()` `` | Specify the priors for the random effects in the model. |
| `` `.$changeLink()` `` | Change the link function of a process. |
## Example
This is a basic example which shows you how to specify and run an integrated model, using three disparate datasets containing locations of the solitary tinamou (*Tinamus solitarius)*.
```{r setup, include=FALSE}
knitr::opts_chunk$set(warning = FALSE, message = FALSE)
```
```{r example}
library(PointedSDMs)
library(ggplot2)
library(terra)
```
```{r data}
bru_options_set(inla.mode = "experimental")
#Load data in
data("SolitaryTinamou")
projection <- "+proj=longlat +ellps=WGS84"
species <- SolitaryTinamou$datasets
covariates <- terra::rast(system.file('extdata/SolitaryTinamouCovariates.tif',
package = "PointedSDMs"))
mesh <- SolitaryTinamou$mesh
```
Setting up the model is done easily with `startISDM()`, where we specify the required components of the model:
```{r intModel, message = FALSE, warning = FALSE}
#Specify model -- here we run a model with one spatial covariate and a shared spatial field
model <- startISDM(species, spatialCovariates = covariates,
Projection = projection, Mesh = mesh, responsePA = 'Present')
```
We can also make a quick plot of where the species are located using `` `.$plot()` ``:
```{r plot, warning = FALSE, message = FALSE, fig.width=8, fig.height=5}
region <- SolitaryTinamou$region
model$plot(Boundary = FALSE) +
geom_sf(data = st_boundary(region))
```
To improve stability, we specify priors for the intercepts of the model using `` `.$priorsFixed()` ``
```{r specifyPriors}
model$priorsFixed(Effect = 'Intercept',
mean.linear = 0,
prec.linear = 1)
```
And *PC* priors for the spatial field using `` `.$specifySpatial()` ``:
```{r specifySpatial}
model$specifySpatial(sharedSpatial = TRUE,
prior.range = c(0.2, 0.1),
prior.sigma = c(0.1, 0.1))
```
We can then estimate the parameters in the model using the `fitISDM()` function:
```{r fitISDM, warning = FALSE, message = FALSE}
modelRun <- fitISDM(model, options = list(control.inla =
list(int.strategy = 'eb'),
safe = TRUE))
summary(modelRun)
```
*PointedSDMs* also includes generic predict and plot functions:
```{r predict_and_plot, warning = FALSE, message = FALSE, fig.width=8, fig.height=5}
predictions <- predict(modelRun, mesh = mesh,
mask = region,
spatial = TRUE,
fun = 'linear')
plot(predictions, variable = c('mean', 'sd'))
```