Package 'flocker'

A flocker_fit object.

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

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.

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.

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

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

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

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'

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 for random effect terms in 'new_data'? Will error if set to 'FALSE' and new levels are provided in 'new_data'.

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.

A brms-type model formula for occupancy. If provided, must begin with "~".

A brms-type model formula for detection. Must begin with "~". OR, a brmsformula object including formulas for all of the relevant distributional parameters in the desired model (det and at least one of occ, colo, ex, autologistic, and Omega). The $formula element of the brmsformula must be the detection formula, beginning with det ~. This latter option unadvisable except when necessary (e.g. when a nonlinear formula is desired), as input checking is less thorough.

data, generally the output of make_flocker_data().

additional data (e.g. a covariance matrix for a phylogenetic effect)

Must be NULL (the default) or one of "colex" or "autologistic". If NULL, data must be formatted for a single-season model. Otherwise, the data must be formatted for a multiseason model. If "colex", a colonization-extinction model will be fit, and 'f_col' and 'f_ex' must be specified. If "autologistic", an autologistic model will be fit, and 'f_col' and 'f_ex' must both be NULL.

A brms-type model formula for colonization in colonization-extinction dynamic models. If provided, must begin with "~".

A brms-type model formula for extinction probabilities in colonization-extinction dynamic models. If provided, must begin with "~".

Must be NULL unless the model is a dynamic (multiseason) model, in which case must be either "explicit" or "equilibrium". If "explicit", then 'f_occ' must be provided to model occupancy probabilities in the first timestep. If "equilibrium", then 'f_occ' must be 'NULL' and the initial occupancy probabilities are assumed to be the (possibly site-specific) equilibrium probabilities from the colonization- extinction dynamics.

Relevant only for autologistic models. A brms-type model formula for the autologistic offset parameter (theta). If provided, must begin with "~".

Logical. Must be TRUE if data are formatted for a data-augmented multi-species model, and FALSE otherwise.

NULL or positive integer. If integer, the number of threads to use per chain in within chain parallelization. Currently available only with single-season rep-constant models, and must be set to NULL otherwise.

additional arguments passed to brms::brm()

A brms-type model formula for occupancy. If provided, must begin with "~".

A brms-type model formula for detection. Must begin with "~". OR, a brmsformula object including formulas for all of the relevant distributional parameters in the desired model (det and at least one of occ, colo, ex, autologistic, and Omega). The $formula element of the brmsformula must be the detection formula, beginning with det ~. This latter option unadvisable except when necessary (e.g. when a nonlinear formula is desired), as input checking is less thorough.

data, generally the output of make_flocker_data().

additional data (e.g. a covariance matrix for a phylogenetic effect)

Must be NULL (the default) or one of "colex" or "autologistic". If NULL, data must be formatted for a single-season model. Otherwise, the data must be formatted for a multiseason model. If "colex", a colonization-extinction model will be fit, and 'f_col' and 'f_ex' must be specified. If "autologistic", an autologistic model will be fit, and 'f_col' and 'f_ex' must both be NULL.

A brms-type model formula for colonization in colonization-extinction dynamic models. If provided, must begin with "~".

A brms-type model formula for extinction probabilities in colonization-extinction dynamic models. If provided, must begin with "~".

Must be NULL unless the model is a dynamic (multiseason) model, in which case must be either "explicit" or "equilibrium". If "explicit", then 'f_occ' must be provided to model occupancy probabilities in the first timestep. If "equilibrium", then 'f_occ' must be 'NULL' and the initial occupancy probabilities are assumed to be the (possibly site-specific) equilibrium probabilities from the colonization- extinction dynamics.

Relevant only for autologistic models. A brms-type model formula for the autologistic offset parameter (theta). If provided, must begin with "~".

Logical. Must be TRUE if data are formatted for a data-augmented multi-species model, and FALSE otherwise.

NULL or positive integer. If integer, the number of threads to use per chain in within chain parallelization. Currently available only with single-season rep-constant models, and must be set to NULL otherwise.

additional arguments passed to brms::brm()

A brms-type model formula for occupancy. If provided, must begin with "~".

A brms-type model formula for detection. Must begin with "~". OR, a brmsformula object including formulas for all of the relevant distributional parameters in the desired model (det and at least one of occ, colo, ex, autologistic, and Omega). The $formula element of the brmsformula must be the detection formula, beginning with det ~. This latter option unadvisable except when necessary (e.g. when a nonlinear formula is desired), as input checking is less thorough.

data, generally the output of make_flocker_data().

additional data (e.g. a covariance matrix for a phylogenetic effect)

Must be NULL (the default) or one of "colex" or "autologistic". If NULL, data must be formatted for a single-season model. Otherwise, the data must be formatted for a multiseason model. If "colex", a colonization-extinction model will be fit, and 'f_col' and 'f_ex' must be specified. If "autologistic", an autologistic model will be fit, and 'f_col' and 'f_ex' must both be NULL.

