In alexdiana1992/FastOccupancy: Fast Bayesian occupancy models

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(FastOccupancy)

The fitting is performed using the function runModel. The functions fits the model described in Diana et al. (2021). The following model configurations can be chosen:

usingYearDetProb: when set to TRUE, this commands fits the model using year-specific intercepts for detection probabilities. If set to FALSE, the intercept is constant across year.
usingSpatial: when set to TRUE, this commands fits the model using spatial autocorrelated random effects for the occupancy probability (in addition to independent site-specific random effects).

Data format

Sample data to feed to the function runModel are provided in the object sampleData.

head(sampleData)

In the data, each row needs to correspond to a detection, with information of each detection in the columns.

runModel requires the user to input the data and the indexes of the column corresponding to the information for each detection (year, site and detection outcome).

Covariates for the occupancy and detection probability can be easily added through the model via the arguments covariates_psi_text and covariates_p_text. The format accepted is a string with the indexes of the column separated by a comma (for example "5" or "6,7").

Model fitting

modelResults <- runModel(sampleData, 
                         index_year = 1, 
                         index_site = 2, 
                         index_occ = 8, 
                         index_spatial_x = 3, 
                         index_spatial_y = 4, 
                         covariates_psi_text = "5", 
                         covariates_p_text = "6-7", 
                         usingSpatial = TRUE,
                         gridStep = .2, 
                         nchain = 1, 
                         nburn = 100,
                         niter = 100)

Choosing the grid

In case the autocorrelated spatial random effect are added to the model (usingSpatial = T), the width of the squares for the spatial approximation needs to be chosen. The package provides the function buildSpatialGrid to visualize the approximation for a given value of the grid step and the number of squares associated.

buildSpatialGrid(sampleData$X, sampleData$Y, gridStep = .3)

Note that decreasing the width leads to an increased number of squares, which increases the computational time required to fit the model

Analyzing the output

The model output can be analyzed through the functions provided with the package. We provide functions for plotting summaries and printing outputs.

For plotting, we provide the functions:

plotOccupancyIndex: Plots estimates of the occupancy index.

plotOccupancyIndex(modelResults)

plotSpatialSiteEffect: Plots a map with the posterior means of the spatial site effect.
plotOccupancyCovariatesEffect: Plots estimates of coefficients for the covariates of the occupancy probability.
plotBaseLineCaptureProb: Plots estimates of the detection probability.
plotDetectionCovariatesEffect: Plots estimates of coefficients for the covariates of the detection probability.

For printing, we provide the functions:

printOccupancyIndex: Prints estimates of the occupancy index.
printOccupancyCovariatesEffect: Prints estimates of coefficients for the covariates of the occupancy probability.
printBaseLineCaptureProb: Prints estimates of the detection probability.
printDetectionCovariatesEffect: Prints estimates of coefficients for the covariates of the detection probability.

Moreover, goodness of fit as described in the paper can be performed through the functions:

plotGOFYearDetections: Goodness of fit of the yearly detections.
plotGOFSpaceDections: Goodness of fit of the detections in each region.

Diagnostics

The package provides function to produce traceplots to assess convergence. The functions provided are:

tracePlot_OccupancyYearEffect: Traceplots of the year-specific random effects.

tracePlot_OccupancyYearEffect(modelResults, 1)

tracePlot_OccupancySiteEffect: Traceplots of the site-specific random effects.
tracePlot_OccupancyCovariate: Traceplot of the covariates of the occupancy probability.
tracePlot_DetectionIntercept: Traceplot of the intercept of the detection probability.
tracePlot_DetectionCovariate: Traceplot of the covariates of the detection probability.