occModel: Specify and Fit a Multi-scale Occupancy Model

In RobertDorazio/eDNAoccupancy: Multi-scale Occupancy Modeling of Environmental DNA Data

Specify and Fit a Multi-scale Occupancy Model

Description

This function specifies and fits a multi-scale occupancy model.

Usage

occModel(formulaSite = ~1, formulaSiteAndSample = ~1,
  formulaReplicate = ~1, detectionMats, siteData = NULL,
  siteAndSampleData = NULL, niter = 1100, niterInterval = 100,
  siteColName = "site", sampleColName = "sample")

Arguments

formulaSite	model of occurrence at a site
formulaSiteAndSample	model of occurrence in different samples of a site
formulaReplicate	model of detection in replicates of a sample
detectionMats	list containing y: M x J matrix of numbers of detections per sample K: M x J matrix of numbers of replicates per sample where M = no. sites and J = maximum no. samples per site
siteData	data frame containing site-level covariates
siteAndSampleData	data frame containing site- and sample-level covariates
niter	no. iterations of MCMC algorithm
niterInterval	no. iterations for reporting progress of MCMC algorithm
siteColName	column of data frame siteData (or column of data frame siteAndSampleData) containing sites (i.e., primary sample units)
sampleColName	column of data frame siteData (or column of data frame siteAndSampleData) containing sample numbers (i.e., integers 1, 2, ...) for each site

Details

This function is used to specify and fit a multi-scale occupancy model (with or without covariates). The model is fitted using Bayesian methods (specifically, a Markov chain Monte Carlo (MCMC) algorithm that is run for a finite number of iterations). Additional MCMC iterations may be computed using the function updateOccModel. Output from the MCMC algorithm is stored in the file "mc.csv" and can be summarized using functions plotTrace, plotACF, and posteriorSummary.

Value

A list (object of class occModel) containing the following objects:

niterations:

total number of iterations MCMC algorithm was run

state:

the value of each model parameter after the last iteration of the MCMC algorithm

y:

M x J matrix of numbers of detections per sample

K:

M x J matrix of numbers of replicates per sample

X:

matrix of regressors associated with model parameter beta

W:

array of regressors associated with model parameter alpha

V:

array of regressors associated with model parameter delta

siteEffectInW:

logical indicator of whether model parameter alpha contains M elements (that is, one element per site)

colNamesOfX:

vector of names of regressors in X

colNamesOfW:

vector of names of regressors in W

colNamesOfV:

vector of names of regressors in V

where M = no. sites and J = maximum no. samples per site

Note

Before fitting the model, this function checks to ensure that the model specification is possible given the data files. These checks include:

• Value of siteColName matches that in data frame siteData.

• Values of siteColName and sampleColName match those in data frame siteAndSampleData.

• Values in sampleColName contain consecutive positive integers (1, 2, ...) for each site.

• Only one data frame (siteData or siteAndSampleData) is specified for survey data.

If any of these checks fail, the function returns an error message.

See Also

updateOccModel, scaleData

Examples

data(gobyDetectionData)
detections = occData(gobyDetectionData, "site", "sample")

# Fit a model without covariates of occurrence or detection.
fit.simplest = occModel(detectionMats=detections)


# Fit a model which assumes that probability of occurrence in samples differs with site,
# but the differences are not a function of site-level covariates.

data(gobySurveyData)
fit = occModel(~1, ~factor(site)-1, ~1,
          detectionMats=detections,
          siteData=gobySurveyData,
          siteColName="site")


# Fit a model assuming occurrence and detection probabilities
# are functions of site-level covariates.

data(gobySurveyData)
gobySurveyData = scaleData(gobySurveyData)  # center and scale numeric covariates
fit1 = occModel(formulaSite          = ~ veg,
                formulaSiteAndSample = ~ sal + twg,
                formulaReplicate     = ~ sal + fish,
                detectionMats        = detections,
                siteData             = gobySurveyData,
                niter                = 110,
                niterInterval        = 10,
                siteColName = 'site',
                )


# Update the Markov chain of the model specified in fit1
fit2 = updateOccModel(fit1, niter=50, niterInterval=10)

RobertDorazio/eDNAoccupancy documentation built on Sept. 5, 2023, 9:57 a.m.