Rdistance (version 3.0.0)

predict.dfunc: Predict method for dfunc objects

Description

Predict likelihood parameters for distance function objects

Usage

# S3 method for dfunc
predict(object, newdata = NULL, type = c("parameters"), distances = NULL, ...)

Value

A matrix containing one of two types of predictions:

• If type is "parameters", the returned matrix contains predicted likelihood parameters. The extent of the first dimension (rows) in the returned matrix is equal to either the number of detection distances in object$detections 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. Without expansion terms, the number of columns in the returned matrix is either 1 or 2 depending on the likelihood (e.g., halfnorm has one parameter, hazrate has two). See the help for each likelihoods to interpret the returned parameter values.

• If type is not "parameters", the returned matrix contains scaled distance functions. The extent of the first dimension (rows) is either the number of distances specified in distance or 200 if distances is not specified. The extent of the second dimension (columns) is:

  • 1: if object does NOT contain covariates.

  • the number of detections: if object contains covariates and newdata is NULL.

  • the number of rows in newdata: if object contains covariates and newdata is specified.

  All distance functions in columns of the return are scaled to object$g.x.scale at object$x.scl.

  When type is not "parameters", the returned matrix has additional attributes containing the distances at which the functions are scaled and ESW's. attr(return, "x0") is the vector of distances at which each distance function in <return> is scaled. i.e., the vector of x.scl. attr(return, "scaler") is a vector scaling factors corresponding to each distance function in return. i.e., the vector of 1/f(x.scl) where f() is the unscaled distance function. If object contains line transects, attr(return, "scaler") is a vector of ESW corresponding to each distance function.

Arguments

object

An estimated dfunc object. See dfuncEstim.

newdata

A data frame containing new values of the covariates at which predictions are to be computed. If newdata is NULL, predictions are made at values of the observed covariates and results in one prediction (either parameters or distance function, see parameter type) for every observed distance. If newdata is not NULL and the model does not contains covariates, this routine returns one prediction (either parameters or distance function) for each row in newdata, but columns and values in newdata are ignored.

type

The type of predictions desired.

• If type = "parameters": Return predicted parameters of the likelihood function, one value for each observation (row) in newdata. If newdata is NULL, return one predicted parameter value for every detection in object$detections.

• If type is not "parameters": Return scaled distance functions. Distance functions are evaluated at the distances specified in distances. The number of distance functions returned depends on newdata and whether object contains covariates:

  • If object does NOT contain covariates, the distance function does not vary (by covariate) and only one distance function will be returned, even if newdata is specified.

  • If object contains covariates, one distance function will be returned for each observation (row) in newdata. If newdata is NULL, one distance function will be returned for every detection in object$detections.

If object is a smoothed distance function, it does not have parameters and this routine will always return a scaled distance function. That is, type = "parameters" when object is smoothed does not make sense and the smoothed distance function estimate will be returned.

distances

A vector of distances when distance functions are requested. distances must have measurement units. Any distances outside the observation strip (object$w.lo to object$w.hi) are discarded. If distances is NULL, this routine uses a sequence of 200 evenly spaced distances between object$w.lo and object$w.hi, inclusive

...

Included for compatibility with generic predict methods.

See Also

halfnorm.like, negexp.like, uniform.like, hazrate.like, Gamma.like

Examples

data(sparrowDetectionData)
data(sparrowSiteData)
# No covariates
dfuncObs <- dfuncEstim(formula = dist ~ 1
                     , detectionData = sparrowDetectionData
                     , w.hi = units::as_units(100, "m"))
predict(dfuncObs)
# values in newdata ignored because no covariates
predict(dfuncObs, newdata = data.frame(x = 1:5)) 

predict(dfuncObs, type = "dfunc") # one function

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

# Covariates
dfuncObs <- dfuncEstim(formula = dist ~ observer
                     , detectionData = sparrowDetectionData
                     , siteData = sparrowSiteData
                     , w.hi = units::as_units(100, "m"))
predict(dfuncObs)  # 356 X 1

Observers <- data.frame(observer = levels(sparrowSiteData$observer))
predict(dfuncObs, newdata = Observers) # 5 X 1

predict(dfuncObs, type = "dfunc") # 200 X 356
predict(dfuncObs, newdata = Observers, type = "dfunc") # 200 X 5
predict(dfuncObs, newdata = Observers, distances = d, type = "dfunc") # 3 X 5