specifySpecies | R Documentation |
startSpecies
object.A data object containing the data and the relevant information about the integrated model. The function startSpecies
acts as a wrapper in creating one of these objects. The output of this object has additional functions within the object which allow for further specification and customization of the integrated model.
help()
Function to provide documentation for a specifySpecies
object.
specifySpecies$help(...)
...
Not used
Documentation.
print()
Prints the datasets, their data type and the number of observations, as well as the marks and their respective families.
specifySpecies$print(...)
...
Not used.
plot()
Makes a plot of the points surrounded by the boundary of the region where they were collected.
specifySpecies$plot(datasetNames, Species = TRUE, Boundary = TRUE, ...)
datasetNames
Name of the datasets to plot. If this argument is missing, the function will plot all the data available to the model.
Species
Logical: should the points be plotted based on the species name. Defaults to TRUE
.
Boundary
Logical: should a boundary (created using the Mesh
object) be used in the plot. Defaults to TRUE
.
...
Not used.
A ggplot object.
\dontrun{ if (requireNamespace('INLA')) { #Get Data library(ggplot2) data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', Projection = proj, responsePA = 'Present') #Create plot of data organizedData$plot() } }
addBias()
Function used to add additional spatial fields (called bias fields) to a selected dataset present in the integrated model. Bias fields are typically used to account for sampling biases in opportunistic citizen science data in the absence of any covariate to do such.
specifySpecies$addBias( datasetNames = NULL, allPO = FALSE, biasField = NULL, copyModel = TRUE, shareModel = FALSE, temporalModel = list(model = "ar1") )
datasetNames
A vector of dataset names (class character
) for which a bias field needs to be added to. If NULL
(default), then allPO
has to be TRUE
.
allPO
Logical: should a bias field be added to all datasets classified as presence only in the integrated model. Defaults to FALSE
.
biasField
An inla.spde
object used to describe the bias field. Defaults to NULL
which uses inla.spde2.matern
to create a Matern model for the field.
copyModel
Create copy models for all the of the datasets specified with either datasetNames
or allPO
. The first dataset in the vector will have its own spatial effect, and the other datasets will "copy" the effect with shared hyperparameters. Defaults to TRUE
.
shareModel
Share a bias field across the datasets specified with datasetNames
. Defaults to FALSE
.
temporalModel
List of model specifications given to the control.group argument in the time effect component. Defaults to list(model = 'ar1')
; see control.group
from the INLA package for more details. temporalName
needs to be specified in intModel
prior.
A bias field to the model.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', Projection = proj, responsePA = 'Present') #Add bias field to eBird records organizedData$addBias(datasetNames = 'eBird') } }
updateFormula()
Function used to update the formula for a selected observation model. The function is designed to work similarly to the generic update
formula, and should be used to thin terms out of a process from the full model specified in intModel
. The function also allows the user to add their own formula to the model, such that they can include non-linear components in the model. The function can also be used to print out the formula for a process by not specifying the Formula
or newFormula
arguments.
specifySpecies$updateFormula( datasetName = NULL, speciesName = NULL, Formula, processLevel = FALSE, newFormula )
datasetName
Name of the dataset (class character
) for which the formula needs to be changed.
speciesName
Name of the species for which to change a formula for. Defaults to NULL
which chnages the formula for all species present in datasetName
.
Formula
An updated formula to give to the process. The syntax provided for the formula in this argument should be identical to the formula specification as in base R. Should be used to thin terms out of a formula but could be used to add terms as well. If adding new terms not specified in intModel
, remember to add the associated component using .$changeComponents
as well.
processLevel
Logical argument: if TRUE
changes the formulas for all of the processes in a dataset. Defaults to FALSE
.
newFormula
Completely change the formula for a process – primarily used to add non-linear components into the formula. Note: all terms need to be correctly specified here.
An updated formula.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- terra::rast( system.file( 'extdata/SolitaryTinamouCovariates.tif', package = "PointedSDMs"))$Forest #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', spatialCovariates = Forest, Projection = proj, responsePA = 'Present', pointsSpatial = 'individual') #Remove Forest from eBird organizedData$updateFormula(datasetName = 'eBird', Formula = ~ . - Forest) #Add some scaling to Forest for Parks organizedData$updateFormula(datasetName ='Parks', newFormula = ~ I(. +(Forest+1e-6)*scaling)) #Now dd scaling to components organizedData$changeComponents(addComponent = 'scaling') } }
changeComponents()
Function to add and specify custom components to model, which are required by inlabru. The main purpose of the function is to re-specify or completely change components already in the model, however the user can also add completely new components to the model as well. In this case, the components need to be added to the correct formulas in the model using the .$updateFormula
function. If addComponent
and removeComponent
are both missing, the function will print out the components to be supplied to inlabru's bru
function.
specifySpecies$changeComponents(addComponent, removeComponent, print = TRUE)
addComponent
Component to add to the integrated model. Note that if the user is re-specifying a component already present in the model, they do not need to remove the old component using removeComponent
.
removeComponent
Component (or just the name of a component) present in the model which should be removed.
print
Logical: should the updated components be printed. Defaults to TRUE
.
An updated components list.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- terra::rast( system.file( 'extdata/SolitaryTinamouCovariates.tif', package = "PointedSDMs"))$Forest #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', spatialCovariates = Forest, Projection = proj, responsePA = 'Present') #Remove Forest from components organizedData$changeComponents(removeComponent = 'speciesSpatial') } }
priorsFixed()
Function to change priors for the fixed (and possibly random) effects of the model.
specifySpecies$priorsFixed( Effect, Species = NULL, datasetName = NULL, mean.linear = 0, prec.linear = 0.001 )
Effect
Name of the fixed effect covariate to change the prior for. Can take on 'intercept'
, which will change the specification for an intercept (specified by one of species
or datasetName
).
Species
Name of the species (class character
) for which the prior should change. Defaults to NULL
which will change the prior for all species added to the model.
datasetName
Name of the dataset for which the prior of the intercept should change (if fixedEffect = 'intercept'). Defaults to NULL
which will change the prior effect of the intercepts for all the datasets in the model.
mean.linear
Mean value for the prior of the fixed effect. Defaults to 0
.
prec.linear
Precision value for the prior of the fixed effect. Defaults to 0.001
.
New priors for the fixed effects.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- terra::rast( system.file( 'extdata/SolitaryTinamouCovariates.tif', package = "PointedSDMs"))$Forest #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', spatialCovariates = Forest, Projection = proj, responsePA = 'Present', pointsSpatial = 'individual') #Add prior to Forest organizedData$priorsFixed(Effect = 'Forest', mean.linear = 2, prec.linear = 0.1) } }
specifySpatial()
Function to specify random fields in the model using penalizing complexity (PC) priors for the parameters.
specifySpecies$specifySpatial( sharedSpatial = FALSE, datasetName, Species, Bias, PC = TRUE, Remove = FALSE, ... )
sharedSpatial
Logical: specify the shared spatial field in the model. Requires pointsSpatial == 'shared'
in intModel
. Defaults to FALSE
.
datasetName
Name of which of the datasets' spatial fields to be specified. Requires pointsSpatial = 'individual'
in intModel
.
Species
Name of the species to change the spatial effect for. If TRUE
then changes the spatial effect for the shared species field.
Bias
Logical: specify the spatial field for the bias effect. If seperate fields are specified for different fields, the argument may be the name of the dataset for which the bias field to be specified. #' @param PC Logical: should the Matern model be specified with pc priors. Defaults to TRUE
, which uses inla.spde2.pcmatern
to specify the model; otherwise uses inla.spde2.matern
.
Remove
Logical: should the chosen spatial field be removed. Requires one of sharedSpatial
, species
, mark
or bias
to be non-missing, which chooses which field to remove.
...
Additional arguments used by INLA's inla.spde2.pcmatern
or inla.spde2.matern
function, dependent on the value of PC
.
A new model for the spatial effects.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- terra::rast( system.file( 'extdata/SolitaryTinamouCovariates.tif', package = "PointedSDMs"))$Forest #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', spatialCovariates = Forest, Projection = proj, responsePA = 'Present') #Specify the shared spatial field organizedData$specifySpatial(sharedSpatial = TRUE, PC = TRUE, prior.range = c(1,0.001), prior.sigma = c(1,0.001)) } }
changeLink()
Function used to change the link function for a given process.
specifySpecies$changeLink(datasetName, Link, ...)
datasetName
Name of the dataset for which the link function needs to be changed.
Link
Name of the link function to add to the process. If missing, will print the link function of the specified dataset.
A new link function for a process.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- terra::rast( system.file( 'extdata/SolitaryTinamouCovariates.tif', package = "PointedSDMs"))$Forest #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', spatialCovariates = Forest, Projection = proj, responsePA = 'Present') #Specify the shared spatial field organizedData$changeLink('Parks', 'logit') } }
spatialBlock()
Function to spatially block the datasets, which will then be used for model cross-validation with blockedCV
. See the spatialBlock
function from blockCV for how the spatial blocking works and for further details on the function's arguments.
specifySpecies$spatialBlock(k, rows_cols, plot = FALSE, seed = 1234, ...)
k
Integer value reflecting the number of folds to use.
rows_cols
Integer value by which the area is divided into longitudinal and latitudinal bins.
plot
Plot the cross-validation folds as well as the points across the boundary. Defaults to FALSE
.
seed
Seed used by blockCV's spatialBlock
to make the spatial blocking reproducible across different models. Defaults to 1234
.
...
Additional arguments used by blockCV's spatialBlock
.
If plot = TRUE
, a plot of the grid.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- terra::rast( system.file( 'extdata/SolitaryTinamouCovariates.tif', package = "PointedSDMs"))$Forest #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', spatialCovariates = Forest, Projection = proj, responsePA = 'Present', pointsSpatial = 'individual') #Specify the spatial block organizedData$spatialBlock(k = 2, rows = 2, cols = 1, plot = FALSE) } }
addSamplers()
Function to add an integration domain for the PO datasets.
specifySpecies$addSamplers(datasetName, Samplers)
datasetName
Name of the dataset for the samplers.
Samplers
A Spatial*
object representing the integration domain.
New samplers for a process.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', Projection = proj, responsePA = 'Present') #Add integration domain for the eBird records organizedData$addSamplers(datasetName = 'eBird', Samplers = SolitaryTinamou$region) } }
specifyRandom()
Function to specify the models and priors for the random effects included in the model.
specifySpecies$specifyRandom( temporalModel = list(model = "ar1"), copyModel = list(beta = list(fixed = FALSE)), copyBias = list(beta = list(fixed = FALSE)), speciesCopy = list(beta = list(fixed = FALSE)), speciesIntercepts = list(prior = "loggamma", param = c(1, 5e-05)), speciesGroup = list(model = "iid", hyper = list(prec = list(prior = "loggamma", param = c(1, 5e-05)))) )
temporalModel
List of model specifications given to the control.group argument in the time effect component. Defaults to list(model = 'ar1')
; see control.group
from the INLA package for more details.
copyModel
List of model specifications given to the hyper parameters for the "copy"
model. Defaults to list(beta = list(fixed = FALSE))
.
copyBias
List of model specifications given to the hyper parameters for the "copy"
bias model. Defaults to list(beta = list(fixed = FALSE))
.
speciesCopy
List of model specifications given to the hyper parameters for the species "copy"
model. Defaults to list(beta = list(fixed = FALSE))
.
speciesIntercepts
Prior distribution for precision parameter for the random species intercept term. Defaults to INLA
's default choice.
speciesGroup
Prior distribution for the precision parameter for the iid group model. Defaults to INLA
's default.
#' @return An updated component list.
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj #Set model up organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName', Projection = proj, responsePA = 'Present', pointsSpatial = copy) #Add integration domain for the eBird records organizedData$specifyRandom(copyModel = list(beta = list(fixed = TRUE))) } }
new()
specifySpecies$new( data, projection, Inlamesh, initialnames, responsecounts, responsepa, pointcovariates, speciesintercept, trialspa, spatial, intercepts, spatialcovariates, boundary, ips, temporal, temporalmodel, offset, copymodel, formulas, speciesindependent, speciesname, speciesenvironment, speciesspatial )
samplingBias()
specifySpecies$samplingBias(datasetName, Samplers)
## ------------------------------------------------
## Method `specifySpecies$plot`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
library(ggplot2)
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
Projection = proj,
responsePA = 'Present')
#Create plot of data
organizedData$plot()
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$addBias`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
Projection = proj,
responsePA = 'Present')
#Add bias field to eBird records
organizedData$addBias(datasetNames = 'eBird')
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$updateFormula`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- terra::rast(
system.file(
'extdata/SolitaryTinamouCovariates.tif',
package = "PointedSDMs"))$Forest
#Set model up
organizedData <- startSpecies(data, Mesh = mesh, speciesName = 'speciesName',
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present',
pointsSpatial = 'individual')
#Remove Forest from eBird
organizedData$updateFormula(datasetName = 'eBird', Formula = ~ . - Forest)
#Add some scaling to Forest for Parks
organizedData$updateFormula(datasetName ='Parks', newFormula = ~ I(. +(Forest+1e-6)*scaling))
#Now dd scaling to components
organizedData$changeComponents(addComponent = 'scaling')
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$changeComponents`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- terra::rast(
system.file(
'extdata/SolitaryTinamouCovariates.tif',
package = "PointedSDMs"))$Forest
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
spatialCovariates = Forest,
Projection = proj,
responsePA = 'Present')
#Remove Forest from components
organizedData$changeComponents(removeComponent = 'speciesSpatial')
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$priorsFixed`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- terra::rast(
system.file(
'extdata/SolitaryTinamouCovariates.tif',
package = "PointedSDMs"))$Forest
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present',
pointsSpatial = 'individual')
#Add prior to Forest
organizedData$priorsFixed(Effect = 'Forest', mean.linear = 2, prec.linear = 0.1)
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$specifySpatial`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- terra::rast(
system.file(
'extdata/SolitaryTinamouCovariates.tif',
package = "PointedSDMs"))$Forest
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present')
#Specify the shared spatial field
organizedData$specifySpatial(sharedSpatial = TRUE, PC = TRUE,
prior.range = c(1,0.001),
prior.sigma = c(1,0.001))
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$changeLink`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- terra::rast(
system.file(
'extdata/SolitaryTinamouCovariates.tif',
package = "PointedSDMs"))$Forest
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present')
#Specify the shared spatial field
organizedData$changeLink('Parks', 'logit')
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$spatialBlock`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- terra::rast(
system.file(
'extdata/SolitaryTinamouCovariates.tif',
package = "PointedSDMs"))$Forest
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present',
pointsSpatial = 'individual')
#Specify the spatial block
organizedData$spatialBlock(k = 2, rows = 2, cols = 1, plot = FALSE)
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$addSamplers`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
Projection = proj, responsePA = 'Present')
#Add integration domain for the eBird records
organizedData$addSamplers(datasetName = 'eBird', Samplers = SolitaryTinamou$region)
}
## End(Not run)
## ------------------------------------------------
## Method `specifySpecies$specifyRandom`
## ------------------------------------------------
## Not run:
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
#Set model up
organizedData <- startSpecies(data, Mesh = mesh,
speciesName = 'speciesName',
Projection = proj,
responsePA = 'Present',
pointsSpatial = copy)
#Add integration domain for the eBird records
organizedData$specifyRandom(copyModel = list(beta = list(fixed = TRUE)))
}
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.