simDynoccSpatial {AHMbook} | R Documentation |

## Simulate data under a dynamic occupancy model with spatial autocorrelation

### Description

Function to simulate detection/nondetection data under a general dynamic site-occupancy model with autocorrelation, including:

* Annual variation in the probabilities of patch persistence, colonization and detection is specified by the bounds of a uniform distribution.

* One covariate is allowed to affect a parameter: a site covariate for psi1, site-by-year covariates for phi and gamma, and an observational covariate for p. Covariates are generated internally from uniform(-2, 2) distributions.

* Additional heterogeneity among sites in persistence and colonization or both.

* Additional detection heterogeneity at the site or survey level, with the possibility of a temporal trend in this heterogeneity over the years. E.g., an annual trend in detection heterogeneity at the site or the survey level is specified by the first and second value, which correspond to the heterogeneity in the first and the last year. Hence, trend.sd.site = c(0, 1) will result in a linear trend in the magnitude of site heterogeneity in detection from 0 in the first year to 1 in the last year.

* A single, spatially structured covariate for habitat suitability may affect all parameters via coefficient beta.XAC; for a biologically reasonable way, choose coefficients with the same sign for all 4 (mediated by underlying density). That spatial covariate is simulated as a Gaussian random field with negative exponential correlation function with 'range parameter' theta.XAC.

