Description Usage Arguments Value Input data frames Likelihood functions Author(s) References See Also Examples
Fit a specific detection function offtransect or offpoint (radial) distances.
1 2 3 4 5  dfuncEstim(formula, detectionData, siteData, likelihood = "halfnorm",
pointSurvey = FALSE, w.lo = 0, w.hi = NULL, expansions = 0,
series = "cosine", x.scl = 0, g.x.scl = 1, observer = "both",
warn = TRUE, transectID = NULL, pointID = "point",
length = "length", control = RdistanceControls())

formula 
A standard formula object (e.g., 
detectionData 
A data frame containing detection distances (either perpendicular for linetransect or radial for pointtransect designs), with one row per detected object or group. This data frame must contain at least the following information:
Optionally, this data frame can contain the following variables:
See example data set 
siteData 
A data.frame containing site (transect or point)
IDs and any
site level covariates to include in the detection function.
Every unique surveyed site (transect or point) is represented on
one row of this data set, whether or not targets were sighted
at the site. See arguments If sites are transects,
this data frame must also contain transect length. By
default, transect length is assumed to be in column 'length'
but can be specified using argument The total number of sites surveyed is See Input data frames
for when 
likelihood 
String specifying the likelihood to fit. Builtin likelihoods at present are "uniform", "halfnorm", "hazrate", "negexp", and "Gamma". See vignette for a way to use userdefine likelihoods. 
pointSurvey 
A logical scalar specifying whether input data come from pointtransect surveys (TRUE), or linetransect surveys (FALSE). 
w.lo 
Lower or lefttruncation limit of the distances in distance data. This is the minimum possible offtransect distance. Default is 0. 
w.hi 
Upper or righttruncation limit of the distances
in 
expansions 
A scalar specifying the number of terms
in 
series 
If 
x.scl 
This parameter is passed to 
g.x.scl 
This parameter is passed to 
observer 
This parameter is passed to 
warn 
A logical scalar 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, 
transectID 
A character vector naming the transect ID column(s) in

pointID 
When pointtransects are used, this is the
ID of points on a transect. When If single points are surveyed,
meaning surveyed points were not grouped into transects, each 'transect' consists
of one point. In this case, set 
length 
Character string specifying the (single) column in

control 
A list containing optimization control parameters such
as the maximum number of iterations, tolerance, the optimizer to use,
etc. See the

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 builtin likelihoods is one (for the function's parameter) plus the number of expansion terms plus one if the likelihood is either 'hazrate' or 'uniform' (hazrate and uniform have two parameters). 
varcovar 
The variancecovariance matrix for coefficients of the distance function, estimated by the inverse of the Hessian of the fit evaluated at the estimates. There is no guarantee this matrix is positivedefinite and should be viewed with caution. Error estimates derived from bootstrapping are generally more reliable. 
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 
like.form 
The name of the likelihood. This is
the value of the argument 
w.lo 
Lefttruncation value used during the fit. 
w.hi 
Righttruncation value used during the fit. 
dist 
The input vector of observed distances. 
covars 
A 
expansions 
The number of expansion terms used during estimation. 
series 
The type of expansion used during estimation. 
call 
The original call of this function. 
call.x.scl 
The distance at which the distance function
is scaled. This is the x at which g(x) = 
call.g.x.scl 
The value of the distance function at distance

call.observer 
The value of input parameter 
fit 
The fitted object returned by 
factor.names 
The names of any factors in 
pointSurvey 
The input value of 
formula 
The formula specified for the detection function. 
To save space and to easily specify
sites without detections,
all site ID's, regardless of whether a detection occurred there,
and site level covariates are stored in
the siteData
data frame. Detection distances and group
sizes are measured at the detection level and
are stored in the
detectionData
data frame.
The following explains conditions under which various combinations of the input data frames are required.
Detection data and site data both required:
Both detectionData
and siteData
are required if site level covariates are
specified on the righthand side of formula
.
Detection level covariates are not currently allowed.
Detection data only required:
The detectionData
data frame alone can be
specified if no covariates
are included in the distance function (i.e., righthand side of
formula
is "~1"). Note that this routine (dfuncEstim
)
does not need to know about sites where zero targets were detected, hence
siteData
can be missing when no covariates are involved.
Neither detection data nor site data required
Neither detectionData
nor siteData
are required if all variables specified in formula
are within the scope of this routine (e.g., in the global working
environment). Scoping rules here work the same as for other modeling
routines in R such as lm
and glm
. Like other modeling
routines, it is possible to mix and match the location of variables in
the model. Some variables can be in the .GlobalEnv
while others
are in either detectionData
or siteData
.
The input data frames, detectionData
and siteData
,
must be mergeable on unique sites. For linetransects,
site ID's specify transects or routes and are unique values of
the transectID
column in siteData
. In this case,
the following merge must work:
merge(detectionData,siteData,by=transectID)
.
For pointtransects,
site ID's specify individual points are unique values
of the combination paste(transectID,pointID)
.
In this case, the following merge must work:
merge(detectionData,siteData,by=c(transectID, pointID)
.
By default,transectID
and pointID
are NULL and
the merge is done on all common columns.
That is, when transectID
is NULL, this routine assumes unique
transects are specified by unique combinations of the
common variables (i.e., unique values of
intersect(names(detectionData), names(siteData))
).
An error occurs if there are no common column names between
detectionData
and siteData
.
Duplicate site IDs are not allowed in siteData
.
If the same site is surveyed in
multiple years, specify another transect ID column (e.g., transectID =
c("year","transectID")
). Duplicate site ID's are allowed in
detectionData
.
To help envision the relationship between data frames, bear in
mind that during bootstrap estimation of variance
in abundEstim
,
unique transects (i.e., unique values of
the transect ID column(s)), not detections or
points, are resampled with replacement.
Given a specified sighting function (e.g., "halfnorm"), maximum likelihood is used to estimate the parameter(s) of the function (e.g., standard error) that best fit the distance data.
When plotted (see Examples), histogram bins are plotted behind the detection function for visualization; however, the function is fit to the actual data, not to the bins.
Trent McDonald, WEST Inc., tmcdonald@westinc.com
Jason Carlisle, University of Wyoming and WEST Inc., jcarlisle@westinc.com
Aidan McDonald, WEST Inc., aidan@mcdcentral.org
Buckland, S.T., D.R. Anderson, K.P. Burnham, J.L. Laake, D.L. Borchers, and L. Thomas. (2001) Introduction to distance sampling: estimating abundance of biological populations. Oxford University Press, Oxford, UK.
abundEstim
, autoDistSamp
.
See likelihoodspecific help files (e.g., halfnorm.like
) for
details on each builtin likelihood. See package vignettes for information on custom,
userdefined likelihoods.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33  # Load example sparrow data (line transect survey type)
data(sparrowDetectionData)
data(sparrowSiteData)
# Fit halfnormal detection function
dfunc < dfuncEstim(formula=dist~1,
detectionData=sparrowDetectionData,
likelihood="halfnorm", w.hi=100)
# Fit a second halfnormal detection function, now including
# a categorical covariate for observer who surveyed the site (factor, 5 levels)
# Increase maximum iterations
dfuncObs < dfuncEstim(formula=dist~observer,
detectionData=sparrowDetectionData,
siteData=sparrowSiteData,
likelihood="halfnorm", w.hi=100, pointSurvey=FALSE,
control=RdistanceControls(maxIter=1000))
# Print results
# And plot the detection function for each observer
dfuncObs
plot(dfuncObs,
newdata=data.frame(observer=levels(sparrowSiteData$observer)))
# Show some plotting options
plot(dfuncObs,
newdata=data.frame(observer=levels(sparrowSiteData$observer)),
vertLines = FALSE, lty=c(1,1),
col.dfunc=heat.colors(length(levels(sparrowSiteData$observer))),
col=c("grey","lightgrey"), border=NA,
xlab="Distance (m)",
main="Showing plot options")

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.