Package 'Rdistance'

Description

Rdistance contains functions and associated routines to analyze distance-sampling data collected on point or line transects. Some of Rdistance's features include:

• Accommodation of both point and line transect analyses in one routine (dfuncEstim).

• Regression-like formula for inclusion of distance function covariates (dfuncEstim).

• Automatic bootstrap confidence intervals (abundEstim).

• Availability of both study-area and site-level abundance estimates (help("predict.dfunc")).

• Classical, parametric distance functions (halfnorm.like, hazrate.like, negexp.like), and expansion functions (cosine.expansion, hermite.expansion, simple.expansion).

• Automated distance function fits and selection autoDistSamp.

• print, plot, predict, coef, and summary methods for distance function objects and abundance classes.

Background

Distance-sampling is a popular method for abundance estimation in ecology. Line transect surveys are conducted by traversing randomly placed transects in a study area with the objective of sighting animals and estimating density or abundance. Data collected during line transect surveys consists of sighting records for targets, usually either individuals or groups of individuals. Among the collected data, off-transect distances are recorded or computed from other information (see perpDists). Off-transect distances are the perpendicular distances from the transect to the location of the initial sighting cue. When groups are the target, the number of individuals in the group is recorded.

Point transect surveys are similar except that observers stop one or more times along the transect to observe targets. This is a popular method for avian surveys where detections are often auditory cues, but is also appropriate when automated detectors are placed along a route. Point transect surveys collect distances from the observer to the target and are sometimes called radial distances.

A fundamental characteristic of both line and point-based distance sampling analyses is that probability of detecting a target declines as off-transect or radial distances increase. Targets far from the observer are usually harder to detect than closer targets. In most classical line transect studies, targets on the transect (off-transect distance = 0) are assume to be sighted with 100% probability. This assumption allows estimation of the proportion of targets missed during the survey, and thus it is possible to adjust the actual number of sighted targets for the proportion of targets missed. Some studies utilize two observers searching the same areas to estimate the proportion of individuals missed and thereby eliminating the assumption that all individuals on the line have been observed.

Relationship to other software

A detailed comparison of Rdistance to other options for distance sampling analysis (e.g., Program DISTANCE, R package Distance, and R package unmarked) is forthcoming. While some of the functionality in Rdistance is not unique, our aim is to provide an easy-to-use, rigorous, and flexible analysis option for distance-sampling data. We understand that beginning users often need software that is both easy to use and easy to understand, and that advanced users often require greater flexibility and customization. Our aim is to meet the demands of both user groups. Rdistance is under active development, so please contact us with issues, feature requests, etc. through the package's GitHub website (https://github.com/tmcd82070/Rdistance).

Data sets

Rdistance contains four example data sets: two collected using line-transect methods (i.e., sparrowDetectionData and sparrowSiteData) and two collected using point-transect methods (i.e., thrasherDetectionData and thrasherSiteData).

Author(s)

Main author and maintainer: Trent McDonald <[email protected]>

Coauthors: Ryan Nielson, Jason Carlisle, and Aidan McDonald

Contributors: Ben Augustine, James Griswald, Joel Reynolds, Pham Quang, Earl Becker, Aaron Christ, Brook Russelland, Patrick McKann, Lacey Jeroue, Abigail Hoffman, Michael Kleinsasser, and Ried Olson

References

Buckland, S.T., Anderson, D.R., Burnham, K.P. and Laake, J.L. 1993. Distance Sampling: Estimating Abundance of Biological Populations. Chapman and Hall, London.

See Also

Useful links:

• https://github.com/tmcd82070/Rdistance/wiki

• Report bugs at https://github.com/tmcd82070/Rdistance/issues

Description

Estimate abundance (or density) from an estimated detection function and supplemental information on observed group sizes, transect lengths, area surveyed, etc. Computes confidence intervals on abundance (or density) using a the bias corrected bootstrap method.

Usage

abundEstim(
  object,
  area = NULL,
  propUnitSurveyed = 1,
  ci = 0.95,
  R = 500,
  plot.bs = FALSE,
  showProgress = TRUE
)

Arguments

Details

The abundance estimate for line-transect surveys (if no covariates are included in the detection function and both sides of the transect are observed) is

$N =\frac{n(A)}{2(ESW)(L)}$

where n is total number of sighted individuals (i.e., sum(groupSizes(dfunc))), L is the total length of surveyed transect (i.e., sum(effort(dfunc))), and ESW is effective strip width computed from the estimated distance function (i.e., ESW(dfunc)). If only one side of transects were observed, the "2" in the denominator is not present (or, replaced with a "1").

The abundance estimate for point transect surveys (if no covariates are included) is

$N =\frac{n(A)}{\pi(ESR^2)(P)}$

where n is total number of sighted individuals (i.e., sum(groupSizes(dfunc))), P is the total number of surveyed points (i.e., sum(effort(dfunc))), and ESR is effective search radius computed from the estimated distance function (i.e., ESR(dfunc)).

Setting plot.bs=FALSE and showProgress=FALSE suppresses all intermediate output.

Estimation of site-specific density (e.g., on every transect) is accomplished by predict(x, type = "density"), which returns a tibble containing density and abundance on the area surveyed by every transect.

Value

An Rdistance 'abundance estimate' object, which is a list of class c("abund", "dfunc"), containing all the components of a "dfunc" object (see dfuncEstim), plus the following:

Bootstrap Confidence Intervals

Rdistance's nested data frames (produced by RdistDf) contain all information required to estimate bootstrap CIs. To compute bootstrap CIs, Rdistance resamples, with replacement, the rows of the $data component contained in Rdistance fitted models. Rdistance assumes each row of $data contains one information on on transect. The $data component also contains information on which observations go into the detection functions, which should be counted as detected targets, and which count toward transect length. After resampling rows of $data, Rdistance refits the distance function using non-missing distances, recomputes the detected number of targets using non-missing group sizes on transects with non-missing length, and re-computes total transect length from transects with non-missing lengths. By default, R = 500 bootstrap iterations are performed, after which bias corrected confidence intervals are computed (Manly, 1997, section 3.4).

The distance function is not re-selected during bootstrap resampling. The model of the input object is re-fitted every iteration.

During bootstrap iterations, the distance function can fail. An iteration can fail for a two reasons: (1) no detections on the iteration, and (2) a bad configuration of distances that push the distance function's parameters to their limits. When an iteration fails, Rdistance skips the iteration and effectively ignores the failed iterations. If the proportion of failed iterations is small (less than 20 is probably valid and no warning is issued. If the proportion of non-convergent iterations is not small (exceeds 20 The warning can be modified by re-setting the Rdistance_maxBSFailPropForWarning option. Setting options(Rdistance_masBSFailPropForWarning = 1.0) will turn off the warning. Setting options(Rdistance_masBSFailPropForWarning = 0.0) will warn if any iteration failed. Results (density and effective sampling distance) from all successful iterations are contained in the non-NA rows of data frame 'B' in the output object.

Missing Transect Lengths

Transect lengths can be missing in the RdistDf object. Missing length transects are equivalent to 0 [m] transects and do not count toward total surveyed units nor to group sizes on these transects count toward total detected individuals. Use NA-length transects to include their associated distances when estimating the distance function, but not when estimating abundance. For example, this allows estimation of abundance on one study area using off-transect distances from another. This allows sightability to be estimated using two or more similar targets (e.g., two similar species), but abundance to be estimated separate for each target type. Include NA-length transects by including the "extra" distance observations in the detection data frame, with valid site IDs, but set the length of those site IDs to NA in the site data frame.

Point Transect Lengths

Point transects do not have a physical measurement for length. The "length" of point transects is the number of points on the transect. Point transects can contain only one point. Rdistance treats transects of points as independent and bootstrap resamples them to estimate variance. The number of points on each point transect must exist in the RdistDf and cannot have physical measurement units (it is a count, not a distance).

References

Manly, B.F.J. (1997) Randomization, bootstrap, and Monte-Carlo methods in biology, London: Chapman and Hall.

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.

See Also

dfuncEstim, autoDistSamp, predict.dfunc with 'type = "density"'.

