Package 'eoa3'

A template for carcass persistence data with interval-censored carcass persistence times

Description

A template for carcass persistence data with interval-censored carcass persistence times

Usage

cpdata0

Format

A matrix with 2 columns bracketing persistence times (in days since carcass placement) of each carcass:

CPmin

the last time the carcass was observed

CPmax

the first time the carcass was noted missing

---

A template for search schedule data

Description

A template for search schedule data

Usage

days0

Format

A numeric vector with the times when searches were conducted, with days[1] = 0:

days0

numeric vector of search times

---

Evidence of Absence

Description

This package is designed to analyze searcher efficiency, carcass persistence, search schedule, and carcass observation data for the estimation of bird and bat mortality at wind and solar power facilities. It is specially designed for analyses when few carcasses are observed and detection probability is low. [It works fine for large counts as well, but some estimators (GenEst in particular) are more well-endowed with a wider array of tools for analysis of large-count data.

Main command-line functions

est_pk0, est_cp0, est_g0

estimate searcher efficiency (pk), carcass persistence (cp), and (g) parameters

postM, postM.ab

estimate posterior distribution of $M$ given estimated $g$ and carcass count (X)

calcMstar, MCI

calculate $M*$ and credible interval for $M$

Potentially useful calculation functions

sim_pk0, sim_cp0

simulate estimated SE and CP parameters

GenEst::ppersist

calculate probability that a carcass that arrives at an (unknown) uniform random time in an interval persists until a later, specified time. This is the generalized $r$ statistic for a given persistence distribution, arrival interval width, and search time.

Behind-the-scenes utility functions

fmmax, fmmax.ab

functions to calculate a suitable maximum value to truncate improper prior distributions of $M$

getab

function to extract MLE of pda and pdb parameters from a persistence distribution

---

Fit cp carcass persistence models

Description

Carcass persistence is modeled as survival function

Usage

est_cp0(cpdata, dist)

Arguments

cpdata	matrix of interval censored carcass persistence times
dist	Name of the persistence distribution family: Weibull, lognormal, loglogistic, or exponential

Details

uses survival package to fit.

Value

answer

---

estimate g from fitted pk and cp models and search schedule

Description

Given a fitted pk model (from est_pk0), a fitted cp model (from est_cp0 or a survreg object), and a search schedule, estimate detection probability.

Usage

est_g0(pkmodel, cpmodel, days, a = NULL, v = NULL, ...)

Arguments

pkmodel	fitted pk model (from est_pk0)
cpmodel	fitted cp model (from est_cp0 or survreg object)
days	vector of days since searches begin (days[1] == 0)
a	fraction of carcasses arriving in the area searched
v	fraction of carcasses arriving in the period spanned by the monitoring
...	additional arguments (ignored)

Value

list of parameters for a beta distributions fit to the vectors of for $\hat{g}$ for the searched area within the period monitored ($BabRaw), for the whole site within the period monitored ($Bab), and for the whole site extrapolated to the whole year ($BabAnn). In addition, the models and parameters that went into the estimate are included as well (pkmodel, cpmodel, a, v).

Examples

pkmodel <- est_pk0(pkdata = pkdata0)
 cpmodel <- est_cp0(cpdata = cpdata0, dist = "weibull")
 ghat <- est_g0(pkmodel = pkmodel, cpmodel = cpmodel, days = days0, a = 0.4, v = 0.75)
 summary(ghat)

---

Fit pk searcher efficiency models

Description

Searcher efficiency is modeled as a function of the number of times a carcass has been missed in previous searches and any number of covariates.

Usage

est_pk0(pkdata, kFixed = NULL, n.iter = 1000, ...)

Arguments

pkdata	Search trial data entered in a list of N-vectors, $n and $y, indicating the number of carcasses available and the number discovered in searcher efficiency field trials in which carcasses were available for discovery. [NOTE: In earlier versions of eoa, the vectors were $M and $X. The names have been changed to avoid confusion with the M and X for total mortality and carcasses discovered carcass survey.]
kFixed	If trial carcassses are available for discovery for one search and data are insufficient for estimating k, a fixed, assumed value must be entered for k.
n.iter	number of iterations to use in updating the JAGS model for $p$ and $k$
...	Other parameters that may be used in called functions (esp. burn for updating the JAGS function)

Details

The probability of finding a carcass that is present at the time of search is p on the first search after carcass arrival and is assumed to decrease by a factor of k each time the carcass is missed in searches.

Value

A list with an nsim x 2 matrix of simulated p and k values the joint posterior for SE.

---

Find suitable mmax for clipping improper priors for M

Description

Improper priors need to be clipped in order to be usable. fmmax and fmmax.ab find values of $m$ that are large enough that the probability of exceeding is less than 0.0001 (depends on $g$ and $X$).

Usage

fmmax(x, g)

fmmax.ab(x, pBa, pBb)

Arguments

x	carcass count
g	overall carcass detection probability
pBa, pBb	parameters for beta distribution characterizing estimated $g$

Value

integer $m$ such that $Pr(M >= m) < 0.0001$

---

retrieve EoA parameterization from survival parameterization of a fitted cp model (or survreg object with exponential, weibull, lognormal, or loglogistic distribution)

Description

retrieve EoA parameterization from survival parameterization of a fitted cp model (or survreg object with exponential, weibull, lognormal, or loglogistic distribution)

Usage

getab(cpmodel)

Arguments

cpmodel

fitted cp model (from est_cp0 or survreg object)

Value

2-vector of pda and pdb

---

Check validity of format of custom prior for M

Description

Check validity of format of custom prior for M

Usage

MpriorOK(prior)

Arguments

prior

a custom prior for M must be a matrix with columns for M and and associated probabalities P(M = m). The M column must begin at 0 and the probabilities must sum to 1.

Value

boolean. Is the prior formatted properly?

---

A template for summarized searcher efficiency data with the number of carcasses available and the number discovered for N = 12 search occasions

Description

A template for summarized searcher efficiency data with the number of carcasses available and the number discovered for N = 12 search occasions

Usage

pkdata0

Format

A list with 2 numeric N-vectors with numbers of:

n

searcher efficiency trial carcasses available

y

carcasses discovered

---

Calculate posterior distribution of M and extract statistics (M* and CI)

Description

Calculation of the posterior distribution of total mortality (M) given the carcass count, overall detection probability (g), and prior distribtion; calculation of summary statistics from the posterior distribution of M, including M* and credibility intervals.

Usage

postM(x, g, prior = "IbinRef", mmax = NA)

postM.ab(x, Ba, Bb, prior = "IbinRef", mmax = NULL)

calcMstar(pMgX, alpha)

MCI(pMgX, crlev = 0.95)

Arguments

x	carcass count
g	overall carcass detection probability
prior	prior distribution of $M$
mmax	cutoff for prior of M (large max requires large computing resources but does not help in the estimation)
Ba, Bb	parameters for beta distribution characterizing estimated $g$
pMgX	posterior distribution of $M$
crlev, alpha	credibility level ($1-\alpha$) and its complement ($\alpha$)

Details

The functions postM and postM.ab return the posterior distributions of $M|(X, g)$ and $M|(X, Ba, Bb)$, respectively, where Ba and Bb are beta distribution parameters for the estimated detection probability. postM and postM.ab include options to to specify a prior distribution for $M$ and a limit for truncating the prior to disregard implausibly large values of $M$ and make the calculations tractable in certain cases where they otherwise might not be. Use postM when $g$ is fixed and known; otherwise, use postM.ab when uncertainty in $g$ is characterized in a beta distribution with parameters $Ba$ and $Bb$. The non-informative, integrated reference prior for binomial random variables is the default (prior = "IbinRef"). Other options include "binRef", "IbetabinRef", and "betabinRef", which are the non-integrated and integrated forms of the binomial and betabinomial reference priors (Berger et al., 2012). For $X > 2$, the integrated and non-integrated reference priors give virtually identical posteriors. However, the non-integrated priors assign infinite weight to $m = 0$ and return a posterior of $Pr(M = 0| X = 0, \hat{g}) = 1$, implying absolute certainty that the total number of fatalities was 0 if no carcasses were observed. In addition, a uniform prior may be specified by prior = "uniform". Alternatively, a custom prior may be given as a 2-dimensional array with columns for $m$ and $Pr(M = m)$, respectively. The first column (m) must be sequential integers starting at $m = 0$. The second column gives the probabilities associated with $m$, which must be non-negative and sum to 1. The named priors ("IbinRef", "binRef", "IbetabinRef", and "betabinRef") are functions of $m$ and defined on $m=0,1,2,...$ without upper bound. However, the posteriors can only be calculated for a finite number of $m$'s up to a maximum of mmax, which is set by default to the smallest value of $m$ such that $Pr(X \leq x | m, \hat{g}) < 0.0001$, where $x$ is the observed carcass count, or, alternatively, mmax may be specified by the user.

Value

The functions postM and postM.ab return the posterior distributions of $M | (X, g)$ and $M | (X, Ba, Bb)$, respectively. The functions calcMstar and MCI return $M^*$ value and credibility interval for the given posterior distribution, pMgX (which may be the return value of postM or postM.ab) and $\alpha$ value or credibility level.

---

generate random cp parameters or persistence times

Description

Given a fitted cp model (survreg object), generate random pda and pdb parameters or random persistence times. NOTE: This function is likely to move to call GenEst's rcp in future. This will not change the results, but the GenEst version is more nicely coded and keeping some coherence among the models is helpful.

Usage

sim_cp0(cpmodel, nsim, option = "parms")

Arguments

cpmodel	Fitted cp model ((survreg object))
nsim	Number of simulation draws
option	option = "parms" returns random draws of parameters from the fitted model; option != "parms" returns random draws of carcass persistence times

Value

answer

---

Simulate pk parameters from model

Description

Simple simulation

Usage

sim_pk0(pkmodel, nsim = 1000)

Arguments

pkmodel	A model returned from est_pk0
nsim	Number of simulation reps for estimating the joint posterior distribution of p and k.

Value

An nsim x 2 matrix of simulated p and k values the joint posterior for SE.

---

Summary statistics for estimated g

Description

Summary statistics for estimated g

Usage

## S3 method for class 'estg'
summary(object, crlev = 0.95, ...)

Arguments

object	An estg object
crlev	Credibility level of estimated CI to be returned
...	additional (optional) arguments passed to rjags::coda.samples

Value

summary statistics for estimated g. searched is for the fraction of carcasses falling in the searched area during the monitored period, site is area-adjusted to account for carcasses falling outside the searched area, and full is further extrapolated to the full year.

---

Summary statistics for estimated p and p parameters

Description

Summary statistics for estimated p and p parameters

Usage

## S3 method for class 'estpk'
summary(object, crlev = 0.95, n.iter = 10000, ...)

Arguments

object	An estpk object
crlev	Credibility level of estimated CI to be returned
n.iter	Number of iterations of the JAGS model for estimating the joint posterior distribution of p and k (relevant only if object$type == "pk").
...	additional (optional) arguments passed to rjags::coda.samples

Value

array of summary statistics for p and k

---