scrdesignGA: Generating near-optimal sampling designs for spatial...
In jaroyle/oSCR: Multi-Session Sex-Structured Spatial Capture-Recapture Models

scrdesignGA

R Documentation

Generating near-optimal sampling designs for spatial capture-recapture.

Description

Given any SCR-sensible objective function, scrdesignGA() implements a genetic algorithm to solve this k-of-n design problem. In the context of SCR, and for a given objective function and landscape, the function finds the best subset of sampling locations (k) from all possible sampling locations (n) . The arguments of this function that are related to the biology of the species should be parameterized using the values that are expected, preferrably informed by previous research.

Usage

scrdesignGA(statespace = NULL, alltraps = NULL, fixedtraps = NULL,
            ntraps = 9, beta0 = -0.2*5, sigma = 2, N = 100, crit = 1, 
            verbose = 1, ...)

Arguments

`statespace`	A discretized representation of the study area (state-space), defined as a convex hull around the trapping extent with an additional buffer of approximately `3*sigma` to ensure the incorporation of the activity centers of all individuals that could be captured.
`alltraps`	A two-column dataframe, labelled X and Y accordingly, comprised of all possible trapping locations. These locations should be user-defined after accounting for logistic constraints, primarily accessibility. Design generation then relies on subsetting these locations.
`fixedtraps`	A two-column dataframe, labelled X and Y accordingly, comprised of any fixed sampling locations (e.g., an existing grid around which an optimal design is to be found). The algorithm will find `k` additional locations conditional on the location of these fixed sampling points.
`ntraps`	The number of traps available for constructing the design. More traps will allow for a larger sample size, providing more data to an SCR model, resulting in improvement in terms of bias and precision of estimates.
`beta0`	The probability of encounter of an individual across occassions at its activtiy center, specified here as the logaritm of baseline detection probability (`p0`) multiplied by the number of sampling occasions, i.e., `log(p0*K)`.
`sigma`	The spatial scaling parameter in the half-normal encounter model, which relates the baseline encounter probability, `p0`, to the distance between the individual's activity center and the location of the trap where it was captured.
`N`	The number of individuals in the landscape, which is used to determine population density in the statespace.
`crit`	Integer. The design criteria used in the objective function for optimization. Available options are model-based criteria, which optimize: `crit = 1` The probability of capture. `crit = 2` The probability of capture at more than one trap. `crit = 3` An intermediate between criteria 1 and 2. `crit = 4` The probability of more than one capture. Additionally, user-defined criteria can also be implement, see `oSCR::scrdesignOF` for more details.
`...`	Below are the descriptions used in the help file for `kofnGA::kofnGA()` (credit to the authors of `kofnGA`)
`popsize`	The size of the population; equivalently, the number of offspring produced each generation.
`keepbest`	The `keepbest` least fit offspring each generation are replaced by the `keepbest` most fit members of the previous generation. Used to implement elitism.
`ngen`	The number of generations to run.
`cluster`	If non-null, the objective function evaluations for each generation are done in parallel. `cluster` can be either a cluster as produced by `makeCluster`, or an integer number of parallel workers to use. If an integer, `makeCluster(cluster)` will be called to create a cluster, which will be stopped on function exit.
`verbose`	An integer controlling the display of progress during search. If `verbose` takes positive value `v`, then the iteration number and best objective function value are displayed at the console every `v` generations. Otherwise nothing is displayed. Default is zero (no display).

Value

A list of class "scrdesign" with the following elements:

`des`	A list containing the resulting components of the design-finding process. For more information, see `kofnGA::kofnGA()`.
`statespace`	A 3-column dataframe containing the coordinates (X and Y) and the expected per-pixel density of the discretized state-space.
`alltraps`	A 2-column dataframe containing the coordinates (X and Y) of all possible locations available for traps.
`optimaltraps`	Most importantly, the optimal design produced by the algorithm. A 2-column dataframe containing the selected coordinates (X and Y) of each trap.
`sigma`	The value of sigma, the spatial scaling parameter in the half-normal encounter model, originally specified by the user.
`beta0`	The value of the encounter probability across sampling occasions, as originally specified by the user.

Note

For best designs, ngen should be ~1500+. Further, the kofnGA package recommends popsize = 200, and keepbest = 20 for best performance.

References

TBD

Examples


#----Load the package----

library(oSCR)


#----Load data from Pakistan----

data(pakistan) 
# This loads the statespace: pakSS 
# and the possible trap locations: pakTT


#----Plot this data----

plot(pakSS, asp=1, pch=16, col="grey")
points(pakTT, pch=20, cex = 0.5)


#----Run the design-finding algo----

test_design <- scrdesignGA(
  statespace = pakSS, alltraps = pakTT,  # Study area components
  ntraps = 25,                           # Number of available traps
  beta0 = 0.2*5, sigma = 3, crit = 1,    # Expected data
  popsize = 50, keepbest= 5, ngen = 50   # GA settings 
  ) # FOR BEST DESIGNS: ngen should be ~1500


#----Plot the results----

par(mfrow=c(1,3))          # Setup plotting area
plot(test_design, which=4) # which = 4 plots all three together
par(mfrow=c(1,1))          # Reset plotting area

jaroyle/oSCR documentation built on Sept. 23, 2023, 12:46 p.m.