Examples

# Load example sparrow data (line transect survey type)
# sparrowDf <- RdistDf(sparrowSiteData, sparrowDetectionData)
data(sparrowDf)

# Fit half-normal detection function
dfunc <- sparrowDf |> 
  dfuncEstim(formula=dist ~ groupsize(groupsize)
           , likelihood="halfnorm"
           , w.hi=units::set_units(150, "m")
  )

# Estimate abundance - Convenient for programming 
abundDf <- estimateN(dfunc
                   , area = units::set_units(4105, "km^2")
           )

# Same - Nicer output 
# Set ci=0.95 (or another value) to estimate bootstrap CI's on ESW, density, and abundance.
fit <- abundEstim(dfunc
                , area = units::set_units(4105, "km^2")
                , ci = NULL
                )

Description

Computes AICc, AIC, or BIC for estimated distance functions.

Usage

## S3 method for class 'dfunc'
AIC(object, ..., criterion = "AICc")

Arguments

Details

Regular Akaike's information criterion (https://en.wikipedia.org/wiki/Akaike_information_criterion) ($AIC$) is

$AIC = LL + 2p,$

where $LL$ is the maximized value of the log likelihood (the minimized value of the negative log likelihood) and $p$ is the number of coefficients estimated in the detection function. For dfunc objects, $AIC$ = obj$loglik + 2*length(coef(obj)).

A correction for small sample size, $AIC_c$, is

$AIC_c = LL + 2p + \frac{2p(p+1)}{n-p-1},$

where $n$ is sample size or number of detected groups for distance analyses. By default, this function computes $AIC_c$. $AIC_c$ converges quickly to $AIC$ as $n$ increases.

The Bayesian Information Criterion (BIC) is

$BIC = LL + log(n)p,$

.

Value

A scalar, the requested fit statistic for object.

References

Burnham, K. P., and D. R. Anderson, 2002. Model selection and multi-model inference: A practical information-theoretic approach, Second ed. Springer-Verlag. ISBN 0-387-95364-7.

McQuarrie, A. D. R., and Tsai, C.-L., 1998. Regression and time series model selection. World Scientific. ISBN 981023242X

See Also

coef, dfuncEstim

Examples

data(sparrowDf)
dfunc <- sparrowDf |> dfuncEstim(dist~1)
  
# Fit statistics
AIC(dfunc)  # AICc
AIC(dfunc, criterion="AIC")  # AIC
AIC(dfunc, criterion="BIC")  # BIC

Description

Perform automated likelihood, expansion, and series selection for a classic distance sampling analysis. Estimate abundance using the best fitting likelihood, expansion, and series.

Usage

autoDistSamp(
  data,
  formula,
  likelihoods = c("halfnorm", "hazrate", "negexp"),
  w.lo = units::set_units(0, "m"),
  w.hi = NULL,
  expansions = 0:3,
  series = c("cosine"),
  x.scl = w.lo,
  g.x.scl = 1,
  warn = TRUE,
  outputUnits = NULL,
  area = NULL,
  propUnitSurveyed = 1,
  ci = 0.95,
  R = 500,
  plot.bs = FALSE,
  showProgress = TRUE,
  plot = TRUE,
  criterion = "AICc"
)

Arguments

Details

During distance function selection, all combinations of likelihoods, series, and number of expansions is fitted. For example, if likelihoods has 3 elements, series has 2 elements, and expansions has 4 elements, this routine fits a total of 3 (likelihoods) * 2 (series) * 4 (expansions) = 24 models. Default parameters fit 9 detection functions, i.e., all combinations of "halfnorm", "hazrate", and "negexp" likelihoods and 0 through 3 expansions. Other combinations are specified through values of likelihoods, series, and expansions.

Suppress all intermediate output using plot.bs=FALSE, showProgress=FALSE, and plot=FALSE.

The returned abundance estimate object contains an additional component, the fitting table (a list of models fitted and criterion values) in component $fitTable.

Value

An Rdistance 'abundance estimate' object, which is a list of class c("abund", "dfunc"), containing all the components of a "dfunc" object (see dfuncEstim), plus the following:

See Also

dfuncEstim, abundEstim.

Examples

# Load example sparrow data (line transect survey type)
data(sparrowDf)

autoDistSamp(data = sparrowDf
           , formula = dist ~ groupsize(groupsize)
           , likelihoods = c("halfnorm","negexp")
           , expansions = 0
           , plot = FALSE
           , ci = NULL
           , area = units::set_units(1, "hectare")
)

## Not run: 
autoDistSamp(data = sparrowDf
    , formula = dist ~ 1 + groupsize(groupsize)
    , ci = 0.95
    , area = units::set_units(1, "hectare")
)     

## End(Not run)

Description

Calculate bias-corrected confidence intervals for bootstrap data using methods in Manly textbook.

Usage

bcCI(x.bs, x, ci = 0.95)

Arguments

Value

A named vector containing the lower and upper endpoints of the bias-corrected bootstrap confidence interval.

Description

Check that number of integration intervals is odd and sufficiently large.

Usage

checkNEvalPts(nEvalPts)

Arguments

Value

The first element of nEvalPts is returned if it is acceptable. If nEvalPts is not acceptable, an error is thrown.

Description

Check for the presence of physical measurement units on key columns of an RdistDf data frame.

Usage

checkUnits(ml)

Arguments

Value

The input ml list, with units of various quantities converted to common units. If a check fails, for example, a quantity does not have units, an error is thrown.

Description

Extract distance model coefficients from an estimated detection function object.

Usage

## S3 method for class 'dfunc'
coef(object, ...)

Arguments

Value

The estimated coefficient vector for the detection function. Length and interpretation of values vary depending on the form of the detection function and expansion terms.

See Also

AIC, dfuncEstim

Examples

data(sparrowDfuncObserver) # pre-estimated dfunc

# Same as sparrowDfuncObserver$par 
coef(sparrowDfuncObserver) 

## Not run: 
data(sparrowDf)
dfunc <- sparrowDf |> dfuncEstim(dist~bare + observer,
                      w.hi=units::set_units(150, "m"))
coef(dfunc)

## End(Not run)

Description

Add ANSI color to a string using the crayon package, if the R environment accepts color. This function is needed because of the need to determine whether output can be colorized. This determination is left up to crayon::has_color().

In addition, for Rdistance results, we want to only colorize numbers, not the reporting units. Everything between the last set of square brackets ([...]) is NOT colorized.

Usage

colorize(STR, col = NULL, bg = NULL)

Arguments

Value