A brms-type model formula for colonization in colonization-extinction dynamic models. If provided, must begin with "~".

A brms-type model formula for extinction probabilities in colonization-extinction dynamic models. If provided, must begin with "~".

Must be NULL unless the model is a dynamic (multiseason) model, in which case must be either "explicit" or "equilibrium". If "explicit", then 'f_occ' must be provided to model occupancy probabilities in the first timestep. If "equilibrium", then 'f_occ' must be 'NULL' and the initial occupancy probabilities are assumed to be the (possibly site-specific) equilibrium probabilities from the colonization- extinction dynamics.

Relevant only for autologistic models. A brms-type model formula for the autologistic offset parameter (theta). If provided, must begin with "~".

Logical. Must be TRUE if data are formatted for a data-augmented multi-species model, and FALSE otherwise.

NULL or positive integer. If integer, the number of threads to use per chain in within chain parallelization. Currently available only with single-season rep-constant models, and must be set to NULL otherwise.

additional arguments passed to brms::brm()

A brms-type model formula for occupancy. If provided, must begin with "~".

A brms-type model formula for detection. Must begin with "~". OR, a brmsformula object including formulas for all of the relevant distributional parameters in the desired model (det and at least one of occ, colo, ex, autologistic, and Omega). The $formula element of the brmsformula must be the detection formula, beginning with det ~. This latter option unadvisable except when necessary (e.g. when a nonlinear formula is desired), as input checking is less thorough.

data, generally the output of make_flocker_data().

additional data (e.g. a covariance matrix for a phylogenetic effect)

Must be NULL (the default) or one of "colex" or "autologistic". If NULL, data must be formatted for a single-season model. Otherwise, the data must be formatted for a multiseason model. If "colex", a colonization-extinction model will be fit, and 'f_col' and 'f_ex' must be specified. If "autologistic", an autologistic model will be fit, and 'f_col' and 'f_ex' must both be NULL.

A brms-type model formula for colonization in colonization-extinction dynamic models. If provided, must begin with "~".

A brms-type model formula for extinction probabilities in colonization-extinction dynamic models. If provided, must begin with "~".

Must be NULL unless the model is a dynamic (multiseason) model, in which case must be either "explicit" or "equilibrium". If "explicit", then 'f_occ' must be provided to model occupancy probabilities in the first timestep. If "equilibrium", then 'f_occ' must be 'NULL' and the initial occupancy probabilities are assumed to be the (possibly site-specific) equilibrium probabilities from the colonization- extinction dynamics.

Relevant only for autologistic models. A brms-type model formula for the autologistic offset parameter (theta). If provided, must begin with "~".

Logical. Must be TRUE if data are formatted for a data-augmented multi-species model, and FALSE otherwise.

NULL or positive integer. If integer, the number of threads to use per chain in within chain parallelization. Currently available only with single-season rep-constant models, and must be set to NULL otherwise.

additional arguments passed to brms::brm()

A flocker_fit object

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

Should the posterior distribution for Z directly condition on the observed detection history ('TRUE') or not ('FALSE')? For example, at sites with at least one detection, the true occupancy state conditioned on the history is one with absolute certainty. Without directly conditioning on the history, the occupancy state is controlled by the posterior distribution for the occupancy probability psi.

Should the return be posterior probabilities of occupancy (FALSE), or bernoulli samples from those probabilities (TRUE)

Optional new data at which to predict the Z matrix. Can be the output of 'make_flocker_data' or the 'unit_covs' input to 'make_flocker_data' provided that 'history_condition' is 'FALSE' and the occupancy model is a single-season, non-augmented model.

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

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.

real number or vector of reals

A flocker_fit object

the draw ids to compute log-likelihoods for. Defaults to using the full posterior.

real number or vector of reals

a list of flocker_fit objects.

An optional vector of names for the models.

specify the amount of thinning required. 1 or NULL results in no thinning, 2 retains every other value, 3 every third, etc.

a flocker_fit object or a list of flocker_fit objects

specify the amount of thinning required. 1 or NULL implies no thinning, 2 implies every other value, 3 every third, etc.

If type = "single", an I x J matrix-like object where closure is assumed across rows and columns are repeated sampling events. If type = "multi", an I x J x K array where rows are sites or species-sites, columns are repeated sampling events, and slices along the third dimension are seasons. Allowable values are 1 (detection), 0 (no detection), and NA (no sampling event). If type = "augmented", an L x J x K array where rows L are sites, columns J are repeat sampling events, and slices K are species. The data must be packed so that, for a given unit (site, site-species, site-timestep, site-species-timestep) all realized visits come before any missing visits (NAs are trailing within their rows).

If type = "single" a dataframe of covariates for each closure-unit that are constant across repeated sampling events within units. If type = "multi", a list of such dataframes, one per timestep. All dataframes must have identical column names and types, and all dataframes must have I rows. If type = "augmented", a dataframe of covariates for each site that are constant across repeated sampling events within sites (no dependence on species is allowed).

