PointedSDMs (version 2.1.3)

specifyMarks: R6 class for creating a specifyMarks object.

Description

A data object containing the data and the relevant information about the integrated model. The function startMarks 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

• specifyMarks$help()

• specifyMarks$print()

• specifyMarks$plot()

• specifyMarks$addBias()

• specifyMarks$updateFormula()

• specifyMarks$changeComponents()

• specifyMarks$priorsFixed()

• specifyMarks$specifySpatial()

• specifyMarks$changeLink()

• specifyMarks$spatialBlock()

• specifyMarks$addSamplers()

• specifyMarks$specifyRandom()

• specifyMarks$new()

• specifyMarks$samplingBias()

---

Method help()

Function to provide documentation for a specifyMarks object.

Usage

specifyMarks$help(...)

Arguments

...

Not used

Returns

Documentation.

---

Method print()

Prints the datasets, their data type and the number of observations, as well as the marks and their respective families.

Usage

specifyMarks$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

specifyMarks$plot(datasetNames, 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.

Boundary

Logical: should a boundary (created using the Mesh object) be used in the plot. Defaults to TRUE.

...

Not used.

Returns

A ggplot object.

Examples

\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 organizedData up
 organizedData <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
  #Create plot of data
  organizedData$plot()
}
}

---

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

specifyMarks$addBias(
  datasetNames = NULL,
  allPO = FALSE,
  biasField = NULL,
  copyModel = TRUE,
  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. 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.

Returns

A bias field to the model.

Examples

\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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
#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

specifyMarks$updateFormula(
  datasetName = NULL,
  Points = TRUE,
  Mark = NULL,
  Formula,
  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.

Mark

Name of the mark (class character) to change the formula for. Defaults to NULL.

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.

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

\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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 #Remove Forest from eBird
   organizedData$updateFormula(datasetName = 'eBird', Mark = 'speciesName', Formula = ~ . - Forest)
 
}
}

---

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

specifyMarks$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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 #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

specifyMarks$priorsFixed(
  Effect,
  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 of species or datasetName).

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.

Returns

New priors for the fixed effects.

Examples

\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 <- startMarks(data, Mesh = mesh, marksIntercept = FALSE,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 #Add prior to Forest
 organizedData$priorsFixed(Effect = 'Intercept', 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

specifyMarks$specifySpatial(
  sharedSpatial = FALSE,
  datasetName,
  Mark,
  Bias,
  PC = TRUE,
  Remove = FALSE,
  ...
)

Arguments

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.

Mark

Name of the marks to specify the spatial field for. If TRUE changes the spatial effect for all marks.

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 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.

Returns

A new model for the spatial effects.

Examples

\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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 #Specify the shared spatial field
 organizedData$specifySpatial(sharedSpatial = 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

specifyMarks$changeLink(datasetName, Mark, Link, ...)

Arguments

datasetName

Name of the dataset 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

Species

Name of the species for which the link function needs to be changed.

Examples

\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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 #Specify the shared spatial field
 organizedData$changeLink(datasetName = 'Parks', 
                          Mark = 'speciesName',
                          Link = 'logit')
 
 
} 
}

---

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

specifyMarks$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 to 1234.

...

Additional arguments used by blockCV's spatialBlock.

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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 #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

specifyMarks$addSamplers(datasetName, Samplers)

Arguments

datasetName

Name of the dataset for the samplers.

Samplers

A Spatial* object representing the integration domain.

Examples

\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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
#Add integration domain for the eBird records
organizedData$addSamplers(datasetName = 'eBird', Samplers = SolitaryTinamou$region)
}
}

---

Method specifyRandom()

Function to specify the models and priors for the random effects included in the model.

Usage

specifyMarks$specifyRandom(
  temporalModel = list(model = "ar1"),
  copyModel = list(beta = list(fixed = FALSE)),
  copyBias = list(beta = list(fixed = FALSE))
)

Arguments

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)).

Returns

An updated component list.

Examples

\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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
#Add integration domain for the eBird records
organizedData$specifyRandom(copyModel =  list(beta = list(fixed = TRUE)))
}
}

---

Method new()

Usage

specifyMarks$new(
  data,
  coordinates,
  projection,
  Inlamesh,
  initialnames,
  responsecounts,
  responsepa,
  marksnames,
  marksfamily,
  pointcovariates,
  trialspa,
  trialsmarks,
  marksspatial,
  spatial,
  intercepts,
  spatialcovariates,
  marksintercepts,
  boundary,
  ips,
  temporal,
  temporalmodel,
  offset,
  copymodel,
  formulas
)

---

Method samplingBias()

Usage

specifyMarks$samplingBias(datasetName, Samplers)

Examples

## ------------------------------------------------
## Method `specifyMarks$plot`
## ------------------------------------------------


if (FALSE) {
 if (requireNamespace('INLA')) {
   
 #Get Data
 library(ggplot2)
 data("SolitaryTinamou")
 proj <- "+proj=longlat +ellps=WGS84"
 data <- SolitaryTinamou$datasets
 mesh <- SolitaryTinamou$mesh
 mesh$crs <- proj
 
 #Set organizedData up
 organizedData <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
  #Create plot of data
  organizedData$plot()

}
}

## ------------------------------------------------
## Method `specifyMarks$addBias`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
#Add bias field to eBird records
organizedData$addBias(datasetNames = 'eBird')

}
}

## ------------------------------------------------
## Method `specifyMarks$updateFormula`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')

 #Remove Forest from eBird
   organizedData$updateFormula(datasetName = 'eBird', Mark = 'speciesName', Formula = ~ . - Forest)
 
}
}

## ------------------------------------------------
## Method `specifyMarks$changeComponents`
## ------------------------------------------------

if (FALSE) {

 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')

 #Remove Forest from components
 organizedData$changeComponents(removeComponent = 'Forest')

}

}

## ------------------------------------------------
## Method `specifyMarks$priorsFixed`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh, marksIntercept = FALSE,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')

 #Add prior to Forest
 organizedData$priorsFixed(Effect = 'Intercept', mean.linear = 2, prec.linear = 0.1)

}
}

## ------------------------------------------------
## Method `specifyMarks$specifySpatial`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')

 #Specify the shared spatial field
 organizedData$specifySpatial(sharedSpatial = TRUE,
                       prior.range = c(1,0.001),
                       prior.sigma = c(1,0.001))

} 
}

## ------------------------------------------------
## Method `specifyMarks$changeLink`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')

 #Specify the shared spatial field
 organizedData$changeLink(datasetName = 'Parks', 
                          Mark = 'speciesName',
                          Link = 'logit')
 
 
} 
}

## ------------------------------------------------
## Method `specifyMarks$spatialBlock`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')

 #Specify the spatial block
 organizedData$spatialBlock(k = 2, rows = 2, cols = 1, plot = FALSE)

} 
}

## ------------------------------------------------
## Method `specifyMarks$addSamplers`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
#Add integration domain for the eBird records
organizedData$addSamplers(datasetName = 'eBird', Samplers = SolitaryTinamou$region)

}
}

## ------------------------------------------------
## Method `specifyMarks$specifyRandom`
## ------------------------------------------------

if (FALSE) {
 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 <- startMarks(data, Mesh = mesh,
                             Projection = proj, responsePA = 'Present',
                             markNames = 'speciesName', 
                             markFamily = 'multinomial')
 
#Add integration domain for the eBird records
organizedData$specifyRandom(copyModel =  list(beta = list(fixed = TRUE)))

}
}