If color is not allowed in the terminal, the input string is returned unperturbed. If color is allowed, the input string is returned with color and background ANSI code surrounding the initial part of the string from character 1 to the character before the [ in the last pair of [].

See Also

crayon::style

Description

Computes the cosine expansion terms used to modify the shape of distance likelihood functions.

Usage

cosine.expansion(x, expansions)

Arguments

Details

There are, in general, several expansions that can be called cosine. The cosine expansion used here is:

• First term:

  $h_1(x)=\cos(2\pi x),$

• Second term:

  $h_2(x)=\cos(3\pi x),$

• Third term:

  $h_3(x)=\cos(4\pi x),$

• Fourth term:

  $h_4(x)=\cos(5\pi x),$

• Fifth term:

  $h_5(x)=\cos(6\pi x),$

The maximum number of expansion terms computed is 5.

Value

A matrix of size length(x) X expansions. The columns of this matrix are the cosine expansions of x. Column 1 is the first expansion term of x, column 2 is the second expansion term of x, and so on up to expansions.

See Also

dfuncEstim, hermite.expansion, simple.expansion, and the discussion of user defined likelihoods in dfuncEstim.

Examples

x <- seq(0, 1, length = 200)
cos.expn <- cosine.expansion(x, 5)
plot(range(x), range(cos.expn), type="n")
matlines(x, cos.expn, col=rainbow(5), lty = 1)

Description

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

Usage

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

Arguments

Value

An object of class 'dfunc'. Objects of class 'dfunc' are lists containing the following components:

Description

Fits a detection function to off-transect distances collected by a single observer.

Usage

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

Arguments

Details

Optimization and estimation controls can be modified using options(). See RdistanceControls.

Value

An object of class 'dfunc'. Objects of class 'dfunc' are lists containing the following components:

Group Sizes

To specify non-unity group sizes, use groupsize() on the RHS of formula. When group sizes are not all 1, they must appear in a column of the 'detections' list-column of data. For example, d ~ habitat + groupsize(number) specifies distances in column d, one covariate named habitat, and that column number contains the number of individuals associated with each detection. If group sizes are not specified, all group sizes are assumed to be 1.

Contrasts

Factor contrasts in Rdistance are specified the same way as in lm or glm. By default, Rdistance uses contrasts in getOption("contrasts"). To change contrasts, use a statement like options(contrasts = c(unordered = "contr.SAS", ordered = "contr.poly")). Or, to set contrasts for a specific factor in the input data frame, use contrasts(df$A) <- "contr.sum" or similar. See contrasts or the contrasts.arg of model.matrix.

Transect types

Rdistance accommodates two kinds of transects: continuous and point. Detections can occur at any point on continuous transects. Rdistance calls these 'line-transects' even though routes are not necessarily a straight line. On point transects, detections occur at a series of stops (points). Rdisance calls these point-transects. Transects are the basic sampling unit in both cases. Rdistance assumes each row of data contains information from one transect. See RdistDf for more details.

Measurement Units

As of Rdistance version 3.0.0, measurement units are require on all physical distances. Requiring units ensures that internal calculations and results (e.g., ESW and abundance) are correct and that output units are clear. Physical distances are required on off-transect distances, radial distances, truncation distances (w.lo, unless it is zero; and w.hi, unless it is NULL), scale locations (x.scl, unless it is zero), line-transect lengths, and study area size. All units are 1-dimensional except those on study area, which are 2-dimensional.

Physical measurement units can vary. For example, off-transect distances can be meters ("m"), w.hi can be inches ("in"), and w.lo can be kilometers ("km"). Internally, all distances are converted to the units specified by outputUnits (or the units of input distances if outputUnits is NULL), and all output is reported in units of outputUnits. Valid conversions must exist between units or an error is thrown. For example, meters cannot be converted into hectares.

Measurement units can be assigned using units()<- after attaching the units package or with x <- units::set_units(x, "<units>"). See units::valid_udunits() for a list of valid symbolic units.

If measurements are truly unit-less, or measurement units are unknown, set options(Rdist_requireUnits = FALSE). This suppresses all unit checks and conversions. Users are on their own to make sure inputs are scaled correctly and that output units are known.

References

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.

See Also

abundEstim, autoDistSamp. Likelihood-specific help files (e.g., halfnorm.like).

Examples

# Load example sparrow data (line transect survey type)
data(sparrowDf)

dfunc <- dfuncEstim(data = sparrowDf
                  , formula = dist ~ 1)
dfunc
plot(dfunc)

Description

Fits a detection function using maximum likelihood.

Usage

dfuncEstim(data, ...)

Arguments

Details

Optimization and estimation controls can be modified using options(). See RdistanceControls.

Value

An object of class 'dfunc'. Objects of class 'dfunc' are lists containing the following components:

Group Sizes

To specify non-unity group sizes, use groupsize() on the RHS of formula. When group sizes are not all 1, they must appear in a column of the 'detections' list-column of data. For example, d ~ habitat + groupsize(number) specifies distances in column d, one covariate named habitat, and that column number contains the number of individuals associated with each detection. If group sizes are not specified, all group sizes are assumed to be 1.

Contrasts

Factor contrasts in Rdistance are specified the same way as in lm or glm. By default, Rdistance uses contrasts in getOption("contrasts"). To change contrasts, use a statement like options(contrasts = c(unordered = "contr.SAS", ordered = "contr.poly")). Or, to set contrasts for a specific factor in the input data frame, use contrasts(df$A) <- "contr.sum" or similar. See contrasts or the contrasts.arg of model.matrix.

Measurement Units

As of Rdistance version 3.0.0, measurement units are require on all physical distances. Requiring units ensures that internal calculations and results (e.g., ESW and abundance) are correct and that output units are clear. Physical distances are required on off-transect distances, radial distances, truncation distances (w.lo, unless it is zero; and w.hi, unless it is NULL), scale locations (x.scl, unless it is zero), line-transect lengths, and study area size. All units are 1-dimensional except those on study area, which are 2-dimensional.

Physical measurement units can vary. For example, off-transect distances can be meters ("m"), w.hi can be inches ("in"), and w.lo can be kilometers ("km"). Internally, all distances are converted to the units specified by outputUnits (or the units of input distances if outputUnits is NULL), and all output is reported in units of outputUnits. Valid conversions must exist between units or an error is thrown. For example, meters cannot be converted into hectares.

Measurement units can be assigned using units()<- after attaching the units package or with x <- units::set_units(x, "<units>"). See units::valid_udunits() for a list of valid symbolic units.

If measurements are truly unit-less, or measurement units are unknown, set options(Rdist_requireUnits = FALSE). This suppresses all unit checks and conversions. Users are on their own to make sure inputs are scaled correctly and that output units are known.

References

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.

See Also

abundEstim, autoDistSamp. Likelihood-specific help files (e.g., halfnorm.like).

Examples

# Sparrow line transect example
data(sparrowDetectionData)
data(sparrowSiteData)

sparrowDf <- RdistDf(sparrowSiteData, sparrowDetectionData)

dfunc <- dfuncEstim(sparrowDf, 
                    formula = dist ~ 1
                  )
summary(dfunc)

  
data(sparrowDfuncObserver) # pre-estimated object
## Not run:                  
# Command to produce 'sparrowDfuncObserver'
sparrowDfuncObserver <- sparrowDf |> 
         dfuncEstim( 
           formula = dist ~ observer
         )

## End(Not run)     
sparrowDfuncObserver
summary(sparrowDfuncObserver)
plot(sparrowDfuncObserver)

Description

Utility function to produce error messages suitable for stop

Usage

dfuncEstimErrMessage(txt, attri)

Arguments

Value

A string

Description

Extract the observation distances (i.e., responses for an Rdistance model) from an Rdistance model frame.

Usage

distances(ml, na.rm = TRUE, ...)

Arguments

Value

A vector containing observation distances contained in the Rdistance model frame.

Examples

data(sparrowDf)
sparrowModel <- parseModel( sparrowDf, dist ~ observer )
stats::model.response(sparrowModel$mf)
distances(sparrowModel) # same, but future-proof

Description

Computes Effective Detection Radius (EDR) for estimated detection functions on point transects. See ESW is for line transects.

Usage

EDR(object, newdata = NULL)

Arguments

Details

Effective Detection Radius is the integral under the detection function times distance.

Value

If newdata is present, the returned value is a vector of effective sampling distances for values of the covariates in newdata with length equal to the number of rows in newdata. If newdata is NULL, the returned value is a vector of effective sampling distances associated with covariate values in object and has the same number of detected groups. The returned vector has measurement units, i.e., object$outputUnits.

Numeric Integration

Rdistance uses Simpson's composite 1/3 rule to numerically integrate under distance functions. The number of points evaluated during numerical integration is controlled by options(Rdistance_intEvalPts) (default 101). Option 'Rdistance_intEvalPts' must be odd because Simpson's rule requires an even number of intervals (hence, odd number of points). Lower values of 'Rdistance_intEvalPts' increase calculation speeds; but, decrease accuracy. 'Rdistance_intEvalPts' must be >= 5. A warning is thrown if 'Rdistance_intEvalPts' < 29. Empirical tests by the author suggest 'Rdistance_intEvalPts' values >= 30 are accurate to several decimal points and that all 'Rdistance_intEvalPts' >= 101 produce identical results in all but pathological cases.

See Also

dfuncEstim, ESW, effectiveDistance

Examples

# Load example thrasher data (point transect survey type)
data(thrasherDf)

# Fit half-normal detection function
dfunc <- thrasherDf |> dfuncEstim(formula=dist~bare)

# Compute effective detection radius (EDR)
EDR(dfunc) # vector length 192
effectiveDistance(dfunc) # same
EDR(dfunc, newdata = data.frame(bare=30)) # vector length 1

Description

Computes Effective Strip Width (ESW) for line-transect detection functions, or the analogous Effective Detection Radius (EDR) for point-transect detection functions.

Usage

effectiveDistance(object, newdata = NULL)

Arguments

Details

Serves as a wrapper for ESW and EDR.

Value

If newdata is present, the returned value is a vector of effective sampling distances for values of the covariates in newdata with length equal to the number of rows in newdata. If newdata is NULL, the returned value is a vector of effective sampling distances associated with covariate values in object and has the same number of detected groups. The returned vector has measurement units, i.e., object$outputUnits.

See Also

dfuncEstim ESW EDR

Description

Extract effort information from an Rdistance data frame. Effort is length of line-transects or number of points on point-transects.

Usage

effort(x, ...)

Arguments

Value

A vector containing effort. If line-transects, return is length of transects, with units. If point-transects, return is number of points (integers, no units). Vector length is number of transects. If input is not an RdistDf or estimated distance function, return is NULL.

Examples

data(sparrowDf)
effort(sparrowDf)
fit <- dfuncEstim(sparrowDf, dist ~ 1)
effort(fit)

Description

Constructs a string stating what is "unknown" that is suitable for use in warning and error functions.

Usage

errDataUnk(txt, attri)

Arguments

Value

A descriptive string, suitable for warning or error.

Description

Estimate abundance from an Rdistance fitted model. This function is called internally by abundEstim. Most users will call abundEstim to estimate abundance unless they are running simulations or bootstrapping.

Usage

estimateN(object, area = NULL, propUnitSurveyed = 1)

Arguments

Details

The abundance estimate for line-transect surveys (if no covariates are included in the detection function and both sides of the transect are observed) is

$N =\frac{n(A)}{2(ESW)(L)}$

where n is total number of sighted individuals (i.e., sum(groupSizes(dfunc))), L is the total length of surveyed transect (i.e., sum(effort(dfunc))), and ESW is effective strip width computed from the estimated distance function (i.e., ESW(dfunc)). If only one side of transects were observed, the "2" in the denominator is not present (or, replaced with a "1").

The abundance estimate for point transect surveys (if no covariates are included) is

$N =\frac{n(A)}{\pi(ESR^2)(P)}$

where n is total number of sighted individuals (i.e., sum(groupSizes(dfunc))), P is the total number of surveyed points (i.e., sum(effort(dfunc))), and ESR is effective search radius computed from the estimated distance function (i.e., ESR(dfunc)).

Setting plot.bs=FALSE and showProgress=FALSE suppresses all intermediate output.

Estimation of site-specific density (e.g., on every transect) is accomplished by predict(x, type = "density"), which returns a tibble containing density and abundance on the area surveyed by every transect.

Value

A list containing the following components:

For line-transects that do not involve covariates, object$density is object$n.seen / (2 * propUnitSurveyed * object$w * object$pDetection * object$surveyedUnits)

See Also

dfuncEstim, abundEstim

Description

Returns effective strip width (ESW) for line-transect detection functions. See EDR is for point transects.

Usage

ESW(object, newdata = NULL)

Arguments

Details

ESW is the area under the scaled distance function between its left-truncation limit (obj$w.lo) and its right-truncation limit (obj$w.hi).

If detection does not decline with distance, the detection function is flat (horizontal), and area under the detection function is $g(0)(w.hi - w.lo)$. If, in this case, $g(0) = 1$, effective sampling distance is the half-width of the surveys, $(w.hi - w.lo)$

Value

If newdata is present, the returned value is a vector of effective sampling distances for values of the covariates in newdata with length equal to the number of rows in newdata. If newdata is NULL, the returned value is a vector of effective sampling distances associated with covariate values in object and has the same number of detected groups. The returned vector has measurement units, i.e., object$outputUnits.

Numeric Integration

Rdistance uses Simpson's composite 1/3 rule to numerically integrate under distance functions. The number of points evaluated during numerical integration is controlled by options(Rdistance_intEvalPts) (default 101). Option 'Rdistance_intEvalPts' must be odd because Simpson's rule requires an even number of intervals (hence, odd number of points). Lower values of 'Rdistance_intEvalPts' increase calculation speeds; but, decrease accuracy. 'Rdistance_intEvalPts' must be >= 5. A warning is thrown if 'Rdistance_intEvalPts' < 29. Empirical tests by the author suggest 'Rdistance_intEvalPts' values >= 30 are accurate to several decimal points and that all 'Rdistance_intEvalPts' >= 101 produce identical results in all but pathological cases.

See Also

dfuncEstim, EDR, effectiveDistance

Examples

data(sparrowDf)
dfunc <- sparrowDf |> dfuncEstim(formula=dist~bare)

ESW(dfunc) # vector length 356 = number of groups
ESW(dfunc, newdata = data.frame(bare = c(30,40))) # vector length 2

Description

Compute "expansion" terms that modify the shape of a base distance function.

Usage

expansionTerms(a, d, series, nexp, w)

Arguments

Details

Expansion terms modify the "key" function of the likelihood manipulatively. The modified distance function is, key * expTerms where key is a vector of values in the base likelihood function (e.g., halfnorm.like()$L.unscaled or hazrate.like()$L.unscaled) and expTerms is the matrix returned by this routine.

Let the number of expansions (nexp) be $m$ ($m$ > 0), assume the raw cyclic expansion terms of series are $h_{j}(x)$ for the $j^{th}$ expansion of distance $x$, and that $a_1, a_2, \dots, a_m$ are (estimated) coefficients for the expansion terms, then the likelihood contribution for the $i^{th}$ distance $x_i$ is,

$f(x_i|\beta,a_1,a_2,\dots,a_m) = f(x_i|\beta)(1 + \sum_{k=1}^{m} a_k h_{k}(x_i/w)).$

Value

If nexp equals 0, 1 is returned. If nexp is greater than 0, a matrix of size $n$X$k$ containing expansion terms, where $n$ = length(d) and $k$ = nrow(a). The expansion series associated with row $j$ of a are in column $j$ of the return. i.e., element ($i$,$j$) of the return is

$1 + \sum_{k=1}^{m} a_{jk} h_{k}(x_{i}/w).$

(see Details).

Examples

a1 <- c(log(40), 0.5, -.5)
a2 <- c(log(40), 0.25, -.5)
dists <- units::set_units(seq(0, 100, length = 100), "m")
w = units::set_units(100, "m")

expTerms1 <- expansionTerms(a1, dists, "cosine", 2, w)
expTerms2 <- expansionTerms(a2, dists, "cosine", 2, w)
plot(dists, expTerms2, ylim = c(0,2.5))
points(dists, expTerms1, pch = 16)

# Same as above
a <- rbind(a1, a2)
expTerms <- expansionTerms(a, dists, "cosine", 2, w)
matlines(dists, expTerms, lwd=2, col=c("red", "blue"), lty=1)

# Showing key and expansions
key <- halfnorm.like(log(40), dists, 1)$L.unscaled
plot(dists, key, type = "l", col = "blue", ylim=c(0,1.5))
lines(dists, key * expTerms1, col = "red")
lines(dists, key * expTerms2, col = "purple")

Description

Extract the group size information from an Rdistance model frame.

Usage

groupSizes(ml, ...)

Arguments

Value

A vector containing group sizes contained in the Rdistance model frame or fitted object.

Examples

data("sparrowDf")
sparrowModel <- parseModel( sparrowDf, dist ~ observer )
stats::model.offset(sparrowModel$mf)
groupSizes(sparrowModel)  # same, but future-proof

sparrowModel <- parseModel( sparrowDf
                 , dist ~ observer + groupsize(groupsize) )
groupSizes(sparrowModel)

Description

Estimate distance function scaling factor , g(0) or g(x), for a specified distance function.

Usage

gxEstim(fit)

Arguments

Details

This routine scales sightability such that g(x.scl) = g.x.scl, where g() is the sightability function. Specification of x.scl and g.x.scl covers several estimation cases:

1. g(0) = 1 : (the default) Inputs are x.scl = 0, g.x.scl = 1. If w.lo > 0, x.scl will be set to w.lo so technically this case is g(w.low) = 1.

2. User supplied probability at specified distance: Inputs are x.scl = a number greater than or equal to w.lo, g.x.scl = a number between 0 and 1. This case covers situations where sightability on the transect (distance 0) is not perfect. This case assumes researchers have an independent estimate of sightability at distance x.scl off the transect. For example, researchers could be using multiple observers to estimate that sightability at distance x.scl is g.x.scl.

3. Maximum sightability specified: Inputs are x.scl="max", g.x.scl = a number between 0 and 1. In this case, g() is scaled such that its maximum value is g.x.scl. This routine computes the distance at which g() is maximum, sets g()'s height there to g.x.scl, and returns x.max where x.max is the distance at which g is maximized. This case covers the common aerial survey situation where maximum sightability is slightly off the transect, but the distance at which the maximum occurs is unknown.

4. Double observer system: Inputs are x.scl="max", g.x.scl = <a data frame>. In this case, g(x) = h, where x is the distance that maximizes g and h is the height of g() at x computed from the double observer data frame (see below for structure of the double observer data frame).

5. Distance of independence specified, height computed from double observer system: Inputs are x.scl = a number greater than or equal to w.lo g.x.scl = a data frame. In this case, g(x.scl) = h, where h is computed from the double observer data frame (see below for structure of the double observer data frame).

When x.scl, g.x.scl, or observer are NULL, the routine will look for and use $call.x.scl, or $call.g.x.scl, or $call.observer components of the fit object for whichever of these three parameters is missing. Later, different values can be specified in a direct call to F.gx.estim without having to re-estimate the distance function. Because of this feature, the default values in dfuncEstim are x.scl = 0 and g.x.scl = 1 and observer = "both".

Value

A list comprised of the following components:

Structure of the double observer data frame

When g.x.scl is a data frame, it is assumed to contain the components $obsby.1 and $obsby.2 (no flexibility on names). Each row in the data frame contains data from one sighted target. The $obsby.1 and $obsby.2 components are TRUE/FALSE (logical) vectors indicating whether observer 1 (obsby.1) or observer 2 (obsby.2) spotted the target.

See Also

dfuncEstim

Examples

data(sparrowDf)
fit <- dfuncEstim(sparrowDf, dist ~ groupsize(groupsize))
gxEstim(fit)
  
fit <- dfuncEstim(sparrowDf, dist ~ groupsize(groupsize)
                , x.scl = units::set_units(50,"m")
                , g.x.scl = 0.75)
gxEstim(fit)
plot(fit)
abline(h=0.75)
abline(v=units::set_units(50,"m"))

Description

Evaluate the half-normal distance function, for sighting distances, potentially including covariates and expansion terms

Usage

halfnorm.like(a, dist, covars)

Arguments

Details

The half-normal distance function is

$f(d|s) = \exp(-d^2 / (2*s^2))$

where $s = exp(x'a)$, $x$ is a vector of covariate values associated with distance $d$ (i.e., a row of covars), and $a$ is a vector of the first $q$ (=ncol(covars)) values in argument a.

Some authors parameterize the halfnorm without the "2" in the denominator of the exponent. Rdistance includes "2" in this denominator to make quantiles of the half normal agree with the standard normal. This means that half-normal coefficients in Rdistance (i.e., $s = exp(x'a)$) can be interpreted as normal standard errors. For example, approximately 95% of distances should occur between 0 and 2$s$.

Value

A list containing the following two components:

• L.unscaled: A matrix of size $n$X$k$X$b$ containing likelihood values evaluated at distances in dist. Each row is associated with a single distance, and each column is associated with a single case (row of a). This matrix is "unscaled" because the underlying likelihood does not integrate to one. Values in L.unscaled are always greater than or equal to zero.

• params: A $n$X$k$X$b$ array of the likelihood's (canonical) parameters, First page contains parameter values related to covariates (i.e., $s = exp(x'a)$), while subsequent pages contain other parameters. $b$ = 1 for halfnorm, negexp; $b$ = 2 for hazrate and others. Rows correspond to distances in dist. Columns correspond to rows from argument a.

See Also

dfuncEstim, hazrate.like, negexp.like

Examples

d <- seq(0, 100, length=100)
covs <- matrix(1,length(d),1)
halfnorm.like(log(20), d, covs)

plot(d, halfnorm.like(log(20), d, covs)$L.unscaled, type="l", col="red")
lines(d, halfnorm.like(log(40), d, covs)$L.unscaled, col="blue")

# Matrix inputs:
d <- matrix(c(0,10,20), ncol = 1) # 3X1
covs <- matrix(c(rep(1,nrow(d)), rep(.5,nrow(d))), nrow = nrow(d)) # 3X2
coefs <- matrix(log(c(15,5,10,10)), nrow=2) # 2X2
L <- halfnorm.like( coefs, d, covs ) 
L$L.unscaled # 3X2
L$params     # 3X2; exp(log(15)+0.5log(10)) and exp(log(5)+0.5log(10))

Description

Compute starting values and limits for the half normal distance function.

Usage

halfnorm.start.limits(ml)

Arguments

Value

A list containing the following components

The length of each vector in the return is: (Num expansions) + 1 + 1*(like %in% c("hazrate")) + (Num Covars).

Description

Computes the hazard rate distance function.

Usage

hazrate.like(a, dist, covars)

Arguments

Details

The hazard rate likelihood is

$f(x|\sigma,k) = 1 - \exp(-(x/\sigma)^{-k})$

where $\sigma$ determines location (i.e., distance at which the function equals 1 - exp(-1) = 0.632), and $k$ determines slope of the function at $\sigma$ (i.e., larger k equals steeper slope at $\sigma$). For distance analysis, the valid range for both $\sigma$ and k is $\geq 0$.

Value

A list containing the following two components:

• L.unscaled: A matrix of size $n$X$k$X$b$ containing likelihood values evaluated at distances in dist. Each row is associated with a single distance, and each column is associated with a single case (row of a). This matrix is "unscaled" because the underlying likelihood does not integrate to one. Values in L.unscaled are always greater than or equal to zero.

• params: A $n$X$k$X$b$ array of the likelihood's (canonical) parameters, First page contains parameter values related to covariates (i.e., $s = exp(x'a)$), while subsequent pages contain other parameters. $b$ = 1 for halfnorm, negexp; $b$ = 2 for hazrate and others. Rows correspond to distances in dist. Columns correspond to rows from argument a.

