predict.ds: Predictions from `mrds` models

Description

Predict detection probabilities (or effective strip widths/effective areas of detection) from a fitted distance sampling model using either the original data (i.e. "fitted" values) or using new data.

Usage

# S3 method for ds
predict(object, newdata=NULL, compute=FALSE,
int.range=NULL, esw=FALSE, se.fit=FALSE, ...)
       # S3 method for io.fi
predict(object, newdata=NULL, compute=FALSE,
       int.range=NULL, integrate=FALSE, ...)
       # S3 method for io
predict(object, newdata=NULL, compute=FALSE,
       int.range=NULL, ...)
       # S3 method for trial
predict(object, newdata=NULL, compute=FALSE,
       int.range=NULL, ...)
       # S3 method for trial.fi
predict(object, newdata=NULL, compute=FALSE,
       int.range=NULL, integrate=FALSE, ...)
       # S3 method for rem
predict(object, newdata=NULL, compute=FALSE,
       int.range=NULL, ...)
       # S3 method for rem.fi
predict(object, newdata=NULL, compute=FALSE,
       int.range=NULL, integrate=FALSE, ...)

Value

For all but the exceptions below, the value is a list with a single element: fitted, a vector of average detection probabilities or esw values for each observation in the original data ornewdata

For predict.ds, if se.fit=TRUE there is an additional element $se.fit, which contains the standard errors of the probabilities of detection or ESW.

For predict.io.fi,predict.trial.fi,predict.rem.fi with integrate=TRUE, the value is a list with one element: fitted, which is a vector of integrated (average) detection probabilities for each observation in the original data or newdata.

For predict.io.fi, predict.trial.fi, or predict.rem.fi

with integrate=FALSE, the value is a list with the following elements:

fitted: $p(y)$ values
p1: $p_{1|2}(y)$, conditional detection probability for observer 1
p2: $p_{2|1}(y)$, conditional detection probability for observer 2
fitted: $p_.(y) = p_{1|2}(y) + p_{2|1}(y) - p_{1|2}(y) * p_{2|1}(y)$, conditional detection probability of being seen by either observer

Arguments

object: ddf model object.
newdata: new data.frame for prediction, this must include a column called "distance".
compute: if TRUE compute values and don't use the fitted values stored in the model object.
int.range: integration range for variable range analysis; either vector or 2 column matrix.
esw: if TRUE, returns effective strip half-width (or effective area of detection for point transect models) integral from 0 to the truncation distance (width) of $p(y)dy$; otherwise it returns the integral from 0 to truncation width of $p(y)\pi(y)$ where $\pi(y)=1/w$ for lines and $\pi(y)=2r/w^2$ for points.
se.fit: for *.ds models only, generate standard errors on the predicted probabilities of detection (or ESW if esw=TRUE), stored in the se.fit element
...: for S3 consistency
integrate: for *.fi methods, see Details below.

Author

Jeff Laake, David L Miller

Details

The first 4 arguments are the same in each predict function. The latter 2 are specific to certain functions. For line transects, the effective strip half-width (esw=TRUE) is the integral of the fitted detection function over either 0 to W or the specified int.range. The predicted detection probability is the average probability which is simply the integral divided by the distance range. For point transect models, esw=TRUE calculates the effective area of detection (commonly referred to as "nu", this is the integral of 2/width^2 * rg(r).

Fitted detection probabilities are stored in the model object and these are returned unless compute=TRUE or newdata is specified. compute=TRUE is used to estimate numerical derivatives for use in delta method approximations to the variance.

For method="io.fi" or method="trial.fi" if integrate=FALSE, predict returns the value of the conditional detection probability and if integrate=TRUE, it returns the average conditional detection probability by integrating over x (distance) with respect to a uniform distribution.