dE.multi: Estimate multiple-observer line-transect distance functions

In Rdistance: Density and Abundance from Distance-Sampling Surveys

Estimate multiple-observer line-transect distance functions

Description

Fits a detection function to off-transect distances collected by multiple observers.

Usage

dE.multi(
  data,
  formula,
  likelihood = "halfnorm",
  w.lo = setUnits(0, "m"),
  w.hi = NULL,
  expansions = 0,
  series = "cosine",
  x.scl = setUnits(0, "m"),
  g.x.scl = 1,
  warn = TRUE,
  outputUnits = NULL
)

Arguments

data	An RdistDf data frame. RdistDf data frames contain one line per transect and a list-based column. The list-based column contains a data frame with detection information. The detection information data frame on each row contains (at least) distances and group sizes of all targets detected on the transect. Function RdistDf() creates RdistDf data frames from separate transect and detection data frames. is.RdistDf() checks whether data frames are RdistDf's.
formula	A standard formula object. For example, dist ~ 1, dist ~ covar1 + covar2). The left-hand side (before ~) is the name of the vector containing off-transect or radial detection distances. The right-hand side contains the names of covariate vectors to fit in the detection function, and potentially group sizes. Group sizes are specified by including ⁠+ groupsize(<variable>)⁠ in the RHS (see 'Group Sizes' section). Covariates can be either detection level or transect level and can appear in data or exist in the global working environment. Regular R scoping rules apply.
likelihood	String specifying the likelihood to fit. Built-in likelihoods at present are "halfnorm", "hazrate", and "negexp".
w.lo	Lower or left-truncation limit of the distances in distance data. This is the minimum possible off-transect distance. Default is 0. If w.lo is greater than 0, it must have measurement units. See help(unitHelpers) for assistance assigning units.
w.hi	Upper or right-truncation limit of the distances in dist. This is the maximum off-transect distance that could be observed. If unspecified (i.e., NULL), right-truncation is set to the maximum of the observed distances. If w.hi is specified, it must have measurement units. See help(unitHelpers) for assistance assigning units.
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. No expansion terms are allowed (i.e., expansions is forced to 0) if covariates are present in the detection function (i.e., right-hand side of formula includes something other than 1).
series	If expansions > 0, this string specifies the type of expansion to use. Valid values at present are 'simple', 'hermite', and 'cosine'.
x.scl	The x coordinate (a distance) at which the detection function will be scaled. g.x.scl can be a distance or the string "max". When x.scl is specified (i.e., not 0 or "max"), it must have measurement units assigned. See help(unitHelpers) for assistance assigning units.
g.x.scl	Height of the distance function at coordinate x. The distance function will be scaled so that g(x.scl) = g.x.scl. If g.x.scl is not a data frame, it must be a numeric value (vector of length 1) between 0 and 1.
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, 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, after completion all messages about convergence and boundary conditions are printed by print.dfunc, print.abund, and plot.dfunc.
outputUnits	A string specifying the symbolic measurement units for results. Valid units are listed in units::valid_udunits(). The strings for common distance symbolic units are: "m" - meters, "ft" - feet, "cm" - centimeters, "mm" - millimeters, "mi" - miles, "nmile" - nautical miles ("nm" is nano meters), "in" - inches, "yd" - yards, "km" - kilometers, "fathom" - fathoms, "chains" - chains, and "furlong" - furlongs. If outputUnits is unspecified (NULL), output units will be the same as those on distances in data.

Value

An object of class 'dfunc' with the following components:

• par: The vector of estimated parameter values. Length of this vector is the sum of the following:

  1. The number of columns of the design matrix. This equals the number of covariates in the distance function plus one for the intercept, assuming an intercept is included.

  2. The number of constant parameters in the distance function. Constant parameters are those not related to covariates. For example, the exponent 'k' parameter for hazard rate likelihood, or the mixing fraction 'p' for the oneStep likelihood. This can be zero.

  3. The number of expansion functions called for. This equals the input expansions.

• loglik: The maximized value of the log likelihood.

• convergence: The convergence code. This code is returned by the optimizing routine (e.g., optim or nlminb). Values other than 0 indicate suspect convergence.

• message: If maximization did not converge (convergence != 0), this is the reason given by the optimizing routine.

• varcovar: The variance-covariance matrix for coefficients of the distance function, either estimated by the inverse of the fit's Hessian or by bootstrapping. If the likelihood is smooth (i.e., those listed by ⁠Rdistance:::differentiableLikelihoods())⁠, Rdistance initially estimates the variance-covariance matrix using the second derivative of the log likelihood surface at the final estimates, where second derivatives are estimated by numeric differentiation (in routine secondDeriv(). The variance-covariance matrix is re-set to NULL if the Hessian is not positive-definite. If bootstrap resampling has been performed (using abundEstim()), the variance-covariance matrix is re-estimated using the bootstrap values of parameters and automatically reset. Error estimates derived from bootstrapping are generally preferable to the asymptotic estimates, hence the automatic re-set.

• limits: A list containing the lower and upper limits of parameters.

• evaluations: The number of likelihood evaluations performed by the optimizer.

• mf: An R 'model frame' containing the detections (within the strip or circle) used in the fit, covariates specified in the formula, and groupsizes. Column 'dist' contains the observed distances. The intercept, if included in the model, is not included as a column in this model frame. (Test whether an intercept is included using attr(terms(return$mf), "intercept")). Column offset(...) contains group sizes associated with the values of dist. Name of the group size column is "offset(...)", not "groupsize(...)", so that group sizes can be treated offsets in other R routines. The mf component is a proper model.frame and contains both terms and contrasts attributes. This model frame contains only non-missing distances between w.lo and w.hi.

• data: The original nested data frame subset to information required to complete distance estimation. This data frame contains information on replication (i.e., rows are sites and are re-sampled during bootstrapping), missing distances, missing transect lengths, and distances outside the observation strip (below w.lo or above w.hi).

• formula: The distance function's formula.

• dataName: Name of the original nested data frame.

• likelihood: The name of the likelihood fitted to observation distances.

• w.lo: Left-truncation value used during the fit.

• w.hi: Right-truncation value used during the fit.

• expansions: The number of expansion terms.

• series: The type of expansion used during estimation. This is only relevant if expansions > 0.

• x.scl: The distance at which the function has been scaled to some value. This is the x at which g(x) = g.x.scl.

• g.x.scl: The height of the distance function at distance x.scl.

• outputUnits: A list of type symbolic_units containing the physical measurement units used during estimation.

• asymptoticSE: A logical scalar indication whether the variance-covariance matrix in component varcovar is asymptotic (TRUE; estimated from the Hessian) or bootstrap (FALSE; estimated by bootstrap resampling).

• optimizer: The optimizing routine used.

• call: The original function call.

• nCovars: The number of exogenous covariates fitted in the distance function. Does not include the intercept.

• LhoodType: The type of likelihood fitted. Currently, only 'parametric' types are fitted.

Rdistance documentation built on May 14, 2026, 5:09 p.m.