See Also

dfuncEstim, hazrate.like, negexp.like

Examples

d <- seq(0, 100, length=100)
covs <- matrix(1,length(d),1)
hazrate.like(c(log(20), 5), d, covs)

# Changing location parameter
plot(d, hazrate.like(c(log(20), 5), d, covs)$L.unscaled, type="l", col="red")
lines(d, hazrate.like(c(log(40), 5), d, covs)$L.unscaled, col="blue")
abline(h = 1 - exp(-1), lty = 2)
abline(v = c(20,40), lty = 2)

# Changing slope parameter
plot(d, hazrate.like(c(log(50), 20), d, covs)$L.unscaled, type="l", col="red")
lines(d, hazrate.like(c(log(50), 2), d, covs)$L.unscaled, col="blue")
abline(h = 1 - exp(-1), lty = 2)
abline(v = 50, lty = 2)

Description

Compute starting values and limits for the hazard rate distance function.

Usage

hazrate.start.limits(ml)

Arguments

Value

A list containing the following components

The length of each vector in the return is: (Num expansions) + 1 + 1*(like %in% c("hazrate")) + (Num Covars).

Description

Computes the Hermite expansion terms used in the likelihood of a distance analysis. More generally, will compute a Hermite expansion of any numeric vector.

Usage

hermite.expansion(x, expansions)

