analyze_energy_budget: Analyze energy budget from FB4 results

In fb4package: 'Fish Bioenergetics 4.0' Model Implementation with High-Performance 'TMB' Backend

Analyze energy budget from FB4 results

Description

Analyzes energy budget components from FB4 simulation results. Calculates proportional allocation to different processes with uncertainty propagation when available.

Usage

analyze_energy_budget(result, individual_id = NULL, confidence_level = 0.95)

Arguments

result	FB4 result object
individual_id	Individual ID for hierarchical models (NULL for population/single individual)
confidence_level	Confidence level for intervals (default 0.95)

Value

A named list with four elements:

energy_components

The list returned by get_energy_budget_uncertainty, containing six component sub-lists each with estimate, se, ci_lower, and ci_upper.

proportions

Named list of proportional allocations (prop_respiration, prop_egestion, prop_excretion, prop_sda, prop_net), each a sub-list with estimate, se, ci_lower, and ci_upper. NULL when consumption energy is zero or unavailable.

summary_metrics

Named list with gross_growth_efficiency, metabolic_scope, and assimilation_efficiency sub-lists (each estimate + se). NULL when proportions are unavailable.

balance_check

Named list with consumption_energy, total_allocated, balance_error, and relative_error (all numeric) to verify mass-balance closure.

Plus the context scalars method, has_uncertainty, and individual_id.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
budget <- analyze_energy_budget(result)

fb4package documentation built on May 8, 2026, 1:07 a.m.