parseModel: Parse Rdistance model

In Rdistance: Density and Abundance from Distance-Sampling Surveys

Parse Rdistance model

Description

Parse an 'Rdistance' formula and produce a list containing all model parameters. This routine is not normally called directly by the user, but it might be helpful in simulations. It is called internally from the model estimation routines.

Usage

parseModel(
  data,
  formula = NULL,
  likelihood = "halfnorm",
  w.lo = 0,
  w.hi = NULL,
  expansions = 0,
  series = "cosine",
  x.scl = 0,
  g.x.scl = 1,
  outputUnits = NULL,
  asymptoticSE = TRUE
)

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.
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.
asymptoticSE	Logical variable for whether to calculate asymptotic standard errors. The default (TRUE) estimates an asymptotic variance-covariance matrix for parameters based on the likelihood's Hessian (2nd derivative). If maximization has been performed by Nlminb or HookesJeeves, the asymptotic Hessian is estimated using numeric second deriviatives of the likelihood at the maximum likelihood solution. If maximization was performed by Optim, the last Hessian of the maximization is returned by Optim and used (see varcovarEstim and secondDeriv). Asymptotic standard errors will not be estimated if asymptoticSE = FALSE. If not estimated, bootstrap iterations will run faster because the numeric Hessian, which is discarded during bootstrapping, will not be calculated every iteration.

Value

An Rdistance model frame, which is an object of class "dfunc". Rdistance model frames are lists containing distance model components but not estimates. Model frames contain everything necessary to fit an Rdistance mode, such as covariates, minimum and maximum distances, the form of the likelihood, number of expansions, etc. Rdistance model frames contain a subset of fitted Rdistance model components.

See Also

RdistDf, which returns an Rdistance data frame; dfuncEstim, which returns an Rdistance fitted model.

Examples

data(sparrowDf)
   
ml <- Rdistance::parseModel(sparrowDf
   , formula = dist ~ 1 + observer + groupsize(groupsize)
   , likelihood = "halfnorm"
   , w.lo = 0
   , w.hi = NULL
   , series = "cosine"
   , x.scl = 0
   , g.x.scl = 1
   , outputUnits = "m"
   )
class(ml)  # 'dfunc', but no estimated coefficients
print(ml)
print.default(ml)

Rdistance documentation built on Jan. 10, 2026, 1:07 a.m.