Arguments

Details

There are, in general, several expansions that can be called Hermite. The Hermite expansion used here is:

• First term:

  $h_1(x)=x^4 - 6x^2 + 3,$

• Second term:

  $h_2(x)=x^6 - 15x^4 + 45x^2 - 15,$

• Third term:

  $h_3(x)=x^8 - 28x^6 + 210x^4 - 420x^2 + 105,$

• Fourth term:

  $h_4(x)=x^10 - 45x^8 + 630x^6 - 3150x^4 + 4725x^2 - 945,$

The maximum number of expansion terms computed is 4.

Value

A matrix of size length(x) X expansions. The columns of this matrix are the Hermite polynomial expansions of x. Column 1 is the first expansion term of x, column 2 is the second expansion term of x, and so on up to expansions.

See Also

dfuncEstim, cosine.expansion, simple.expansion, and the discussion of user defined likelihoods in dfuncEstim.

Examples

x <- seq(0, 1, length = 200)
herm.expn <- hermite.expansion(x, 4)
plot(range(x), range(herm.expn), type="n")
matlines(x, herm.expn, col=rainbow(4), lty = 1)

Description

Utility function to detect whether a distance function has covariates beyond the intercept. If the model contains an intercept-only, effective distance is constant across detections and short-cuts can be implemented in code.

