envi (version 0.1.19)

perlrren: Spatially perturb an ecological niche model that uses a log relative risk surface

Description

Estimates the ecological niche of a single species with presence/absence data and two covariates, iteratively, by randomly perturbing ('jittering') the coordinates of observations.

Usage

perlrren(
  obs_ppp,
  covariates,
  predict = TRUE,
  predict_locs = NULL,
  radii = NULL,
  n_sim = 2,
  alpha = 0.05,
  p_correct = "none",
  parallel = FALSE,
  n_core = 2,
  verbose = FALSE,
  ...
)

Value

An object of class "list". This is a named list with the following components:

sim

An object of class 'list' for the summary statistics of the iterative ecological niche.

predict

An object of class 'ppp', a marked point pattern with summary statistics for the iterative ecological niche in geographic space.

The returned sim is a named list with the following components:

lrr_mean

An object of class 'im' for the mean log relative risk surface.

lrr_sd

An object of class 'im' for the standard deviation of log relative risk surface.

pval_mean

An object of class 'im' for the mean p-value surface.

pval_prop

An object of class 'im' for the proportion of iterations were statistically significant surface.

alpha_median

A numeric value of the median critical p-value across all iterations.

If predict = FALSE, the returned predict is empty. If predict = TRUE, the returned predict is an object of class 'ppp' a marked point pattern with the following features:

x

Values for x-coordinate in geographic space (e.g., longitude).

y

Values for y-coordinate in geographic space (e.g., latitude).

v

Values for x-coordinate in covariate space.

z

Values for x-coordinate in covariate space.

lrr_mean

Values for the mean log relative risk surface.

lrr_sd

Values for the standard deviation of log relative risk surface.

pval_mean

Values for the mean p-value surface.

pval_prop

Values for the proportion of iterations were statistically significant surface.

Arguments

obs_ppp

Input object of class 'ppp' a marked point pattern of presence and absence observations with 5 (five) features (columns): 1) ID, 2) longitude, 3) latitude, 4) presence/absence binary variable, 5) ordinal ID for spatial perturbation.

covariates

Input object of class 'imlist' of 2 (two) covariates within the same spatial window and in the same coordinate reference system as obs_ppp.

predict

Logical. If TRUE (the default), will predict the ecological niche in geographic space. If FALSE, will not predict.

predict_locs

Input data frame of prediction locations with 4 features (columns): 1) longitude, 2) latitude, 3) covariate 1 as x-coordinate, 4) covariate 2 as y-coordinate. If unspecified (the default), automatically computed from an 'im' object within covariates.

radii

Vector of length equal to the number of levels of ordinal ID in obs_ppp. Specifies the radii of the spatial perturbation at each level in units equivalent to the coordinate reference system of obs_ppp.

n_sim

Integer, specifying the number of simulation iterations to perform.

alpha

Numeric. The two-tailed alpha level for the significance threshold (default is 0.05).

p_correct

Optional. Character string specifying whether to apply a correction for multiple comparisons including a False Discovery Rate p_correct = "FDR", a Sidak correction p_correct = "Sidak", and a Bonferroni correction p_correct = "Bonferroni". If p_correct = "none" (the default), then no correction is applied.

parallel

Logical. If TRUE, will execute the function in parallel. If FALSE (the default), will not execute the function in parallel.

n_core

Optional. Integer specifying the number of CPU cores on the current host for parallelization (the default is 2 cores).

verbose

Logical. If TRUE (the default), will print function progress during execution. If FALSE, will not print.

...

Arguments passed to lrren.

Details

This function performs a sensitivity analysis of an ecological niche model of a single species (presence/absence data), or the presence of one species relative to another, that uses two covariates. The observation locations (presence and absence data) are randomly spatially perturbed (i.e., "jittered") uniformly within a circular disc of a specified radius centered at their recorded location using the rjitter function. This method simulates the spatial uncertainty of observations, how that may affect the covariate values at each observation (i.e., misclassification error), and the estimated ecological niche based on the two specified covariates. Observations can be grouped into categories of the uncertainty of class 'factor' and can vary by degrees of uncertainty specified using the radii argument.

The function iteratively estimates the ecological niche using the lrren function and computes four summary statistics at every grid cell (i.e., knot) of the estimated surface: 1) mean of the log relative risk, 2) standard deviation of the log relative risk, 3) mean of the asymptotically normal p-value, and 4) proportion of iterations were statistically significant based on a two-tailed alpha-level threshold (argument alpha). The process can be performed in parallel if parallel = TRUE using the future, doFuture, doRNG, and foreach packages. The computed surfaces can be visualized using the plot_perturb function. If predict = TRUE, this function will predict the four summary statistics at every location specified with predict_locs and can also be visualized using the plot_perturb function.

For more information about the spatial perturbation, please refer to the rjitter function documentation.

The function has functionality for a correction for multiple testing. If p_correct = "FDR", calculates a False Discovery Rate by Benjamini and Hochberg. If p_correct = "Sidak", calculates a Sidak correction. If p_correct = "Bonferroni", calculates a Bonferroni correction. If p_correct = "none" (the default), then the function does not account for multiple testing and uses the uncorrected alpha level. See the internal pval_correct function documentation for more details.

Examples

if (interactive()) {
  set.seed(1234) # for reproducibility

# Using the 'bei' and 'bei.extra' data within {spatstat.data}

# Covariate data (centered and scaled)
  ims <- spatstat.data::bei.extra
  ims[[1]]$v <- scale(ims[[1]]$v)
  ims[[2]]$v <- scale(ims[[2]]$v)
  
# Presence data
  presence <- spatstat.data::bei
  spatstat.geom::marks(presence) <- data.frame("presence" = rep(1, presence$n),
                                               "lon" = presence$x,
                                               "lat" = presence$y)
                                          
# (Pseudo-)Absence data
  absence <- spatstat.random::rpoispp(0.008, win = ims[[1]])
  spatstat.geom::marks(absence) <- data.frame("presence" = rep(0, absence$n),
                                              "lon" = absence$x,
                                              "lat" = absence$y)
# Combine into readable format
  obs_locs <- spatstat.geom::superimpose(presence, absence, check = FALSE)
  spatstat.geom::marks(obs_locs)$id <- seq(1, obs_locs$n, 1)
  spatstat.geom::marks(obs_locs) <- spatstat.geom::marks(obs_locs)[ , c(4, 2, 3, 1)]
 
# Specify categories for varying degrees of spatial uncertainty
## Creates three groups
  spatstat.geom::marks(obs_locs)$levels <- as.factor(stats::rpois(obs_locs$n,
                                                                  lambda = 0.05))
                                                                  
# Run perlrren
  test_perlrren <- perlrren(obs_ppp = obs_locs,
                            covariates = ims,
                            radii = c(10, 100, 500),
                            n_sim = 10)
}