get_posterior: Extract posterior samples or summary of parameters from a...

In fukayak/occumb: Site Occupancy Modeling for Environmental DNA Metabarcoding

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"),
  output_dataframe = FALSE
)

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

Arguments

fit	An occumbFit object.
parameter	A string of parameter name. See Details for possible choices and corresponding parameters.
output_dataframe	If TRUE, results are returned in data frame format.

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 when output_dataframe = FALSE, 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

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

get_post_summary() returns, by default, 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.

When output_dataframe = TRUE, the results are returned in data frame format where the attributes obtained when output_dataframe = FALSE are incorporated into the table.

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)

fukayak/occumb documentation built on Jan. 20, 2025, 1:09 p.m.