dE.multi: Estimate multiple-observer line-transect distance functions
In Rdistance: Density and Abundance from Distance-Sampling Surveys

dE.multi

R Documentation

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: 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. The number of constant parameters in the distance function. Constant parameters are those not related to covariates. For example, the expornent 'k' parameter for hazard rate likelihood, or the mixing fraction 'p' for the oneStep likelihood. This can be zero. 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 (by 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 from `w.lo` and `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 used during the fit.
`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 the distance function g(x) = `g.x.scl`.
`g.x.scl`	The height of the distance function at a distance of `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 boostrap 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.