Numerically integrate under a distance function.
integrateNumeric(
object,
newdata = NULL,
w.lo = NULL,
w.hi = NULL,
Units = NULL,
expansions = NULL,
series = NULL,
isPoints = NULL,
likelihood = NULL
)A vector of areas under the distance functions represented in
object.
If object is a distance function and
newdata is specified, the returned vector's length is
nrow(newdata). If object is a distance function and
newdata is NULL,
returned vector's length is length(distances(object)). If
object is a matrix, return's length is
nrow(object).
Either an Rdistance fitted distance function
(an object that inherits from class "dfunc"; usually produced
by a call to dfuncEstim), or a matrix of canonical
distance function parameters (e.g., matrix(exp(fit$par),1)).
If a matrix, each row corresponds to a
distance function and each column is a parameter. The first column is
the parameter related to sighting covariates and must be transformed
to the "real" space (i.e., inverse link, which is \(exp()\), must
be applied outside this routine). If object is a matrix,
it should not have measurement units because
only derived quantities (e.g., ESW) have units; Rdistance function
parameters themselves never have units.
A data frame containing new values for
the distance function covariates. If NULL and
object is a fitted distance function, the
observed covariates stored in
object are used (behavior similar to predict.lm).
Argument newdata is ignored if object is a matrix.
Minimum sighting distance or left-truncation value
if object is a matrix.
Ignored if object
is a fitted distance function.
Must have physical measurement units.
Maximum sighting distance or right-truncation value
if object is a matrix.
Ignored if object
is a fitted distance function.
Must have physical measurement units.
Physical units of sighting distances if
object is a matrix. Sighting distance units can differ from units
of w.lo or w.hi. Ignored if object
is a fitted distance function.
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).
If expansions > 0, this string
specifies the type of expansion to use. Valid values at
present are 'simple', 'hermite', and 'cosine'.
Boolean. TRUE if integration is for point surveys. FALSE for line-transect surveys. Line-transect surveys integrate under the distance function, g(x), while point surveys integrate under the distance function times distances, xg(x).
String specifying the likelihood to fit. Built-in likelihoods at present are "halfnorm", "hazrate", and "negexp".
Rdistance uses Simpson's composite 1/3 rule to numerically
integrate distance functions from 0 to the maximum sighting distance
(w.hi - w.lo). 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.
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 for smooth distance functions
(e.g., hazrate, halfnorm, negexp)
and that all 'Rdistance_intEvalPts' >= 101 produce
identical results if the distance function is not smooth.
Details: Let n = options(Rdistance_intEvalPts).
Evaluate the distance function at n equal-spaced
locations {f(x0), f(x1), ..., f(xn)} between 0 and (w.hi - w.lo).
Simpson's composite approximation to the area under the curve is
$$\frac{1}{3}h(f(x_0) + 4f(x_1) + 2f(x_2) +
4f(x_3) + 2f(x_4) + ... + 2f(x_{n-2}) +
4f(x_{n-1}) + f(x_{n}))$$
where \(h\) is the interval size (w.hi - w.lo) / n.
Physical units on the return values
are the original (linear) units if object contains line-transect data
(e.g., [m]), or square of the original units if object contains
point-transect data (e.g., [m^2]). Point-transect units are squared because
the likelihood is the product of the detection function (which is unitless)
and distances (which have units).
# A halfnorm distance function
fit <- dfuncEstim(sparrowDf, dist~1, likelihood = "halfnorm")
exact <- integrateHalfnormLines(fit)[1,] # exact area
apprx <- integrateNumeric(fit)[1] # Numeric approx
pd <- options(digits = 20)
cbind(exact, apprx)
absDiff <- abs(apprx - exact)
absDiff
options(pd)
# halfnorm approx good to this number of digits
round(log10(absDiff),1)
Run the code above in your browser using DataLab