Rdistance (version 1.3.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 sighting angle and sighting distance.

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. When computing bootstrap confidence intervals, setting warn = FALSE turns off annoying warnings when an iteration does not converge. Regardless of warn, messages about convergence and boundary conditions are printed by print.dfunc, print.abund, and plot.dfunc, so there should be little harm in setting warn = FALSE.

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 details on "Gamma". And see package vignettes for information on custom, user-defined likelihoods. See also F.abund.estim, F.automated.CDA

Examples

# NOT RUN {
# Load the example dataset of sparrow detections from package
data(sparrow.detections)

# Fit multiple detection functions to perpendicular, off-transect distances
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)
# }