Usage

intercept.only(object)

Arguments

Value

TRUE if object contains an intercept-only. FALSE if object contains at least one detection-level or transect-level covariate in the detection function.

Description

Determines whether a distance function is for a point survey or line survey.

Usage

is.points(x)

Arguments

Value

TRUE if the model frame or fitted distance function contains point surveys. FALSE if the model frame or distance function contains line transect surveys.

Description

Checks the validity of Rdistance nested data frames. Rdistance data frames are a particular implementation of rowwise tibbles that contain detections in a list column, and extra attributes specifying types.

Usage

is.RdistDf(df, verbose = FALSE)

Arguments

Details

The following checks are performed (in this order):

• attr(df, "detectionColumn") exists and points to a valid list-based column in the data frame.

• attr(df, "obsType") exists and is one of the valid values.

• attr(df, "transType") exists and is one of the valid values.

• The data frame is either a 'rowwise_df' or 'grouped_df' tibble.

• The data frame has only one row per group. One row per group is implied by 'rowwise_df', but not a 'grouped_df', and both are allowed in Rdistance. One row per group ensures rows are uniquely identified and hence represents one transect.

• No column names in the list-column are duplicated in the non-list columns of the data frame. This check ensures that tidyr::unnest executes.

Other data checks, e.g., for measurement units, are performed later in dfuncEstim, after the model is specified.

Value

TRUE or FALSE invisibly. TRUE means all checks passed. FALSE implies at least one check failed. Use verbose = TRUE to see which.

Examples

data(sparrowDf)
is.RdistDf(sparrowDf)

# Data frame okay, but no attributes
data(sparrowDetectionData)
data(sparrowSiteData)
sparrowDf <- sparrowDetectionData |> 
  dplyr::nest_by( siteID
               , .key = "distances") |> 
  dplyr::right_join(sparrowSiteData, by = "siteID")
is.RdistDf(sparrowDf, verbose = TRUE)

Description

Determines whether a distance function is a non-parametric smooth or classic parameterized function.

Usage

is.smoothed(object)

Arguments

Value

TRUE if the model frame or fitted distance function arises from a non-parametric density smoother. FALSE if the model frame or distance function is a parameterized function.

Description

Tests whether a 'units' object is actually unitless. Unitless objects, such as ratios, should be assigned units of '[1]'. Often they are, but sometimes unitless ratios are assigned units like '[m/m]'. The units package should always convert '[m/m]' to '[1]', but it does not always. Sometimes units like '[m/m]' mess things up, so it is better to remove them before calculations.

Usage

is.Unitless(obj)

Arguments

Value

TRUE if obj has units and they are either '[1]' or the denominator units equal the numerator units. Otherwise, return FALSE. If obj does not have units, this routine returns TRUE.

Examples

a <- units::set_units(2, "m")
b <- a / a
is.Unitless(a)
is.Unitless(b)
is.Unitless(3)

Description

Returns names of the likelihood parameters. This is a helper function and is not necessary for estimation. It is a nice to label some outputs in Rdistance with parameter names like "sigma" or "knee", depending on the likelihood, and this routine provides a way to do that.

Usage

likeParamNames(like.form)

Arguments

Details

For user defined functions, ensure that the user defined start-limits function named <likelihood>.start.limits can be evaluated on a distance of 1, can accept 0 expansions, a low limit of 0 a high limit of 1, and that it returns the parameter names as the $names component of the result. That is, the code that returns user-defined parameter names is, fn <- match.fun( paste0(like.form, ".start.limits")); ans <- fn(1, 0, 0, 1); ans$names

Value

A vector of parameter names for that likelihood

Description

Line plot method for objects of class 'dfunc' that adds distance functions to an existing plot.

Usage

## S3 method for class 'dfunc'
lines(x, newdata = NULL, prob = NULL, ...)

Arguments

Value

A data frame containing the x and y coordinates of the plotted line(s) is returned invisibly. X coordinates in the return are names x. Y coordinates in the return are named y1, y2, ..., yn, i.e., one column per returned distance function.

See Also

dfuncEstim, plot.dfunc, print.abund

Examples

set.seed(87654)
x <- rnorm(1000, mean=0, sd=20)
x <- x[x >= 0]
x <- units::set_units(x, "mi")
Df <- data.frame(transectID = "A"
               , distance = x
                ) |> 
  dplyr::nest_by( transectID
               , .key = "detections") |> 
  dplyr::mutate(length = units::set_units(100,"km"))              
attr(Df, "detectionColumn") <- "detections"
attr(Df, "obsType") <- "single"
attr(Df, "transType") <- "line"
attr(Df,'effortColumn') <- "length"
is.RdistDf(Df)  # TRUE

dfunc <- Df |> dfuncEstim(distance ~ 1, likelihood="halfnorm")
plot(dfunc, nbins = 40, col="lightgrey", border=NA, vertLines=FALSE)
lines(dfunc, col="grey30", lwd=15)
lines(dfunc, col="grey90", lwd=5, lty = 2)

# Multiple lines 
data(sparrowDfuncObserver)
obsLevs <- levels(sparrowDfuncObserver$data$observer)
plot(sparrowDfuncObserver
   , vertLines = FALSE
   , lty = 0
   , plotBars = FALSE
   , main="Detection by observer"
   , legend = FALSE)
y <- lines(sparrowDfuncObserver
   , newdata = data.frame(observer = obsLevs)
   , col = palette.colors(length(obsLevs))
   , lty = 1
   , lwd = 4)
head(y) # values returned, with distances as column

Description

Find the x coordinate that maximizes g(x).

Usage

maximize.g(fit, covars = NULL)

Arguments

Value

The value of x that maximizes g(x) in fit.

See Also

dfuncEstim

Examples

## Not run: 
# Fake data
set.seed(22223333)
x <- rgamma(100, 10, 1)

fit <- dfuncEstim( x, likelihood="Gamma", x.scl="max" )

maximize.g( fit )  # should be near 10.
fit$x.scl            # same thing

## End(Not run)

Description

Estimate parameters of a distance function using maximum likelihood.

Usage

mlEstimates(ml, strt.lims)

Arguments

Value

An Rdistance fitted model object. This object contains the raw object returned by the optimization routine (e.g., nlming), and additional components specific to Rdistance.

Description

Extract the model matrix ("X" matrix) from an Rdistance model object.

Usage

## S3 method for class 'dfunc'
model.matrix(object, ...)

Arguments

Value

A matrix containing covariates for fitting an Rdistance model.

Examples

data(sparrowDf)
sparrowModel <- parseModel( sparrowDf, dist ~ observer )
model.matrix(sparrowModel)

Description

Return number of covariates in a distance model

Usage

nCovars(X)

Arguments

Details

The reason this routine is needed is that sometimes we pass one row of covariates to a likelihood function. If so, it may come in as a normal vector, not a matrix. If a normal vector, ncol(X) does not work.

Value

An integer scalar

# do not export

Description

Computes the negative exponential distance function.

Usage

negexp.like(a, dist, covars)

Arguments

Details

