get_posterior {occumb}

Extract posterior samples or summary of parameters from a model-fit object.

Description

get_post_samples() extracts posterior samples of the specified parameters from a model-fit object.

get_post_summary() extracts posterior summary of the specified parameters from a model-fit object.

Usage

get_post_samples(
  fit,
  parameter = c("z", "pi", "phi", "theta", "psi", "alpha", "beta", "gamma",
    "alpha_shared", "beta_shared", "gamma_shared", "Mu", "sigma", "rho")
)

get_post_summary(
  fit,
  parameter = c("z", "pi", "phi", "theta", "psi", "alpha", "beta", "gamma",
    "alpha_shared", "beta_shared", "gamma_shared", "Mu", "sigma", "rho")
)

Arguments

fit

An occumbFit object.

parameter

A string of parameter name. See Details for possible choices and corresponding parameters.

Details

The functions return posterior samples or a summary of one of the following parameters in the model, stored in the model-fit object fit:

z

Site occupancy status of species.

pi

Multinomial probabilities of species sequence read counts.

phi

Sequence relative dominance of species.

theta

Sequence capture probabilities of species.

psi

Site occupancy probabilities of species.

alpha

Species-specific effects on sequence relative dominance (phi).

beta

Species-specific effects on sequence capture probabilities (theta).

gamma

Species-specific effects on site occupancy probabilities (psi).

alpha_shared

Effects on sequence relative dominance (phi) common across species.

beta_shared

Effects on sequence capture probabilities (theta) that are common across species.

gamma_shared

Effects on site occupancy probabilities (psi) that are common across species.

Mu

Community-level averages of species-specific effects (alpha, beta, gamma).

sigma

Standard deviations of species-specific effects (alpha, beta, gamma).

rho

Correlation coefficients of the species-specific effects (alpha, beta, gamma).

See the package vignette for details of these parameters.

The parameter may have dimensions corresponding to species, sites, replicates, and effects (covariates) and the dimension and label attributes are added to the output object to inform these dimensions. If the sequence read count data y have species, site, or replicate names appended as the dimnames attribute (see Details in occumbData()), they are copied into the label attribute of the returned object.

Value

get_post_samples() returns a vector, matrix, or array of posterior samples for a selected parameter.

get_post_summary() returns a table (matrix) of the posterior summary of the selected parameters. The elements of the posterior summary are the same as those obtained with the jags() function in the jagsUI package: they include the mean, standard deviation, percentiles of posterior samples; the Rhat statistic; the effective sample size, n.eff; overlap0, which checks if 0 falls in the parameter's 95% credible interval; and the proportion of the posterior with the same sign as the mean, f.

The dimension and label attributes of the output object provide information regarding the dimensions of the parameter.

Examples

# Generate the smallest random dataset (2 species * 2 sites * 2 reps)
I <- 2 # Number of species
J <- 2 # Number of sites
K <- 2 # Number of replicates
y_named <- array(sample.int(I * J * K), dim = c(I, J, K))
dimnames(y_named) <- list(c("species 1", "species 2"),
                          c("site 1", "site 2"), NULL)
data_named <- occumbData(y = y_named)

# Fitting a null model
fit <- occumb(data = data_named, n.iter = 10100)

# Extract posterior samples
(post_sample_z <- get_post_samples(fit, "z"))
# Look dimensions of the parameter
attributes(post_sample_z)

# Extract posterior summary
(post_summary_z <- get_post_summary(fit, "z"))
# Look dimensions of the parameter
attributes(post_summary_z)