scampr: Spatially correlated, approximate modelling of presences in R

In ElliotDovers/scampr: Spatially Correlated, Approximate Modelling of Point patterns in R

Spatially correlated, approximate modelling of presences in R

Description

This is the main function for modelling presences within the scampr framework. The type of model will depend on the arguments provided. This can be used to model point patterns as a log-Gaussian Cox process (LGCP) or Inhomogeneous Poisson process (IPP), as well as, jointly fitting a model to presence-only and presence/absence data if both are provided. This function can also fit binary regression with a complimentary log-log link function (with optional spatial random effects) when model.type = "PA".

When model.type = "PO", the function will fit either an IPP, or LGCP model to the point pattern (depending on argument include.sre). This uses numerical quadrature (provided with the data, see e.g. scampr::gorillas) to approximate the spatial integral. If fitting a LGCP, uses one of either a Laplace or variational approximation to marginalise over the latent field according to sre.approx.

When model.type = "PA", the function will fits a binary regression model to presence/absence data using a complimentary log-log link function. Can accommodate an approximate latent field as spatial random effects (depending on argument include.sre).

When model.type = "IDM", the function jointly fits a model to presence-only and presence/absence data as linked by response to environmental predictors provided in each formula. The presence-only formula must also contain biasing predictors to account for opportunistic collection. If argument include.sre equals TRUE, then the two data sources will additionally share a latent Gaussian random field. Observer bias in the presence-only data can be modelled using measured variables via the argument bias.formula or as unmeasured effects with a second latent Gaussian field if latent.po.biasing == TRUE (the default). Either formula accepts an offset term - an offset in formula will apply to the presence/absence data while one in bias.formula will apply to the presence-only data.

Usage

scampr(
  formula,
  data,
  bias.formula,
  pa.data,
  po.data,
  coord.names = c("x", "y"),
  quad.weights.name = "quad.size",
  include.sre = TRUE,
  sre.approx = c("variational", "laplace"),
  model.type = c("PO", "PA", "IDM"),
  basis.functions,
  bf.matrix.type = c("sparse", "dense"),
  latent.po.biasing = TRUE,
  po.biasing.basis.functions,
  prune.bfs = 4,
  se = TRUE,
  starting.pars,
  subset,
  maxit = 100,
  ...
)

Arguments

formula	an object of class "formula" (or one that can be coerced to that class): a symbolic description of the fixed effects of the model to be fitted. The 'response' must be a binary that indicates whether a datum is a presence or: quadrature point (for point process models)/ absence (for binary models). See GLM function for further formula details.
data	a data frame containing response and predictors within formula. Usually defaults to the point pattern and quadrature but will attempt to cleverly determine this via model.type, e.g., this is assumed to be presence/absence data when model.type='PA'. Otherwise, use po.data and/or pa.dtaa to supply the appropriate data frame explicitly.
bias.formula	an object of class "formula" (or one that can be coerced to that class). This is a symbolic description of the predictors included to account for bias in the presence-only data (no response term is needed).
pa.data	an optional data frame. When fitting an integrated data model use this to pass in the presence/absence data.
po.data	an optional data frame. Can be use to explicitly define the presence-only data (and quadrature) when fitting an integrated data model.
coord.names	a vector of character strings describing the column names of the coordinates in both data frames.
quad.weights.name	a character string of the column name of quadrature weights in the data.
include.sre	a logical indicating whether to fit the model with spatial random effects (SRE).
sre.approx	a character string indicating the type of approximation to be used to marginalise over the spatial random effects. May be one of 'laplace' or 'variational'.
model.type	a character string indicating the type of data to be used. May be one of 'PO' (for a presence-only PPM) or 'PA' (for a presence/absence Binary GLM) or 'IDM' (for an integrated data model).
basis.functions	an optional object of class 'Basis' created by FRK::auto_basis() or 'bf.df' created by scampr::simple_basis(). Either object describes a set of basis functions for approximating the latent Gaussian field. If NULL the model will use default FRK::auto_basis() with max_basis = 0.25 * # of points.
bf.matrix.type	a character string, one of 'sparse' or 'dense' indicating whether to use sparse or dense matrix computations for the basis functions created.
latent.po.biasing	a logical, applying only to IDM, indicating whether biasing in the presence-only data should be accounted for via an additional latent field. Default is true as this is the most flexible approach unless good measured PO biasing variables are available.
po.biasing.basis.functions	an optional extra set of basis functions that can be used when latent.po.biasing = TRUE, otherwise basis.functions are used.
prune.bfs	an integer indicating the number of presence-only records required within a basis function's radius for it NOT to be pruned. Applies to the PO and IDM model (additionally, within the presence-only biasing basis functions in the IDM case) to assist with stability in model convergence. Default is zero, i.e. no pruning.
se	a logical indicating whether standard errors should be calculated.
starting.pars	an optional named list or previously fit scampr model object that gives warm starting values for the parameters of the model.
subset	an optional vector describing a subset of the data to be used. Not applicable to integrated data models.
maxit	a numeric indicating the maximum number of iterations for the optimizer. Default is 100 as the optimizer uses a gradient based approach.

Value

a scampr model object

Examples

# Get the flora data for one of the species
dat_po <- flora$po$sp1
dat_pa <- flora$pa

# obtain a sample of 10,000 quadrature points for the point process model
set.seed(1)
quad.pts <- flora$quad[sample(1:nrow(flora$quad), 10000, replace = F), ]
set.seed(NULL)

# Attach the quadrature points to the presence-only data
dat_po <- rbind.data.frame(dat_po, quad.pts)

# Ensure the "response" variable in each data set shares the same name
dat_po$presence <- dat_po$pres
dat_pa$presence <- dat_pa$sp1

# Fit models without a latent effects
# Point Process Model
m.ipp <- scampr(presence ~ MNT + D.Main, dat_po, include.sre = F)
# Binary Regression
m.bin <- scampr(presence ~ MNT, dat_pa, include.sre = F, model.type = "PA")
# Integrated Data Model
m.comb <- scampr(presence ~ MNT, dat_po, bias.formula = ~ D.Main,
pa.data = dat_pa, include.sre = F, model.type = "IDM", latent.po.biasing = F)

# Set up a simple 2D grid of basis functions to fit a LGCP model to the data
bfs <- simple_basis(nodes.on.long.edge = 9, data = dat_po)

## Not run: 
# Fit with a shared latent field (LGCP) #
# Point Process Model
m.lgcp <- scampr(presence ~ MNT + D.Main, dat_po, basis.functions = bfs)
# Binary Regression with spatial random effects
m.bin_w_sre <- scampr(presence ~ MNT, dat_pa, basis.functions = bfs, model.type = "PA")
# Integrated Data Model with spatial random effects
m.comb_w_sre <- scampr(presence ~ MNT, dat_po, ~ D.Main,
dat_pa, basis.functions = bfs, model.type = "IDM")

## End(Not run)

ElliotDovers/scampr documentation built on March 17, 2024, 3:27 p.m.