species_model {intSDM} | R Documentation |
R6 class for creating a species_model
object.
Description
An object containing the data, covariates and other relevant information to be used in the reproducible workflow. The function startWorkflow acts as a wrapper in creating one of these objects. This object has additional slot functions within, which allow for further specification and customization of the reproducible workflow.
Methods
Public methods
Method help()
Obtain documentation for a species_model
object.
Usage
species_model$help(...)
Arguments
...
Not used
Method new()
initialize the species_model object.
Usage
species_model$new( Countries, Species, nameProject, Save, Richness, Directory, Projection, Quiet = TRUE )
Arguments
Countries
Name of the countries to include in the workflow.
Species
Name of the species to include in the workflow.
nameProject
Name of the project for the workflow.
Save
Logical argument indicating if the model outputs should be saved.
Richness
Logical create a species richness model or not.
Directory
Directory where the model outputs should be saved.
Projection
The coordinate reference system used in the workflow.
Quiet
Logical variable indicating if the workflow should provide messages throughout the estimation procedure.
Method addArea()
Usage
species_model$addArea(Object = NULL, countryName = NULL, ...)
Arguments
Object
An
sf
object of the study area. IfNULL
thencountryName
needs to be provided.countryName
Name of the countries to obtain a boundary for. This argument will then use the gisco_get_countries function from the
giscoR
package to obtain a boundary....
Additional arguments passed to gisco_get_countries.
Examples
\dontrun{ workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) #Add boundary workflow$addArea(countryName = 'Sweden') }
Method print()
Prints the datasets, their data type and the number of observations, as well as the marks and their respective families.
Usage
species_model$print(...)
Arguments
...
Not used.
Examples
workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) workflow$print()
Method plot()
Makes a plot of the features used in the integrated model.
Usage
species_model$plot( Mesh = FALSE, Boundary = TRUE, Species = FALSE, Covariates = FALSE )
Arguments
Mesh
Add the mesh to the plot.
Boundary
Add the boundary to the plot.
Species
Add the species location data to the plot.
Covariates
Add the spatial covariates to the plot.
Returns
A ggplot object.
Examples
\dontrun{ workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) #Add boundary workflow$addArea(countryName = 'Germany') workflow$plot(Boundary = TRUE) }
Method workflowOutput()
Function to specify the workflow output from the model. This argument must be at least one of: 'Model'
, 'Prediction'
, 'Maps'
'Cross-validation'
, Bias
and 'Summary'
.
Usage
species_model$workflowOutput(Output)
Arguments
Output
The names of the outputs to give in the workflow. Must be at least one of:
'Model'
,'Prediction'
,'Maps'
,'Bias'
,Summary
and'Cross-validation'
.
Examples
workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) workflow$workflowOutput('Predictions')
Method addStructured()
The function is used to convert structured datasets into a framework which is usable by the model. The three types of structured data allowed by this function are presence-absence (PA), presence-only (PO) and counts/abundance datasets, which are controlled using the datasetType
argument. The other arguments of this function are used to specify the appropriate variable (such as response name, trial name, species name and coordinate name) names in these datasets.
Usage
species_model$addStructured( dataStructured, datasetType, responseName, trialsName, datasetName = NULL, speciesName, coordinateNames, generateAbsences = FALSE )
Arguments
dataStructured
The dataset used in the model. Must be either a
data.frame
,sf
orSpatialPoints*
object, or alist
containing multiples of these classes.datasetType
A vector which gives the type of dataset. Must be either
'count'
,'PO'
or'PA'
.responseName
Name of the response variable in the dataset. If
dataType
is'PO'
, then this argument may be missing.trialsName
Name of the trial name variable in the
PA
datasets.datasetName
An optional argument to create a new name for the dataset. Must be the same length as
dataStructured
if that is provided as alist
.speciesName
Name of the species variable name in the datasets.
coordinateNames
Names of the coordinate vector in the dataset. Only required if the datasets added are
data.frame
objects.generateAbsences
Generates absences for
'PA'
data. This is done by combining all the sampling locations for all the species in a given dataset, and creating an absence where each of the species do not occur. RequiresdatasetType = 'PA'
.
Examples
\dontrun{ workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) #Add boundary workflow$addArea(countryName = 'Sweden') #Generate random species speciesData <- data.frame(X = runif(1000, 12, 24), Y = runif(1000, 56, 68), Response = sample(c(0,1), 1000, replace = TRUE), Name = 'Fraxinus_excelsior') workflow$addStructured(dataStructured = speciesData, datasetType = 'PA', datasetName = 'xx', responseName = 'Response', speciesName = 'Name', coordinateNames = c('X', 'Y')) }
Method addMesh()
Function to add an fm_mesh_2d
object to the workflow. The user may either add their own mesh to the workflow, or use the arguments of this function to help create one.
Usage
species_model$addMesh(Object, ...)
Arguments
Object
An
fm_mesh_2d
object to add to the workflow....
Additional arguments to pass to
fmesher
'sfm_mesh_2d_inla
. Use?fm_mesh_2d_inla
to find out more about the different arguments.
Examples
\dontrun{ workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) #Add boundary workflow$addArea(countryName = 'Sweden') workflow$addMesh(cutoff = 20000, max.edge=c(60000, 80000), offset= 100000) }
Method addGBIF()
Function to add species occurrence records from GBIF (using the rgbif
package) to the reproducible workflow. The arguments for this function are used to either filter the GBIF records, or to specify the characteristics of the observation model.
Usage
species_model$addGBIF( Species = "All", datasetName = NULL, datasetType = "PO", removeDuplicates = FALSE, generateAbsences = FALSE, filterDistance = 0, ... )
Arguments
Species
The names of the species to include in the workflow (initially specified using startWorkflow). Defaults to
All
, which will find occurrence records for all specie specified in startWorkflow.datasetName
The name to give the dataset obtained from GBIF. Cannot be
NULL
.datasetType
The data type of the dataset. Defaults to
PO
, but may also bePA
orCounts
.removeDuplicates
Argument used to remove duplicate observations for a species across datasets. May take a long time if there are many observations obtained across multiple datasets. Defaults to
FALSE
.generateAbsences
Generates absences for
'PA'
data. This is done by combining all the sampling locations for all the species, and creating an absence where a given species does not occur.filterDistance
Remove all points that are x kilometers away from the boundary polygon. Value must be provided in kilometers. Defaults to 0 km which removes no points.
...
Additional arguments to specify the occ_data function from
rgbif
. See?occ_data
for more details.
Examples
\dontrun{ workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) workflow$addArea(countryName = 'Sweden') workflow$addGBIF(datasetName = 'exampleGBIF', datasetType = 'PA', limit = 10000, coordinateUncertaintyInMeters = '0,50') }
Method addCovariates()
Function to add spatial covariates to the workflow. The covariates may either be specified by the user, or they may come from worldClim obtained with the geodata
package.
Usage
species_model$addCovariates( Object = NULL, worldClim = NULL, landCover = NULL, res = 2.5, Months = "All", Function = "mean", ... )
Arguments
Object
A object of class:
spatRaster
,SpatialPixelsDataFrame
orraster
containing covariate information across the area. Note that this function will check if the covariates span the boundary area, so it may be preferable to add your own boundary using`.$addArea`
if this argument is specified.worldClim
Name of the worldClim to include in the model. See
?worldclim_country
from thegeodata
package for more information.landCover
Name of the land cover covariates to include in the model. See
?landcover
from thegeodata
package for more information.res
Resolution of the worldclim variable. Valid options are:
10
,5
,2.5
or0.5
(minutes of a degree).Months
The months to include the covariate for. Defaults to
All
which includes covariate layers for all months.Function
The function to aggregate the temporal data into one layer. Defaults to
mean
....
Not used.
Examples
\dontrun{ if (requireNamespace('INLA')) { workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) #Add boundary workflow$addArea(countryName = 'Sweden') workflow$addCovariates(worldClim = 'tavg', res = '10') } }
Method crossValidation()
Function to add a spatial cross validation method to the workflow.
Usage
species_model$crossValidation( Method, blockOptions = list(k = 5, rows_cols = c(4, 4), plot = FALSE, seed = 123), blockCVType = "DIC" )
Arguments
Method
The spatial cross-validation methods to use in the workflow. May be at least one of
spatialBlock
orLoo
(leave-one-out). See thePointedSDMs
package for more details.blockOptions
A list of options to specify the spatial block cross-validation. Must be a named list with arguments specified for:
k
,rows_cols
,plot
,seed
. SeeblockCV::cv_spatial
for more information.blockCVType
The cross-validation method to complete if
Method = 'spatialBlock'
. May be one of'DIC'
(default) which will iteratively return the DIC scores for each block, or'Predict'
. This method return scores of marginal likelihood for each combination of dataset across all blocks, by fitting a model on all blocks but one, and predicting on the left out block. The prediction dataset is automatically chosen as the first PA dataset added to the model. See blockedCV for more information. Note that this may take a long time to estimate if there are many datasets included in the model.
Examples
workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) workflow$crossValidation(Method = 'Loo')
Method modelOptions()
Function to specify model options for the INLA
and PointedSDMs
parts of the model.
Usage
species_model$modelOptions(ISDM = list(), Richness = list())
Arguments
ISDM
Arguments to specify in startISDM from the
PointedSDMs
function. This argument needs to be a named list of the following options:pointCovariates
: non-spatial covariates attached to the data points to be included in the model.pointsIntercept
: Logical: intercept terms for the dataset. Defaults toTRUE
pointsSpatial
: Choose how the spatial effects are included in the model. If'copy'
then the spatial effects are shared across the datasets, if'individual'
then the spatial effects are created for each dataset individually, and if'correlate'
then the spatial effects are correlated. IfNULL
, then spatial effects are turned off for the datasets.Offset
: The name of the offset variable.
See
?PointedSDMs::startISDM
for more details on these choices.Richness
Options to specify the richness model. This argument needs to be a named list of the following options:
predictionIntercept
: The name of the dataset to use as the prediction intercept in the richness model. The sampling size of the protocol must be known.samplingSize
: The sample area size for the dataset provided inpredictionIntercept
. The units should be the same as specified in startWorkflowspeciesSpatial
: Specify the species spatial model. If'replicate'
then create a spatial effect for each species with shared hyperparameters, if'copy'
create a spatial effect for each species. IfNULL
then the spatial effects for the species will be turned off.speciesIntercept:
IfTRUE
(default) incorporate a random intercept for the species, ifFALSE
use a fixed intercept and ifNULL
include no intercept for the species.
Examples
workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example'))
Method specifySpatial()
Function to specify pc priors for the shared random field in the model. See ?INLA::inla.spde2.pcmatern
for more details.
Usage
species_model$specifySpatial(...)
Arguments
...
Arguments passed on to inla.spde2.pcmatern.
Examples
\dontrun{ if (requireNamespace('INLA')) { workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) #Add boundary workflow$addArea(countryName = 'Sweden') workflow$addMesh(cutoff = 20000, max.edge=c(60000, 80000), offset= 100000) workflow$specifySpatial(prior.range = c(200000, 0.05), prior.sigma = c(5, 0.1)) } }
Method specifyPriors()
Function to specify priors for the fixed effects in the model. The priors of the fixed effects are assumed to be Gaussian; this function alows the user to specify the parameters of this distribution.
Usage
species_model$specifyPriors( effectNames, Mean = 0, Precision = 0.01, copyModel = list(beta = list(fixed = FALSE)), priorIntercept = list(prior = "loggamma", param = c(1, 5e-05)), priorGroup = list(model = "iid", hyper = list(prec = list(prior = "loggamma", param = c(1, 5e-05)))) )
Arguments
effectNames
The name of the effects to specify the prior for. Must be the name of any of the covariates incldued in the model, or 'Intercept' to specify the priors for the intercept terms.
Mean
The mean of the prior distribution. Defaults to
0
.Precision
The precision (inverse variance) of the prior distribution. Defaults to
0.01
.copyModel
List of model specifications given to the hyper parameters for the
"copy"
model. Defaults tolist(beta = list(fixed = FALSE))
.priorIntercept
Prior for the precision parameter for the random intercept in the species richness model. Needs
Output = "Richness"
. Defaults to the default INLA prior.priorGroup
Prior for the precision for the iid effect in the species spatial effect in the richness model. Needs
Output = "Richness"
andspeciesSpatial = "replicate"
in the richness options. Defualts to the default INLA prior.
Examples
\dontrun{ if (requireNamespace('INLA')) { workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) #Add boundary workflow$addArea(countryName = 'Sweden') workflow$addMesh(cutoff = 20000, max.edge=c(60000, 80000), offset= 100000) workflow$specifyPriors(effectName = 'Intercept', mean = 0, Precision = 0.1) } }
Method biasFields()
Function to add bias fields to the model.
Usage
species_model$biasFields( datasetName, copyModel = FALSE, shareModel = FALSE, ... )
Arguments
datasetName
Name of the dataset to add a bias field to.
copyModel
Create copies of the biasField across the different datasets. Defaults to
FALSE
.shareModel
Share a bias field across the datasets specified with
datasetNames
. Defaults toFALSE
....
Additional arguments passed on to inla.spde2.pcmatern to customize the priors for the pc matern for the bias fields.
Examples
\dontrun{ if(requireNamespace('INLA')) { workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) workflow$addArea(countryName = 'Sweden') workflow$addGBIF(datasetName = 'exampleGBIF', datasetType = 'PA', limit = 10000, coordinateUncertaintyInMeters = '0,50') workflow$biasFields(datasetName = 'exampleGBIF') } }
Method modelFormula()
Add a formula to the model
Usage
species_model$modelFormula(covariateFormula, biasFormula)
Arguments
covariateFormula
Change the covariate formula of the model.
biasFormula
Change the bias formula of the model
Examples
\dontrun{ workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) workflow$addArea(countryName = 'Sweden') workflow$addCovariate(rasterStack) workflow$addFormula(covariateFormula = ~ covariate) workflow$addFormula(biasFormula = ~ biasFormula) }
Method obtainMeta()
Obtain metadata from the workflow.
Usage
species_model$obtainMeta(Number = TRUE, Citations = TRUE)
Arguments
Number
Print the number of observations per dataset. Defaults to
TRUE
.Citations
Print the citations for the GBIF obtained datasets. Defaults to
TRUE
.
Examples
\dontrun{ workflow <- startWorkflow(Species = 'Fraxinus excelsior', Projection = '+proj=longlat +ellps=WGS84', Save = FALSE, saveOptions = list(projectName = 'example')) workflow$addArea(countryName = 'Sweden') workflow$addGBIF(datasetName = 'exampleGBIF', datasetType = 'PA', limit = 10000, coordinateUncertaintyInMeters = '0,50') workflow$obtainMeta() }
Method clone()
The objects of this class are cloneable with this method.
Usage
species_model$clone(deep = FALSE)
Arguments
deep
Whether to make a deep clone.
Examples
## ------------------------------------------------
## Method `species_model$addArea`
## ------------------------------------------------
## Not run:
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
#Add boundary
workflow$addArea(countryName = 'Sweden')
## End(Not run)
## ------------------------------------------------
## Method `species_model$print`
## ------------------------------------------------
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
workflow$print()
## ------------------------------------------------
## Method `species_model$plot`
## ------------------------------------------------
## Not run:
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
#Add boundary
workflow$addArea(countryName = 'Germany')
workflow$plot(Boundary = TRUE)
## End(Not run)
## ------------------------------------------------
## Method `species_model$workflowOutput`
## ------------------------------------------------
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
workflow$workflowOutput('Predictions')
## ------------------------------------------------
## Method `species_model$addStructured`
## ------------------------------------------------
## Not run:
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
#Add boundary
workflow$addArea(countryName = 'Sweden')
#Generate random species
speciesData <- data.frame(X = runif(1000, 12, 24),
Y = runif(1000, 56, 68),
Response = sample(c(0,1), 1000, replace = TRUE),
Name = 'Fraxinus_excelsior')
workflow$addStructured(dataStructured = speciesData, datasetType = 'PA',
datasetName = 'xx', responseName = 'Response',
speciesName = 'Name', coordinateNames = c('X', 'Y'))
## End(Not run)
## ------------------------------------------------
## Method `species_model$addMesh`
## ------------------------------------------------
## Not run:
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
#Add boundary
workflow$addArea(countryName = 'Sweden')
workflow$addMesh(cutoff = 20000,
max.edge=c(60000, 80000),
offset= 100000)
## End(Not run)
## ------------------------------------------------
## Method `species_model$addGBIF`
## ------------------------------------------------
## Not run:
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
workflow$addArea(countryName = 'Sweden')
workflow$addGBIF(datasetName = 'exampleGBIF',
datasetType = 'PA',
limit = 10000,
coordinateUncertaintyInMeters = '0,50')
## End(Not run)
## ------------------------------------------------
## Method `species_model$addCovariates`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
#Add boundary
workflow$addArea(countryName = 'Sweden')
workflow$addCovariates(worldClim = 'tavg', res = '10')
}
## End(Not run)
## ------------------------------------------------
## Method `species_model$crossValidation`
## ------------------------------------------------
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
workflow$crossValidation(Method = 'Loo')
## ------------------------------------------------
## Method `species_model$modelOptions`
## ------------------------------------------------
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
## ------------------------------------------------
## Method `species_model$specifySpatial`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
#Add boundary
workflow$addArea(countryName = 'Sweden')
workflow$addMesh(cutoff = 20000,
max.edge=c(60000, 80000),
offset= 100000)
workflow$specifySpatial(prior.range = c(200000, 0.05),
prior.sigma = c(5, 0.1))
}
## End(Not run)
## ------------------------------------------------
## Method `species_model$specifyPriors`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
#Add boundary
workflow$addArea(countryName = 'Sweden')
workflow$addMesh(cutoff = 20000,
max.edge=c(60000, 80000),
offset= 100000)
workflow$specifyPriors(effectName = 'Intercept', mean = 0, Precision = 0.1)
}
## End(Not run)
## ------------------------------------------------
## Method `species_model$biasFields`
## ------------------------------------------------
## Not run:
if(requireNamespace('INLA')) {
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
workflow$addArea(countryName = 'Sweden')
workflow$addGBIF(datasetName = 'exampleGBIF',
datasetType = 'PA',
limit = 10000,
coordinateUncertaintyInMeters = '0,50')
workflow$biasFields(datasetName = 'exampleGBIF')
}
## End(Not run)
## ------------------------------------------------
## Method `species_model$modelFormula`
## ------------------------------------------------
## Not run:
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
workflow$addArea(countryName = 'Sweden')
workflow$addCovariate(rasterStack)
workflow$addFormula(covariateFormula = ~ covariate)
workflow$addFormula(biasFormula = ~ biasFormula)
## End(Not run)
## ------------------------------------------------
## Method `species_model$obtainMeta`
## ------------------------------------------------
## Not run:
workflow <- startWorkflow(Species = 'Fraxinus excelsior',
Projection = '+proj=longlat +ellps=WGS84',
Save = FALSE,
saveOptions = list(projectName = 'example'))
workflow$addArea(countryName = 'Sweden')
workflow$addGBIF(datasetName = 'exampleGBIF',
datasetType = 'PA',
limit = 10000,
coordinateUncertaintyInMeters = '0,50')
workflow$obtainMeta()
## End(Not run)