Rdistance (version 1.2.2)

F.dfunc.estim: Estimate a detection function from distance-sampling data.

Description

Fit a specific detection function to a set of observed off-transect distances.

Usage

F.dfunc.estim (dist, likelihood = "halfnorm", w.lo = 0, w.hi = max(dist), 
                            expansions = 0, series = "cosine", x.scl = 0, g.x.scl = 1,
                            observer = "both", warn = TRUE)

Arguments

dist

The vector of observed off-transect distances. Alternatively, a data.frame with observed off-transect distances stored in a column named 'dist'. See perp.dists to calculate off-transect distances from

likelihood

String specifying the likelihood to assume. Valid values at present are "uniform", "halfnorm", "hazrate", "negexp", and "Gamma".

w.lo

Lower or left-truncation limit of the distances in dist. This is the minimum possible off-transect distance. Default is 0.

w.hi

Upper or right-truncation limit of the distances in dist. This is the maximum off-transect distance that could be observed. Default is the maximum of dist.

expansions

A scalar specifying the number of terms in series to compute. Depending on the series, this could be 0 through 5. The default of 0 equates to no expansion terms of any type.

series

If expansions > 0, this string specifies the type of expansion to use. Valid values at present are 'simple', 'hermite', and 'cosine'.

x.scl

This parameter is passed to F.g.estim. See F.gx.estim documentation for definition.

g.x.scl

This parameter is passed to F.g.estim. See F.gx.estim documentation for definition.

observer

This parameter is passed to F.g.estim. See F.gx.estim documentation for definition.

warn

A logical scaler specifying whether to issue an R warning if the estimation did not converge or if one or more parameter estimates are at their boundaries. For estimation, warn should generally be left at its default value of TRUE

Value

• An object of class 'dfunc'. Objects of class 'dfunc' are lists containing the following components:
• parameters
  The vector of estimated parameter values. Length of this vector for built-in likelihood is the number of expansion terms plus 1 plus 1 if the likelihood is either 'hazrate' or 'uniform'.
• loglik
  The maximized value of the log likelihood (more specifically, the minimized value of the negative log likelihood).
• convergence
  The convergence code. This code is returned by nlminb. Values other than 0 indicate suspect convergence.
• like.form
  The form of the likelihood assumed. This is the value of the argument likelihood.
• w.lo
  Left-truncation value used during the fit.
• w.hi
  Right-truncation value used during the fit.
• dist
  The input vector of observed off-transect distances.
• expansions
  The number of expansion terms used during estimation.
• series
  The type of expansion used during estimation.
• call
  The original call of this function.
• fit
  The fitted object returned by nlminb. See documentation for nlminb.

Details

Given a specified likelihood (e.g., "halfnorm"), maximum likelihood is used to estimate the parameter(s) of that likelihood function that best fit the distance data. When the resulting detection function is plotted (see Examples), bins are plotted behind the detection function for visualization; however, the function is fit to the actual data, not to the bins.

See Also

See uniform.like for details on the "uniform", "halfnorm", "hazrate", and "negexp" likelihoods. See Gamma.like for "Gamma". And see package vignettes for information on custom, user-defined likelihoods. See also F.abund.estim, F.automated.CDA

Examples

# Load the example dataset for sparrow detections from package
data(sparrow.detections)

# Compute perpendicular, off-transect distances from the observer's sight distance and angle
sparrow.detections$dist <- perp.dists(obs.dist=sparrow.detections$sightdist,
                                  obs.angle=sparrow.detections$sightangle)

# Fit multiple detection functions
un.dfunc <- F.dfunc.estim(sparrow.detections, likelihood="uniform", w.hi = 150)
hn.dfunc <- F.dfunc.estim(sparrow.detections, likelihood="halfnorm", w.hi = 150)
ne.dfunc <- F.dfunc.estim(sparrow.detections, likelihood="negexp", w.hi = 150)
hz.dfunc <- F.dfunc.estim(sparrow.detections, likelihood="hazrate", w.hi = 150)
ga.dfunc <- F.dfunc.estim(sparrow.detections, likelihood="Gamma", w.hi = 150, x.scl="max") 

# Plot the first four detection functions
par(mfrow=c(2,2))
plot(un.dfunc)
plot(hn.dfunc)
plot(ne.dfunc)
plot(hz.dfunc)