The negative exponential likelihood is

$f(x|a) = \exp(-ax)$

where $a$ is the slope parameter.

Value

A list containing the following two components:

• L.unscaled: A matrix of size $n$X$k$X$b$ containing likelihood values evaluated at distances in dist. Each row is associated with a single distance, and each column is associated with a single case (row of a). This matrix is "unscaled" because the underlying likelihood does not integrate to one. Values in L.unscaled are always greater than or equal to zero.

• params: A $n$X$k$X$b$ array of the likelihood's (canonical) parameters, First page contains parameter values related to covariates (i.e., $s = exp(x'a)$), while subsequent pages contain other parameters. $b$ = 1 for halfnorm, negexp; $b$ = 2 for hazrate and others. Rows correspond to distances in dist. Columns correspond to rows from argument a.

See Also

dfuncEstim, hazrate.like, negexp.like

Examples

d <- seq(0, 100, length=100)
covs <- matrix(1,length(d),1)
negexp.like(log(0.01), d, covs)

# Changing slope parameter
plot(d, negexp.like(log(0.1), d, covs)$L.unscaled, type="l", col="red")
lines(d, negexp.like(log(0.05), d, covs)$L.unscaled, col="blue")

Description

Compute starting values and limits for the negative exponential distance function.

Usage

negexp.start.limits(ml)

Arguments

Value

A list containing the following components

The length of each vector in the return is: (Num expansions) + 1 + 1*(like %in% c("hazrate")) + (Num Covars).

Description

Return the negative log likelihood of observed detection distances given a likelihood and the estimated parameters.

Usage

nLL(a, ml)

Arguments

Details

Expansion Terms: If ml$expansions = k (k > 0), the expansion function specified by ml$series is called (see for example cosine.expansion). Assuming $h_{ij}(x)$ is the $j^{th}$ expansion term for the $i^{th}$ distance and that $c_1, c_2, \dots, c_k$ are (estimated) coefficients for the expansion terms, the likelihood contribution for the $i^{th}$ distance is,

$f(x|a,b,c_1,c_2,\dots,c_k) = f(x|a,b)(1 + \sum_{j=1}^{k} c_j h_{ij}(x)).$

Value

A scalar, the negative of the log likelihood evaluated at parameters a.

See Also

See halfnorm.like and links there; dfuncEstim

Examples

set.seed(238642)

d <- rnorm(1000, mean = 0, sd = 40)
d <- units::set_units(d[0 <= d], "m")

# Min info in model list to compute likelihood
ml <- list(
    mf = model.frame(d ~ 1) 
  , likelihood = "halfnorm"
  , expansions = 0
  , w.lo = units::set_units(0, "m")
  , w.hi = units::set_units(125, "m")
  , outputUnits = units(units::set_units(1,"m"))
  , x.scl = units::set_units(0,"m")
  , g.x.scl = 1
  , data = 1
)
attr(ml$data, "transType") <- "line"
class(ml) <- "dfunc"
nLL(log(40), ml)

# Another way, b/c we have pnorm()
ones <- matrix(1, nrow = length(d), ncol = 1)
l <- halfnorm.like(log(40), d, ones)
scaler <-(pnorm(units::drop_units(ml$w.hi)
  , units::drop_units(ml$w.lo)
  , sd = l$params) - 0.5) * sqrt(2*pi) * l$params
-sum(log(l$L.unscaled/scaler))

# A third way, b/c we have pnorm() and dnorm(). 
l2 <- dnorm(units::drop_units(d), mean = 0, sd = 40)
scaler2 <- pnorm(125, mean = 0, sd = 40) - 0.5 
-sum(log(l2/scaler2))

Description

Return the type of observations (single or multiple observers) represented in either a fitted distance function or Rdistance data frame.

Usage

observationType(x)

Arguments

Details

This function is a simple helper function. If x is an estimated distance object, it polls the obsType attribute of the object's Rdistance data frame. If x is an Rdistance nested data frame, it polls the obsType attribute.

Value

One of the following values: "single", "1given2", "2given1", or "both". If observation type has not been assigned, return is NULL.

Description

An internal (un-exported) function to perform density and abundance calculations on one iteration of the bootstrap.

Usage

oneBsIter(
  indexDf,
  key,
  data,
  formula,
  likelihood,
  w.lo,
  w.hi,
  expansions,
  series,
  x.scl,
  g.x.scl,
  outputUnits,
  warn,
  area,
  propUnitSurveyed,
  pb,
  plot.bs,
  plotCovValues
)

Arguments

Value

A data frame containing density and abundance and other relevant statistics for one iteration of the bootstrap.

Description

Parse an 'Rdistance' formula and produce a list containing all model parameters.

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
)

Arguments

Details

This routine is not intended to be called by the user. It is called from the model estimation routines in Rdistance.

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(sparrowSiteData)
data(sparrowDetectionData)

sparrowDf <- Rdistance::RdistDf(sparrowSiteData
   , sparrowDetectionData
   , by = NULL
   , pointSurvey = FALSE
   , observer = "single"
   , .detectionCol = "detections")
   
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)

Description

Computes off-transect (also called 'perpendicular') distances from measures of sighting distance and sighting angle.

Usage

perpDists(sightDist, sightAngle, data)

Arguments

Details

If observers recorded sighting distance and sighting angle (as is often common in line transect surveys), use this function to convert to off-transect distances, the required input data for dfunc.estim.

Value

A vector of off-transect (or perpendicular) distances. Units are the same as sightDist.

References

Buckland, S.T., Anderson, D.R., Burnham, K.P. and Laake, J.L. 1993. Distance Sampling: Estimating Abundance of Biological Populations. Chapman and Hall, London.

See Also

dfuncEstim

Examples

# Load the example dataset of sparrow detections from package
data(sparrowDetectionData)
# Compute perpendicular, off-transect distances from the observer's sight distance and angle
sparrowDetectionData$perpDist <- perpDists(sightDist="sightdist", sightAngle="sightangle",
                                           data=sparrowDetectionData)

Description

Plot method for objects of class 'dfunc'. Objects of class 'dfunc' are estimated distance functions produced by dfuncEstim.

Usage

## S3 method for class 'dfunc'
plot(x, ...)

Arguments

Details

If plotBars is TRUE, a scaled histogram is plotted and the estimated distance function is plotted over the top of it. When bars are plotted, this routine uses graphics::barplot for setting up the initial plotting region and most parameters to graphics::barplot can be specified (exceptions noted above in description of '...').

The form of the likelihood and any series expansions is printed in the main title (overwrite this with main="<my title>"). Convergence of the distance function is checked. If the distance function did not converge, a warning is printed over the top of the histogram. If one or more parameter estimates are at their limits (likely indicating non-convergence or poor fit), another warning is printed.

Value

The input distance function is returned, with two additional components than can be used to reconstruct the plotted bars. (To obtain values of the plotted distance functions, use predict with type = "distances".) The additional components are:

Re-plot the bars with barplot( return$barHeights, width = return$barWidths ).

See Also

dfuncEstim, print.dfunc, print.abund

Examples

set.seed(87654)
x <- rnorm(1000, mean=0, sd=20)
x <- x[x >= 0]
x <- units::set_units(x, "ft")
Df <- data.frame(transectID = "A"
               , distance = x
                ) |> 
  dplyr::nest_by( transectID
               , .key = "detections") |> 
  dplyr::mutate(length = units::set_units(1,"mi"))
attr(Df, "detectionColumn") <- "detections"
attr(Df, "obsType") <- "single"
attr(Df, "transType") <- "line"
attr(Df, "effortColumn") <- "length"
is.RdistDf(Df) # TRUE

dfunc <- Df |> dfuncEstim(distance ~ 1, likelihood="halfnorm")
plot(dfunc)
plot(dfunc, nbins=25)

# showing effects of plot params
plot(dfunc
  , col=c("red","blue","orange")
  , border="black"
  , xlab="Off-transect distance"
  , ylab="Prob"
  , vertLines = FALSE
  , main="Showing plot params")
 
