Learn R Programming
⚠️There's a newer version (2.1.3) of this package.Take me there.

PointedSDMs

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, which uses the INLA methodology to estimate a class of latent Gaussian models.

Installation

You can install the development version of PointedSDMs from GitHub with:

# install.packages("devtools")
devtools::install_github("PhilipMostert/PointedSDMs")

or directly through CRAN using:

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 nameFunction 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 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 functionFunction 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.
`.$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 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).


library(PointedSDMs)
library(ggplot2)
library(terra)

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:


#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()`:


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()`


model$priorsFixed(Effect = 'Intercept',
                  mean.linear = 0, 
                  prec.linear = 0.11)

And PC priors for the spatial field using `.$specifySpatial()`:


model$specifySpatial(sharedSpatial = TRUE,
                     prior.range = c(50, 0.1),
                     prior.sigma = c(0.1, 0.1))

We can then estimate the parameters in the model using the fitISDM() function:


modelRun <- fitISDM(model, options = list(control.inla = list(int.strategy = 'eb',
                                                              diagonal = 0.1), 
                                          safe = TRUE))
summary(modelRun)
#> inlabru version: 2.10.1
#> INLA version: 24.03.20
#> Components:
#> eBird_spatial: main = spde(geometry), group = exchangeable(1L), replicate = iid(1L)
#> Parks_spatial(=eBird_spatial): main = unknown(geometry), group = exchangeable(1L), replicate = iid(1L)
#> Gbif_spatial(=eBird_spatial): main = unknown(geometry), group = exchangeable(1L), replicate = iid(1L)
#> Forest: main = linear(Forest), group = exchangeable(1L), replicate = iid(1L)
#> NPP: main = linear(NPP), group = exchangeable(1L), replicate = iid(1L)
#> Altitude: main = linear(Altitude), group = exchangeable(1L), replicate = iid(1L)
#> eBird_intercept: main = linear(1), group = exchangeable(1L), replicate = iid(1L)
#> Parks_intercept: main = linear(1), group = exchangeable(1L), replicate = iid(1L)
#> Gbif_intercept: main = linear(1), group = exchangeable(1L), replicate = iid(1L)
#> Likelihoods:
#>   Family: 'cp'
#>     Data class: 'sf', 'data.frame'
#>     Predictor: geometry ~ .
#>   Family: 'binomial'
#>     Data class: 'sf', 'data.frame'
#>     Predictor: Present ~ .
#>   Family: 'cp'
#>     Data class: 'sf', 'data.frame'
#>     Predictor: geometry ~ .
#> Time used:
#>     Pre = 2.41, Running = 17.7, Post = 0.319, Total = 20.5 
#> Fixed effects:
#>                   mean    sd 0.025quant 0.5quant 0.975quant   mode kld
#> Forest           0.027 0.004      0.019    0.027      0.034  0.027   0
#> NPP              0.000 0.000      0.000    0.000      0.000  0.000   0
#> Altitude        -0.001 0.000     -0.001   -0.001      0.000 -0.001   0
#> eBird_intercept -6.857 0.283     -7.412   -6.857     -6.301 -6.857   0
#> Parks_intercept -6.089 0.401     -6.875   -6.089     -5.302 -6.089   0
#> Gbif_intercept  -7.415 0.317     -8.037   -7.415     -6.793 -7.415   0
#> 
#> Random effects:
#>   Name     Model
#>     eBird_spatial SPDE2 model
#>    Parks_spatial Copy
#>    Gbif_spatial Copy
#> 
#> Model hyperparameters:
#>                          mean    sd 0.025quant 0.5quant 0.975quant  mode
#> Range for eBird_spatial 2.915 0.278      2.417    2.898      3.511 2.858
#> Stdev for eBird_spatial 0.923 0.058      0.814    0.921      1.042 0.918
#> Beta for Parks_spatial  0.020 0.062     -0.103    0.021      0.141 0.023
#> Beta for Gbif_spatial   0.441 0.054      0.335    0.440      0.549 0.438
#> 
#> Deviance Information Criterion (DIC) ...............: -650.55
#> Deviance Information Criterion (DIC, saturated) ....: NA
#> Effective number of parameters .....................: -1472.94
#> 
#> Watanabe-Akaike information criterion (WAIC) ...: 1580.61
#> Effective number of parameters .................: 331.43
#> 
#> Marginal log-Likelihood:  -1607.03 
#>  is computed 
#> Posterior summaries for the linear predictor and the fitted values are computed
#> (Posterior marginals needs also 'control.compute=list(return.marginals.predictor=TRUE)')

PointedSDMs also includes generic predict and plot functions:


predictions <- predict(modelRun, mesh = mesh,
                       mask = region, 
                       spatial = TRUE,
                       fun = 'linear')

plot(predictions, variable = c('mean', 'sd'))

Copy Link

Version

Install

install.packages('PointedSDMs')

Monthly Downloads

293

Version

2.1.2

License

GPL (>= 3)

Issues

5

Pull Requests

0

Stars

26

Forks

6

Maintainer

Philip Mostert

Last Published

August 21st, 2024

Functions in PointedSDMs (2.1.2)

print.blockedCV

Print function for blockedCV.
intModel

intModel: Function used to initialize the integrated species distribution model.
print.blockedCVpred

Print function for blockedCV.
print.modISDM

Generic print function for modISDM.
datasetOut-class

Export class bru_sdm_leave_one_out
dataSet

Internal function used to standardize datasets, as well as assign metadata.
changeCoords

changeCoords: function used to change coordinate names.
modMarks_predict-class

Export class predict_modMarks
print.datasetOut

Generic print function for datasetOut.
modSpecies-class

Export modSpecies class
bruSDM_predict-class

Export class predict_bru_sdm
runModel

runModel: function used to run the integrated model. Note that this function is depreciated, and will be removed in a later version of the package.
removeFormula

removeFormula: Function to remove term from a formula.
eBird

data.frame object containing solitary tinamou observations from eBird
blockedCV

blockedCV: run spatial blocked cross-validation on the integrated model.
datasetOut

datasetOut: function that removes a dataset out of the main model, and calculates some cross-validation score.
modSpecies_predict-class

Export class predict_modSpecies
makeLhoods

makeLhoods: function to make likelihoods.
modISDM-class

Export modISDM class
checkCoords

checkCoords: function used to check coordinate names.
nameChanger

nameChanger: function to change a variable name.
print.modMarks

Generic print function for modMarks.
modISDM_predict-class

Export class predict.modISDM
modMarks-class

Export modMarks class
makeFormulaComps

makeFormulaComps: function to make components for the covariate and bias Formulas.
predict.bruSDM

Generic predict function for bru_SDM objects.
print.bruSDM

Generic print function for bruSDM.
print.bruSDM_predict

Generic print function for bru_sdm_predict.
plot.bruSDM_predict

Generic plot function for predict_bru_sdm.
checkVar

checkVar: Function used to check variable names.
summary.bruSDM

Generic summary function for bruSDM.
reduceComps

reduceComps: Reduce the components of the model.
startSpecies

startSpecies: Function used to initialize a multi-species integrated species distribution model.
startMarks

startMarks: Function used to initialize a marked-point process model.
print.modSpecies

Generic print function for modSpecies.
region

sf object containing the boundary region for solitary tinamouc
fitISDM

fitISDM: function used to run the integrated model.
specifySpecies

R6 class for creating a startSpecies object.
specifyMarks

R6 class for creating a specifyMarks object.
specifyISDM

R6 class for creating a startISDM object.
startISDM

startISDM: Function used to initialize the integrated species distribution model.
elev_raster

Raster object containing the elevation across Pennsylvania state.
SolTinCovariates

spatRaster object containing covariate values
blockedCVpred-class

Export class blockedCVpred
bruSDM-class

Export bru_sdm class
blockedCV-class

Export class blockedCV
Parks

data.frame object containing solitary tinamou observations from Parks
BBSColinusVirginianus

Dataset of Colinus Virginianus obtained from the North American Breeding Bird survey across Alabama state.
BBA

Dataset of setophaga caerulescens obtained from the Pennsylvania Atlas of Breeding Birds.
Koala

Dataset of Eucalyptus globulus (common name: blue gum) sightings collected across the Koala conservation reserve on Phillip island (Australia) between 1993 and 2004. Two marks are considered from this dataset: "koala" which describes the number of koala visits to each tree, and "food" which is some index of the palatability of the leaves.
Gbif

data.frame object containing solitary tinamou observations from Gbif
SetophagaData

List of all data objects used for the Setophaga vignette.
NLCD_canopy_raster

Raster object containing the canopy cover across Pennsylvania state.
data2ENV

data2ENV: function used to move objects from one environment to another.
BBS

Dataset of setophaga caerulescens obtained from the North American Breeding Bird survey across Pennsylvania state.
SolitaryTinamou

List of all data objects used for the solitary tinamou vignette.
dataOrganize

R6 class to assist in reformatting the data to be used in dataSDM.