dataSDM {PointedSDMs} | R Documentation |
R6 class for creating a dataSDM
object.
Description
A data object containing the data and the relevant information about the integrated model. The function intModel
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.
Methods
Public methods
Method print()
Prints the datasets, their data type and the number of observations, as well as the marks and their respective families.
Usage
dataSDM$print(...)
Arguments
...
Not used.
Method plot()
Makes a plot of the points surrounded by the boundary of the region where they were collected. The points may either be plotted based on which dataset they come from, or which species group they are part of (if speciesName
is non-NULL
in intModel
).
Usage
dataSDM$plot(datasetNames, Species = FALSE, Boundary = TRUE, ...)
Arguments
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
FALSE
.Boundary
Logical: should a boundary (created using the
Mesh
object) be used in the plot. Defaults toTRUE
....
Not used.
Returns
A ggplot object.
Examples
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 <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'), Projection = proj, responsePA = 'Present') #Create plot of data organizedData$plot() }
Method addData()
Function used to add additional datasets to the dataSDM
object. This function should be used if the user would like to add any additional datasets to the integrated model, but do not have the same standardized variable names as those added initially with intModel
. Use ?intModel
for a more comprehensive description on what each argument in this function is used for.
Usage
dataSDM$addData( ..., responseCounts, responsePA, trialsPA, markNames, markFamily, pointCovariates, trialsMarks, speciesName, temporalName, Coordinates, Offset )
Arguments
...
The datasets to be added to the integrated model: should be either
sf
,data.frame
orSpatialPoints*
objects, or a list of objects from these classes.responseCounts
The name of the response variable for the counts data.
responsePA
The name of the response variable for the presence absence data.
trialsPA
The name of the trials variable for the presence absence data.
markNames
The names of the marks found in the data.
markFamily
The associated distributions of the marks.
pointCovariates
The additional, non-spatial covariates describing the data.
trialsMarks
The name of the trials variable for the binomial marks.
speciesName
The name of the species variable included in the data. Used to make a stacked species distribution model.
temporalName
The name of the temporal variable in the datasets.
Coordinates
A vector of length 2 describing the names of the coordinates of the data.
Offset
Name of the offset column in the dataset
Examples
if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" #Only select eBird data ebird <- SolitaryTinamou$datasets$eBird mesh <- SolitaryTinamou$mesh mesh$crs <- proj #Set model up organizedData <- intModel(ebird, Mesh = mesh, Coordinates = c('X', 'Y'), Projection = proj) #Print summary organizedData #Add new dataset Parks = SolitaryTinamou$datasets$Parks organizedData$addData(Parks, responsePA = 'Present') #Print summary organizedData }
Method 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.
Usage
dataSDM$addBias( datasetNames = NULL, allPO = FALSE, biasField = NULL, copyModel = FALSE, shareModel = FALSE, temporalModel = list(model = "ar1") )
Arguments
datasetNames
A vector of dataset names (class
character
) for which a bias field needs to be added to. IfNULL
(default), thenallPO
has to beTRUE
.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 toNULL
which usesinla.spde2.matern
to create a Matern model for the field.shareModel
Share a bias field across the datasets specified with
datasetNames
. Defaults toFALSE
.temporalModel
List of model specifications given to the control.group argument in the time effect component. Defaults to
list(model = 'ar1')
; seecontrol.group
from the INLA package for more details.temporalName
needs to be specified inintModel
prior.
Examples
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 <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'), Projection = proj, responsePA = 'Present') #Add bias field to eBird records organizedData$addBias(datasetNames = 'eBird') }
Method 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.
Usage
dataSDM$updateFormula( datasetName = NULL, Points = TRUE, speciesName = NULL, markName = NULL, Formula, allProcesses = FALSE, newFormula )
Arguments
datasetName
Name of the dataset (class
character
) for which the formula needs to be changed.Points
Logical: should the formula be changed for the points (or otherwise, a marked process). Defaults to
TRUE
. IfFALSE
, thenmarkNames
needs to be non-NULL
inintModel
.speciesName
Name of the species (class
character
) to change the formula for. Defaults toNULL
. IfNULL
andspeciesName
is non-NULL
inintModel
, will update the formula for all species within the dataset. Cannot be non-NULL
ifspeciesName
isNULL
inintModel
.markName
Name of the mark (class
character
) to change the formula for. Defaults toNULL
. IfNULL
andmarkNames
is non-NULL
inintModel
, will update the formula for all marks within the dataset. Cannot be non-NULL
ifmarkNames
isNULL
inintModel
.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.$addComponents
as well.allProcesses
Logical argument: if
TRUE
changes the formulas for all of the processes in a dataset. Defaults toFALSE
.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.
Returns
If Formula
and newFormula
are missing, will print out the formula for the specified processes.
Examples
if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- SolitaryTinamou$covariates$Forest #Set model up organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'), 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('Parks', newFormula = ~ I(. +(Forest+1e-6)*scaling)) #Now dd scaling to components organizedData$changeComponents(addComponent = 'scaling') }
Method 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.
Usage
dataSDM$changeComponents(addComponent, removeComponent, print = TRUE)
Arguments
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
.
Examples
\dontrun{ if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- SolitaryTinamou$covariates$Forest #Set model up organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'), spatialCovariates = Forest, Projection = proj, responsePA = 'Present') #Remove Forest from components organizedData$changeComponents(removeComponent = 'Forest') } }
Method priorsFixed()
Function to change priors for the fixed (and possibly random) effects of the model.
Usage
dataSDM$priorsFixed( Effect, Species = NULL, datasetName = NULL, mean.linear = 0, prec.linear = 0.001 )
Arguments
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 ofspecies
ordatasetName
).Species
Name of the species (class
character
) for which the prior should change. Defaults toNULL
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
.
Examples
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 <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'), spatialCovariates = Forest, Projection = proj, responsePA = 'Present', pointsSpatial = 'individual') #Add prior to Forest organizedData$priorsFixed(Effect = 'Forest', mean.linear = 2, prec.linear = 0.1) }
Method specifySpatial()
Function to specify random fields in the model using penalizing complexity (PC) priors for the parameters.
Usage
dataSDM$specifySpatial( sharedSpatial = FALSE, datasetName, Species, Mark, Bias, PC = TRUE, Copy = NULL, Remove = FALSE, ... )
Arguments
sharedSpatial
Logical: specify the shared spatial field in the model. Requires
pointsSpatial == 'shared'
inintModel
. Defaults toFALSE
.datasetName
Name of which of the datasets' spatial fields to be specified. Requires
pointsSpatial = 'individual'
inintModel
.Species
Name of which of the species' spatial field to be specified. Requires
speciesName
to be non-NULL
inintModel
.Mark
Name of which of the mark' spatial field to be specified. Requires
markNames
to be non-NULL
inintModel
.Bias
Name of the dataset for which the bias field to be specified.
PC
Logical: should the Matern model be specified with pc priors. Defaults to
TRUE
, which usesinla.spde2.pcmatern
to specify the model; otherwise usesinla.spde2.matern
.Remove
Logical: should the chosen spatial field be removed. Requires one of
sharedSpatial
,species
,mark
orbias
to be non-missing, which chooses which field to remove....
Additional arguments used by INLA's
inla.spde2.pcmatern
orinla.spde2.matern
function, dependent on the value ofPC
.
Examples
if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- SolitaryTinamou$covariates$Forest #Set model up organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'), 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)) }
Method changeLink()
Function used to change the link function for a given process.
Usage
dataSDM$changeLink(datasetName, Species, Mark, Link, ...)
Arguments
datasetName
Name of the dataset for which the link function needs to be changed.
Species
Name of the species for which the link function needs to be changed.
Mark
Name of the mark 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.
...
Not used
Examples
\dontrun{ #Create data object dataObj <- intModel(...) #Print link function for a process dataObj$changeLink(Dataset = Dataset, Species = Species) #Change link function dataObj$changeLink(Dataset = Dataset, Species = Species, Link = "log") }
Method 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.
Usage
dataSDM$spatialBlock(k, rows_cols, plot = FALSE, seed = 1234, ...)
Arguments
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 to1234
....
Additional arguments used by blockCV's
spatialBlock
.
Examples
if (requireNamespace('INLA')) { #Get Data data("SolitaryTinamou") proj <- "+proj=longlat +ellps=WGS84" data <- SolitaryTinamou$datasets mesh <- SolitaryTinamou$mesh mesh$crs <- proj Forest <- SolitaryTinamou$covariates$Forest #Set model up organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'), spatialCovariates = Forest, Projection = proj, responsePA = 'Present', pointsSpatial = 'individual') #Specify the spatial block organizedData$spatialBlock(k = 2, rows = 2, cols = 1, plot = FALSE) }
Method addSamplers()
Function to add an integration domain for the PO datasets.
Usage
dataSDM$addSamplers(datasetName, Samplers)
Arguments
datasetName
Name of the dataset for the samplers.
Samplers
A
Spatial*
object representing the integration domain.
Method new()
Usage
dataSDM$new( coordinates, projection, Inlamesh, initialnames, responsecounts, responsepa, speciesindependent, marksnames, marksfamily, pointcovariates, speciesintercept, trialspa, trialsmarks, speciesname, marksspatial, speciesenvironment, spatial, intercepts, spatialcovariates, marksintercepts, boundary, ips, temporal, temporalmodel, speciesspatial, offset, copymodel )
Method samplingBias()
Usage
dataSDM$samplingBias(datasetName, Samplers)
Note
The arguments of this function may be missing (ie not provided) if they have already been specified in intModel
, and do not need changing. Therefore this function is useful if there are some variable names not standardized across the datasets; this function will thus standardize the variable names to those provided initially in intModel
.
Examples
## ------------------------------------------------
## Method `dataSDM$plot`
## ------------------------------------------------
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 <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'),
Projection = proj, responsePA = 'Present')
#Create plot of data
organizedData$plot()
}
## ------------------------------------------------
## Method `dataSDM$addData`
## ------------------------------------------------
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
#Only select eBird data
ebird <- SolitaryTinamou$datasets$eBird
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
#Set model up
organizedData <- intModel(ebird, Mesh = mesh, Coordinates = c('X', 'Y'),
Projection = proj)
#Print summary
organizedData
#Add new dataset
Parks = SolitaryTinamou$datasets$Parks
organizedData$addData(Parks, responsePA = 'Present')
#Print summary
organizedData
}
## ------------------------------------------------
## Method `dataSDM$addBias`
## ------------------------------------------------
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 <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'),
Projection = proj, responsePA = 'Present')
#Add bias field to eBird records
organizedData$addBias(datasetNames = 'eBird')
}
## ------------------------------------------------
## Method `dataSDM$updateFormula`
## ------------------------------------------------
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- SolitaryTinamou$covariates$Forest
#Set model up
organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'),
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('Parks', newFormula = ~ I(. +(Forest+1e-6)*scaling))
#Now dd scaling to components
organizedData$changeComponents(addComponent = 'scaling')
}
## ------------------------------------------------
## Method `dataSDM$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 <- SolitaryTinamou$covariates$Forest
#Set model up
organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'),
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present')
#Remove Forest from components
organizedData$changeComponents(removeComponent = 'Forest')
}
## End(Not run)
## ------------------------------------------------
## Method `dataSDM$priorsFixed`
## ------------------------------------------------
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 <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'),
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present',
pointsSpatial = 'individual')
#Add prior to Forest
organizedData$priorsFixed(Effect = 'Forest', mean.linear = 2, prec.linear = 0.1)
}
## ------------------------------------------------
## Method `dataSDM$specifySpatial`
## ------------------------------------------------
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- SolitaryTinamou$covariates$Forest
#Set model up
organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'),
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))
}
## ------------------------------------------------
## Method `dataSDM$changeLink`
## ------------------------------------------------
## Not run:
#Create data object
dataObj <- intModel(...)
#Print link function for a process
dataObj$changeLink(Dataset = Dataset, Species = Species)
#Change link function
dataObj$changeLink(Dataset = Dataset, Species = Species,
Link = "log")
## End(Not run)
## ------------------------------------------------
## Method `dataSDM$spatialBlock`
## ------------------------------------------------
if (requireNamespace('INLA')) {
#Get Data
data("SolitaryTinamou")
proj <- "+proj=longlat +ellps=WGS84"
data <- SolitaryTinamou$datasets
mesh <- SolitaryTinamou$mesh
mesh$crs <- proj
Forest <- SolitaryTinamou$covariates$Forest
#Set model up
organizedData <- intModel(data, Mesh = mesh, Coordinates = c('X', 'Y'),
spatialCovariates = Forest,
Projection = proj, responsePA = 'Present',
pointsSpatial = 'individual')
#Specify the spatial block
organizedData$spatialBlock(k = 2, rows = 2, cols = 1, plot = FALSE)
}