Extract Summary Statistics from Stan Model Results — species_complex

This function extracts and summarizes posterior estimates from a fitted Stan model, organizing the results by taxonomic levels: genus, species complex, and species. It calculates means, variances, and confidence intervals, formats estimates with confidence intervals, and optionally includes all species and complexes from a compatibility repository. The output is a tidy data.frame suitable for further analysis or reporting.

Usage

species_complex_result(results, all = FALSE, output_dir = NULL)

Arguments

results: A list containing the Stan fit results and species metadata. Must include: - `fit`: The fitted Stan model object (class `stanfit`), - `species_complex`: A data frame linking species and complexes with indices.
all: Logical indicating whether to include all species and complexes from an external compatibility repository (default is TRUE).
output_dir: Optional character. Directory path to save the CSV. If NULL, the plot is not saved.

Value

A data.frame with summarized posterior statistics including: - `name`: Taxonomic unit name (genus, complex, or species), - `level`: Taxonomic level ("genus", "complex", or "species"), - `mean`: Formatted estimate - `variance`: Variance of the estimate, - `ci_lower`: Lower bound of the confidence interval, - `ci_upper`: Upper bound of the confidence interval, - additional metadata columns when `all = TRUE`.

Details

The function first extracts summary statistics from the Stan fit object, including means, standard deviations, and confidence intervals for parameters representing genus, complex, and species levels. It then maps these parameters to species and complex names using the `species_complex` data frame. Unlabelled species are handled according to their complex membership. When `all = TRUE`, missing species and complexes are supplemented based on a compatibility repository to ensure completeness.

Examples

if (FALSE) { # \dontrun{
# Assuming `stan_results` is a list with the required components:
summary_df <- extract_stan_summary(
  results = stan_results,
  all = TRUE
)
} # }