predict: Predict from fitted models and other unmarked objects

In unmarked: Models for Data from Unmarked Animals

Predict from fitted models and other unmarked objects

Description

These methods return predicted values from unmarkedFit objects, fitLists, or ranef output. Most object types use the same method, but some have unique options; see usage below.

Usage

## S4 method for signature 'unmarkedFit'
predict(object, type, newdata, backTransform = TRUE,
  na.rm = TRUE, appendData = FALSE, level = 0.95, re.form = NULL, ...)
## S4 method for signature 'unmarkedFitOccuMulti'
predict(object, type, newdata,
  level = 0.95, species = NULL, cond = NULL, nsims = 100, ...)
## S4 method for signature 'unmarkedFitOccuMS'
predict(object, type, newdata,
  level = 0.95, nsims = 100, ...)
## S4 method for signature 'unmarkedFitList'
predict(object, type, newdata = NULL,
  backTransform = TRUE, appendData = FALSE, level = 0.95)
## S4 method for signature 'unmarkedRanef'
predict(object, func, nsims = 100, ...)

Arguments

object	A unmarkedFit, unmarkedFitList, or unmarkedRanef object.
type	The submodel to predict values for, such as state or det. The available types depend on the model.
newdata	Optional; provide a data.frame of new covariate values to predict with. If not supplied, the original data are used.
backTransform	Logical. If TRUE, returned values are on the original (e.g. probability, abundance) scale.
na.rm	Logical. Should missing values be removed when predicting from original data?
appendData	Logical. Should covariate data used for prediction be appended to the output data frame?
level	The confidence interval to calculate. For example 0.95 results in lower and upper bounds for a 95% confidence interval. If set to NULL, no SE or confidence intervals will be returned.
re.form	For unmarkedFit types that support random effects, should the random effects be included in the prediction? If NULL, they will be, if NA, they will not be.
species	Which species (integer or species name as a string) should predictions be calculated for? For unmarkedFitOccuMulti only. If multiple species are provided, the co-occurence probability is returned. See occuMulti.
cond	Which species (integer or species name as a string) should predictions be calculated conditional on? If conditional on species presence, supply just the species name; if species absence, put a minus sign in front of the species name, e.g. "-coyote". See occuMulti.
nsims	Number of bootstrap simulations to use. Relevant only for some predict types.
func	A function to apply to bootstrapped unmarkedRanef samples; see details.
...	Other arguments, currently ignored

Details

The predict method for unmarkedRanef objects generates the empirical Bayes posterior predictive distribution for functions of the random variables (latent abundance or occurrence).

In addition to the output object from ranef, you must also supply a custom function to argument func. The function must take as input a matrix with dimensions M x T, where M is the number of sites and T is the number of primary periods (T=1 for single-season models). The output of this function should be a vector or matrix containing the derived parameters of interest.

You may also manually set the number of draws from the posterior predictive distribution with argument nsims; the default is 100.

The output of predict will be a vector or array with one more dimension than the output of the function supplied func, corresponding to the number of draws requested nsims. For example, if func outputs a scalar, the output of predict will be a vector with length equal to nsims. If func outputs a 3x2 matrix, the output of predict will be an array with dimensions 3x2xnsims. See ranef for an example.

Alternatively, you can use the posteriorSamples function on the ranef output object to obtain the full posterior predictive distribution. This is useful if you are having trouble designing your custom function or if you want to obtain multiple different derived parameters from the same posterior predictive distribution.

Value

For most methods, a data.frame with four columns: the predicted values, standard errors, and lower and upper bounds. If appendData = TRUE covariate data are also in the output. For unmarkedRanef, an array is returned. See details.

unmarked documentation built on April 3, 2025, 5:30 p.m.