Analyze population variation in hierarchical models — analyze_population

Analyzes the magnitude and sources of variation in hierarchical models. Decomposes total variation into between-individual and within-individual components.

Usage

analyze_population_variation(result, include_covariates = TRUE)

Arguments

result: FB4 result object from hierarchical method
include_covariates: Include covariate effects in analysis

Value

A named list with at minimum three elements:

n_individuals: Integer. Number of individuals in the analysis.
population_parameters: Named list with sub-lists mu_p, sigma_p, and sigma_obs, each containing estimate, se, ci_lower, and ci_upper.
variance_decomposition: Named list (present when total variance is positive) with between_individual_variance, within_individual_variance, total_variance, between_individual_prop, within_individual_prop, and intraclass_correlation.

When individual outcome data are available, outcome_variation is appended (sub-lists consumption and optionally growth, each with variance, cv, and range). When covariate effects are present and include_covariates = TRUE, covariate_effects is also appended. Stops with an error if result was not produced by the hierarchical method.

Examples

# \donttest{
# Population variation requires a hierarchical run; shown here for illustration
# result <- run_fb4(bio, strategy = "hierarchical", ...)
# pv <- analyze_population_variation(result)
# }