* Autologistic effects (beta.Xautolog) in persistence and colonization probability can be chosen, which fits a logistic regression of these parameters on the proportion of occupied neighboring cells (in a queen's or 2nd order neighborhood) during the previous time step.

* Additional detection heterogeneity can be introduced at the site- or the individual survey level, with the possibility of a temporal trend in this heterogeneity. For instance, an annual trend in detection heterogeneity at the site or the survey level is specified by the value in the first and the last year. Hence, trend.sd.site = c(0, 1) will result in a linear trend in the magnitude of site heterogeneity in detection from 0 in the first year to 1 in the last year.

Previous versions used RandomFields, but that is not currently available on CRAN. fields is now used instead, but it cannot deal with large values of `side`

and `theta.XAC`

. If you have RandomFields installed (perhaps by getting it from the CRAN archive), you can load a version of `simDynoccSpatial`

that supports it with `source(system.file("RandomFieldsSupport", "simDynoccSpatial.R", package="AHMbook"))`

.

See also `simDynoccSpatialData`

.

### Usage

```
simDynoccSpatial(side = 50, nyears = 10, nsurveys = 3,
mean.psi1 = 0.4, beta.Xpsi1 = 0,
range.phi = c(0.8, 0.8), beta.Xphi = 0,
range.gamma = c(0.1, 0.1), beta.Xgamma = 0,
range.p = c(0.4, 0.4), beta.Xp = 0,
theta.XAC = 5000, beta.XAC = c(0, 0, 0, 0), beta.Xautolog = c(0, 0),
trend.sd.site = c(0, 0), trend.sd.survey = c(0, 0),
seed.XAC = NA, seed = NULL, show.plots = TRUE, ask.plot = TRUE, verbose = TRUE)
```

### Arguments

`side` |
side length of square simulation area; the number of sites, or cells, M = side^2. |

`nyears` |
Number of years (or 'seasons'). |

`nsurveys` |
Number of replicate surveys (= occasions) within a year. |

`mean.psi1` |
average occupancy probability in first year. |

`beta.Xpsi1` |
coefficient of environmental covariate in probability of initial occupancy. |

`range.phi` |
bounds of uniform distribution from which annual probability of persistence is randomly drawn. |

`beta.Xphi` |
coefficient of environmental covariate in probability of persistence. |

`range.gamma` |
bounds of uniform distribution from which annual probability of colonization is randomly drawn. |

`beta.Xgamma` |
coefficient of environmental covariate in probability of colonization. |

`range.p` |
bounds of uniform distribution from which probability of detection is randomly drawn. |

`beta.Xp` |
coefficient of environmental covariate in probability of detection. |

`theta.XAC` |
'range parameter' of a covariate with exponential spatial correlation (i.e., a Gaussian random field is used as an environmental covariate); must be > 0. |

`beta.XAC` |
vector of coefficients of that field for the 4 model parameters: psi1, phi, gamma, and p (in that order). |

`beta.Xautolog` |
vector of coefficients of autologistic covariate in the following order: persistence (phi), colonization (gamma); the autocovariate is computed at every season as the proportion of occupied cells in a queen's neighborhood around each cell. |

`trend.sd.site` |
initial and final values of sd of normal distribution to model logit-normal noise in p at the site level; a linear trend is assumed over time; if the two values are the same, a constant value is assumed. |

`trend.sd.survey` |
initial and final values of sd of normal distribution to model logit-normal noise in p at the 'survey' level; if they are different, a linear trend is assumed over time. |

`seed.XAC` |
the seed to be used for simulation of the spatially structured covariate for habitat suitability. |

`seed` |
the seed to be used for simulation of values apart from the spatially structured covariate for habitat suitability; using the same value for seed.XAC with different values for seed allows generation of different data sets with the same habitat suitability covariate. |

`show.plots` |
if TRUE, summary plots are displayed. |

`ask.plot` |
If TRUE, pause between plots of results; set to FALSE if running simulations. |

`verbose` |
if TRUE, output will be written to the console. |

### Value

A list with the values of the arguments input and the following additional elements:

`M` |
scalar, total number of pixels in the study area, side^2 |

`grid` |
2-column matrix, x and y coordinates of each pixel |

`amatrix` |
M x M matrix, [i,j] = 1 if cells i and j are neighbors, 0 otherwise |

`Xpsi1` |
side x side matrix, value of covariate affecting initial occupancy |

`Xphi` |
side x side x nyears array, value of covariate affecting persistence |

`Xgamma` |
side x side x nyears array, value of covariate affecting colonization |

`Xp` |
side x side x nsurveys x nyears array, value of covariate affecting detection |

`XAC` |
side x side matrix, the spatially correlated covariate |

`Xauto` |
side x side x nyears array, the autocovariate, the proportion of neighboring cells occupied |

`Xautoobs` |
side x side x nyears array, the observed autocovariate, the proportion of neighboring cells where the species was detected |

`sd.site` |
vector nyears, year-specific values of SD of Gaussian random site effects in p |

`sd.survey` |
vector nyears, year-specific values of SD of Gaussian random survey effects in p |

`mean.phi` |
vector nyears-1, mean persistence for each interval |

`mean.gamma` |
vector nyears-1, mean colonization for each interval |

`mean.p` |
vector nyears, mean detection probability for each year |

`psi` |
side x side x nyears array, probability of occupancy for each site and year |

`mean.psi` |
vector nyears, mean occupancy over cells for each year |

`psi.app` |
vector nyears, apparent occupancy, proportion of cells where species detected |

`z` |
side x side x years array, true occupancy state |

`zobs` |
side x side x years array, observed occupancy state |

`nocc` |
vector nyears, true number of occupied cells |

`nocc.obs` |
vector nyears, number of cells where the species was detected |

`phi` |
side x side x nyears-1 array, probability of persistence in each interval between years |

`gamma` |
side x side x nyears-1 array, probability of colonization in each interval between years |

`p` |
side x side x nsurveys x nyears array, probability of detection |

`y` |
side x side x nsurveys x nyears array, the observed detection history |

`umf` |
an unmarked data frame object with the simulated data |

### Author(s)

Marc Kéry & Andy Royle

### References

Kéry, M. & Royle, J.A. (2021) *Applied Hierarchical Modeling in Ecology* AHM2 - 9.

### Examples

```
# Generate data with the default arguments and look at the structure
try(str(simDynoccSpatial())) # Fails if RandomFields is not available
str(simDynoccSpatial(side=50, theta.XAC=1))
```

*AHMbook*version 0.2.9 Index]