If type = "single", a named list of I x J matrices, each one corresponding to a covariate that varies across repeated sampling events within closure-units. If type = "multi", a named list of I x J x K arrays, each one corresponding to a covariate that varies across repeated sampling events within closure-units. If type = "augmented", a named list of L x J matrices, each one corresponding to a covariate that varies across repeated sampling events within sites (no dependence on species is allowed).

The type of occupancy model desired. Options are: "single" for a single_season model, "multi" for a multi-season (dynamic) model, or "augmented" for a single-season multi-species model with data-augmentation for never-observed pseudospecies.

Number of pseudo-species to augment. Only applicable if type = "augmented".

Hide progress bars and informational messages?

An I x J x K array where rows I are sites, columns J are repeat sampling events, and slices K are species. Allowable values are 1 (detection), 0 (no detection), and NA (no sampling event). The data must be formatted so that all NAs are trailing within their rows.

Number of pseudospecies to augment

A dataframe of covariates for each site that are constant across repeated sampling events.

A named list of I x J matrices, each one corresponding to a covariate that varies across repeated sampling events within sites

Hide progress bars and informational messages?

An I x J x K array where closure is assumed across rows, columns are repeated sampling events, and slices along the third dimension are seasons. Allowable values are 1 (detection), 0 (no detection), and NA (no sampling event). The data must be formatted so that all NAs are trailing within their rows across repeat visits, but not necessarily across seasons.

A list of dataframes (one per season) of covariates for each closure-unit that are constant across repeated sampling events within units. All dataframes must have identical column names and types, and all dataframes must have I rows.

A named list of I x J x K arrays, each one corresponding to a covariate that varies across repeated sampling events within closure-units

Hide progress bars and informational messages?

An I x J matrix-like object where closure is assumed across rows and columns are repeated sampling events. Allowable values are 1 (detection), 0 (no detection), and NA (no sampling event).

A dataframe of covariates for each unit that are constant across repeated sampling events within closure-units.

A named list of I x J matrices, each one corresponding to a covariate that varies across repeated sampling events within closure-units

Hide progress bars and informational messages?

A 'flocker_fit' object

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

Logical indicator of whether to directly condition the posterior for the occupancy state on the observed detection histories. For example, at sites with at least one detection, the true occupancy state conditioned on the history is one with absolute certainty. Without directly conditioning on the history, the occupancy state is controlled exclusively by the posterior distribution for the occupancy probability psi.

Optional new data at which to predict. If 'NULL', predictions are given at the data points used for model fitting. Otherwise, must be a flocker_data object produced by 'make_flocker_data'.

When 'new_data' is not provided, should random effect levels be drawn from their posteriors ('FALSE', the default) or re-sampled from their fitted hyperparameters ('TRUE'). The latter can be useful for mixed predictive checking. Note that setting to TRUE is not available for grouping terms involved in phylogenetic random effects or other random effects with specified covariance structures.

Should new_data be allowed to contain new levels for random effects?

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.

number of replicate visits to simulate per closure unit

number of points to simulate. The number of units for single- season models will be 'n_pt*n_sp'. The number of units for multi-season models will be 'n_pt*n_sp*n_season'.

number of levels to include in random effect. For compatibility with multispecies models where the random effect represents species, the data get expanded such that there's a row (closure-unit) for each combination of sampling point and effect level (i.e. species)

Number of seasons desired. 1 yields data for a single-season model; all other positive integers yield data for multiseason models.

if n_season is NULL, must be NULL. Otherwise, one of "colex" or "autologistic".

if n_season is NULL, must be NULL. Otherwise, one of "explicit" or "equilibrium".

logical. If 'TRUE' data will be formatted for an augmented model, which requires that 'n_season == 1'. All never-observed species will be trimmed out of the data, and the default parameters will be modified to increase random effect variances for the detection and occupancy, intercepts and to decrease random effect variances for detection slopes, thus encouraging the existence of never-observed species. Furthermore, the data will be simulated without any covariate influence on occupancy.

logical: create data with unit covariates only (TRUE) or data that includes event covariates (FALSE)

a named list containing of parameter values to use in simulation. Any required parameters whose names are not in this list will be assigned their default values. To see the parameter names and structures required, run with 'params = NULL' (the default) and examine the '$params' element of the output.

a dataframe of covariate values to use in simulation, or NULL to simulate values. To see the covariate names and structures required, run with 'covariates = NULL' (the default) and examine the '$covariates' element of the output.

random seed. NULL uses (and updates) the existing RNG state. Other values do not update the global RNG state.

logical: create data with variable (TRUE) or constant (FALSE) numbers of visits per unit. If TRUE, approximately half of units will be missing approximately half of 'n_rep' visits. Intended primarily for development purposes (bug-checking models with missing data).

logical; relevant only if n_season is greater than 1. create data with variable (TRUE) or constant (FALSE) numbers of seasons per series (TRUE). If TRUE, approximately half of series will be missing their even-numbered seasons.