boral (version 2.0.3)

fitted.boral: Extract Model Fitted Values for an boral object

Description

lifecycle::badge("stable")

Calculated the fitted values based on the response or linear predictor scale, by using the posterior medians or means of the parameters.

Usage

# S3 method for boral
fitted(object, est = "median", include.ranef = TRUE, linear.predictor = FALSE, ...)

Value

A list containing ordinal.probs which is an array with dimensions (number of rows of the response matrix) x (number of columns of the response matrix) x (no. of levels) containing the predicted probabilities for ordinal columns, and out which is a matrix of the same dimension as the original response matrix containing the fitted values. For ordinal columns, the "fitted values" are defined as the level/class that had the highest fitted probability.

Arguments

object

An object of class "boral".

est

A choice of either the posterior median (est = "median") or posterior mean (est = "mean"), which are then treated as estimates and the fitted values are calculated from. Default is posterior median.

include.ranef

If response-specific random intercepts were included as part of the fitted model, then this determines whether the predicted random effects will be included in the fitted values. When set to TRUE, which is the default, then they are included (using either the posterior mean and posterior median predictor). When set to FALSE, they are not included. The former are sometimes called conditional fitted values, while the latter are sometimes called marginal fitted values.

linear.predictor

Determines the scale on which to return the fitted values. When set to TRUE, it returns the fitted values on the linear predictor scale. When set to FALSE, which is the defaul behavior, the fitted values are on the response scale. Note things are slightly more complicated for zero truncated distributions because, the log-link connects the mean of the untruncated distribution to the linear predictor. Therefore if linear.predictor = TRUE, then the linear predictor is returned. But if linear.predictor = FALSE, then actual mean value is returned.

...

Not used.

Author

tools:::Rd_package_author("boral")

Maintainer: tools:::Rd_package_maintainer("boral")

Details

This fitted values here are calculated based on a point estimate of the parameters, as determined by the argument est. A fully Bayesian approach would calculate the fitted values by averaging over the posterior distribution of the parameters i.e., ergodically average over the MCMC samples. For simplicity and speed though (to avoid generation of a large number of predicted values), this is not implemented.

See Also

plot.boral which uses the fitted values calculated from this function to construct plots for residual analysis, ds.residuals for calculating the Dunn-Smyth residuals for a fitted model.

Examples

if (FALSE) {
## NOTE: The values below MUST NOT be used in a real application;
## they are only used here to make the examples run quick!!!
example_mcmc_control <- list(n.burnin = 10, n.iteration = 100, 
     n.thin = 1)
     
testpath <- file.path(tempdir(), "jagsboralmodel.txt")


library(mvabund) ## Load a dataset from the mvabund package
data(spider)
y <- spider$abun

spiderfit_nb <- boral(y, family = "negative.binomial", lv.control = list(num.lv = 2),
     row.eff = "fixed", mcmc.control = example_mcmc_control, model.name = testpath)

fitted(spiderfit_nb)
}