mrds: predict.ds – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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 class 'ds'
predict(object, newdata=NULL, compute=FALSE, int.range=NULL, esw=FALSE, se.fit=FALSE, ...)
       ## S3 method for class 'io.fi'
predict(object, newdata=NULL, compute=FALSE, int.range=NULL, integrate=FALSE, ...)
       ## S3 method for class 'io'
predict(object, newdata=NULL, compute=FALSE, int.range=NULL, ...)
       ## S3 method for class 'trial'
predict(object, newdata=NULL, compute=FALSE, int.range=NULL, ...)
       ## S3 method for class 'trial.fi'
predict(object, newdata=NULL, compute=FALSE, int.range=NULL, integrate=FALSE, ...)
       ## S3 method for class 'rem'
predict(object, newdata=NULL, compute=FALSE, int.range=NULL, ...)
       ## S3 method for class 'rem.fi'
predict(object, newdata=NULL, compute=FALSE, int.range=NULL, integrate=FALSE, ...)

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)π(y) where π(y)=1/w for lines and π(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.

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.

Note that the ordering of the returned results when no new data is supplied (the "fitted" values) will not necessarily be the same as the data supplied to ddf, the data (and hence results from predict) will be sorted by object ID (object) then observer ID (observer).

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

Note

Each function is called by the generic function predict for the appropriate ddf model object. They can be called directly by the user, but it is typically safest to use predict which calls the appropriate function based on the type of model.

Author(s)

Jeff Laake, David L Miller