plot(dfunc
   , col="purple"
   , density=30
   , angle=c(-45,0,45)
   , cex.axis=1.5
   , cex.lab=2
   , ylab="Probability") 

plot(dfunc
   , col=c("grey","lightgrey")
   , border=NA) 

plot(dfunc
   , col="grey"
   , border=0
   , col.dfunc="blue"
   , lty.dfunc=2
   , lwd.dfunc=4
   , vertLines=FALSE)

plot(dfunc
   , plotBars=FALSE
   , cex.axis=1.5
   , col.axis="blue")
rug(distances(dfunc))

# Plot showing f(0)
hist(distances(dfunc)
   , n = 40
   , border = NA
   , prob = TRUE)
x <- seq(dfunc$w.lo, dfunc$w.hi, length=200)
g <- predict(dfunc, type="dfunc", distances = x, newdata = data.frame(a=1))
f <- g[,1] / ESW(dfunc)[1]
# Check integration:
sum(diff(x)*(f[-1] + f[-length(f)]) / 2) # Trapazoid rule; should be 1.0
lines(x, f) # hence, 1/f(0) = ESW

# Covariates: detection by observer
data(sparrowDfuncObserver) # pre-estimated model

obsLevs <- levels(sparrowDfuncObserver$data$observer)
plot(sparrowDfuncObserver
   , newdata = data.frame(observer = obsLevs)
   , vertLines = FALSE
   , col.dfunc = heat.colors(length(obsLevs))
   , col = c("grey","lightgrey")
   , border=NA
   , main="Detection by observer")

Description

Plot method for parametric line and point transect distance functions.

Usage

## S3 method for class 'dfunc.para'
plot(
  x,
  include.zero = FALSE,
  nbins = "Sturges",
  newdata = NULL,
  legend = TRUE,
  vertLines = TRUE,
  plotBars = TRUE,
  circles = FALSE,
  density = -1,
  angle = 45,
  xlab = NULL,
  ylab = NULL,
  border = TRUE,
  col = "grey85",
  col.dfunc = NULL,
  lty.dfunc = NULL,
  lwd.dfunc = NULL,
  ...
)

Arguments

Value

The input distance function is returned, with two additional components than can be used to reconstruct the plotted bars. (To obtain values of the plotted distance functions, use predict with type = "distances".) The additional components are:

Re-plot the bars with barplot( return$barHeights, width = return$barWidths ).

See Also

plot.dfunc

Examples

# Example data
set.seed(87654)
x <- rnorm(1000, mean=0, sd=20)
x <- x[x >= 0]
x <- units::set_units(x, "ft")
Df <- data.frame(transectID = "A"
               , distance = x
                ) |> 
  dplyr::nest_by( transectID
               , .key = "detections") |> 
  dplyr::mutate(length = units::set_units(1,"mi"))
attr(Df, "detectionColumn") <- "detections"
attr(Df, "obsType") <- "single"
attr(Df, "transType") <- "line"
attr(Df, "effortColumn") <- "length"
is.RdistDf(Df) # TRUE

# Estimation
dfunc <- dfuncEstim(Df
                  , formula = distance~1
                  , likelihood="halfnorm")
plot(dfunc)
plot(dfunc, nbins=25)

Description

An internal prediction method for computing density on the sampled transects.

Usage

predDensity(object, propUnitSurveyed = 1)

Arguments

Value

A data frame containing the original data used to fit the distance function, plus an additional column containing the density of individuals on each transect.

Examples

data(sparrowDfuncObserver)
predict(sparrowDfuncObserver, type="density")

Description

An internal prediction function to predict a distance function. This version allows for matrix inputs and uses matrix operations, and is thus faster than earlier looping versions.

Usage

predDfuncs(object, params, distances, isSmooth)

Arguments

Value

A matrix of distance function values, of size length(distances) X nrow(params). Each row of params is associated with a column, i.e., a different distance function. Distances are associated with rows, i.e., use matplot(d,return) to plot values on separate distance functions specified by rows of params.

Description

Predict either likelihood parameters, distance functions, site-specific density, or site-specific abundance from estimated distance function objects.

Usage

## S3 method for class 'dfunc'
predict(
  object,
  newdata = NULL,
  type = c("parameters"),
  distances = NULL,
  propUnitSurveyed = 1,
  area = NULL,
  ...
)

Arguments

Value

A matrix containing predictions:

• If type is "parameters", the returned matrix contains likelihood parameters. The extent of the first dimension (rows) in the returned matrix is equal to either the number of detection distances in the observed strip or number of rows in newdata. The returned matrix's second dimension (columns) is the number of parameters in the likelihood plus the number of expansion terms. See the help for each likelihoods to interpret returned parameter values. All parameters are returned on the inverse-link scale; i.e., exponential for canonical parameters and identity for expansion terms.

• If type is "dfuncs" or "dfunc", columns of the returned matrix contains detection functions (i.e., g(x)). The extent of the first dimension (number of rows) is either the number of distances specified in distances or options()$Rdistance_intEvalPts if distances is not specified. The extent of the second dimension (number of columns) is:

  • the number of detections with non-missing distances: if newdata is NULL.

  • the number of rows in newdata if newdata is specified.

  All distance functions in columns of the return are scaled to object$g.x.scale at object$x.scl. The returned matrix has the following additional attributes:

  • attr(return, "distances") is the vector of distances used to predict the function in return. Either the input distances object or the computed sequence of distances when distances is NULL.

  • attr(return, "x0") is the vector of distances at which each distance function in return was scaled. i.e., the vector of x.scl.

  • attr(return, "g.x.scl") is the height of g(x) (the distance function) at x0.

• If type is "density" or "abundance", the return is a tibble containing density and abundance estimates by transect. All transects in the input data (i.e., object$data) are included, even those with missing lengths. Columns in the tibble are:

  • transect ID: the grouping factor of the original RdistDf object.

  • individualsSeen: sum of non-missing group sizes on that transect.

  • avgPdetect: average probability of detection over groups sighted on that transect.

  • effort: size of the area surveyed by that transect.

  • density: density of individuals in the area surveyed by the transect.

  • abundance: abundance of individuals in the area surveyed by the transect.

See Also

halfnorm.like, negexp.like, hazrate.like

Examples

data("sparrowDf")

# For dimension checks:
nd <- getOption("Rdistance_intEvalPts")

# No covariates
dfuncObs <- sparrowDf |> dfuncEstim(formula = dist ~ 1
                     , w.hi = units::as_units(100, "m"))
                     
n  <- nrow(dfuncObs$mf)
p <- predict(dfuncObs) # parameters
all(dim(p) == c(n, 1)) 

# values in newdata ignored because no covariates
p <- predict(dfuncObs, newdata = data.frame(x = 1:5))
all(dim(p) == c(5, 1)) 

# Distance functions in columns, one per observation
p <- predict(dfuncObs, type = "dfunc") 
all(dim(p) == c(nd, n))

d <- units::set_units(c(0, 20, 40), "ft")
p <- predict(dfuncObs, distances = d, type = "dfunc") 
all(dim(p) == c(3, n))

p <- predict(dfuncObs
   , newdata = data.frame(x = 1:5)
   , distances = d
   , type = "dfunc") 
all(dim(p) == c(3, 5))

# Covariates
data(sparrowDfuncObserver) # pre-estimated object
## Not run: 
# Command to generate 'sparrowDfuncObserver'
sparrowDfuncObserver <- sparrowDf |> 
            dfuncEstim(formula = dist ~ observer
                     , likelihood = "hazrate")

## End(Not run)

predict(sparrowDfuncObserver)  # n X 2

Observers <- data.frame(observer = levels(sparrowDf$observer))
predict(sparrowDfuncObserver, newdata = Observers) # 5 X 2

predict(sparrowDfuncObserver, type = "dfunc") # nd X n
predict(sparrowDfuncObserver, newdata = Observers, type = "dfunc") # nd X 5
d <- units::set_units(c(0, 150, 400), "ft")
predict(sparrowDfuncObserver
  , newdata = Observers
  , distances = d
  , type = "dfunc") # 3 X 5

# Density and abundance by transect
predict(sparrowDfuncObserver
  , type = "density")