predict.dfunc {Rdistance} | R Documentation |
predict.dfunc - Predict distance functions
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
object |
An Rdistance model frame or fitted distance function,
normally produced by a call to |
newdata |
A data frame containing new values of
the covariates at which to evaluate the distance functions.
If |
type |
The type of predictions desired.
If |
distances |
A vector or 1-column matrix of
distances at which to evaluate
distance functions, when distance functions
are requested. |
propUnitSurveyed |
A scalar or vector of real numbers between 0 and 1.
The proportion of the default sampling unit that
was surveyed. If both sides of line transects were observed,
|
area |
A scalar containing the total area of inference. Usually, this is
study area size. If |
... |
Included for compatibility with generic |
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 innewdata
. 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 indistances
oroptions()$Rdistance_intEvalPts
ifdistances
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
ifnewdata
is specified.
All distance functions in columns of the return are scaled to
object$g.x.scale
atobject$x.scl
. The returned matrix has the following additional attributes:-
attr(return, "distances")
is the vector of distances used to predict the function inreturn
. Either the inputdistances
object or the computed sequence of distances whendistances
is NULL. -
attr(return, "x0")
is the vector of distances at which each distance function inreturn
was scaled. i.e., the vector ofx.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")