fitted_flocker {flocker}

Posterior predictive distributions for modeled probabilities

Description

Get expected values of the posterior predictive distribution for the modeled probabilities (occupancy, detection, colonization, extinction, autologistic).

Usage

fitted_flocker(
  flocker_fit,
  components = c("occ", "det", "col", "ex", "auto", "Omega"),
  new_data = NULL,
  unit_level = FALSE,
  summarise = FALSE,
  CI = c(0.05, 0.95),
  draw_ids = NULL,
  response = TRUE,
  re_formula = NULL,
  allow_new_levels = FALSE,
  sample_new_levels = "uncertainty"
)

Arguments

flocker_fit

A flocker_fit object.

components

a character vector specifying one or more of "occ", "det", "col", "ex", "auto", and "Omega" for which to obtain fitted values.

new_data

Optional new data at which to evaluate occupancy predictions. New data can be passed as a flocker_data object produced by make_flocker_data or as a dataframe with one row per desired prediction. If 'NULL' (the default) expected values are generated for the original data as formatted by make_flocker_data.

unit_level

Logical; defaults to FALSE. Relevant only when 'new_data' is not a dataframe (i.e. it is 'NULL' or a flocker_data object), and useful only for multiseason models with missing seasons. If FALSE, returns in the shape of the observation matrix/array with NAs for missing visits. If TRUE, returns in the shape of the first visit, and returns values for all units that are not part of a trailing block of never-visited units, including never-visited units that are part of series with subsequent visits.

summarise

if TRUE, return the expected value and upper and lower bound of the credible interval, otherwise return posterior draws.

CI

A vector of length 2 specifying the upper and lower bounds of the credible interval.

draw_ids

Vector of indices of the posterior draws to be used. If 'NULL' (the default) all draws are used in their native order.

response

Should results be returned on the response or logit scale? Defaults to 'TRUE', i.e. response scale. However, the autologistic parameter is not interpretable as a probability and is always returned on the logit scale regardless of the value of 'response'

re_formula

formula containing group-level effects to be considered in the prediction. If 'NULL' (default), include all group-level effects; if NA, include no group-level effects.

allow_new_levels

allow new levels for random effect terms in 'new_data'? Will error if set to 'FALSE' and new levels are provided in 'new_data'.

sample_new_levels

If new_data is provided and contains random effect levels not present in the original data, how should predictions be handled? Passed directly to 'brms::prepare_predictions', which see.

Details

The probabilities returned are conditional probabilities (e.g. detection conditional on occupancy, colonization conditional on previous non-occupancy, etc). These probabilities are not conditioned on the observed histories (e.g. the occupancy probability is not fixed to one at sites with a detection; it is estimated only based on the covariates).

Value

A list of sets of expected values (one per component). If 'new_data' is a dataframe, each element contains one row per row of 'new_data'. Otherwise, returns in the shape of the observation matrix/array used to format the flocker_data (but see 'unit_level' parameter for further details).

Examples

fitted_flocker(
  example_flocker_model_single, 
  summarise = TRUE
)