Package {fb4package}

Fish Bioenergetics 4.0 Package

Description

An R package implementation of Fish Bioenergetics 4.0 (FB4), a widely used approach for modelling energy allocation in fish. The model partitions consumed energy into three fundamental components: metabolism (respiration + activity + specific dynamic action), waste losses (egestion + excretion), and growth (somatic + gonadal). The package provides multiple estimation strategies (binary search, direct, bootstrap, maximum likelihood) and an optional C++ backend via TMB for high-performance MLE.

Details

The bioenergetics energy balance implemented here follows Kitchell et al. (1977):

C = R + A + \mathrm{SDA} + F + U + G

where C = consumption, R = standard respiration, A = active metabolism, \mathrm{SDA} = specific dynamic action, F = egestion, U = excretion, and G = growth (somatic + gonadal).

Consumption is modelled as C = C_{\max} \cdot p \cdot F(T), where C_{\max} = CA \cdot W^{CB} (Hartman and Hayward 2007) and F(T) is one of four temperature-dependence functions (CEQ 1–4; Kitchell et al. 1977; Thornton and Lessem 1978).

Respiration is modelled as R = RA \cdot W^{RB} \cdot F(T) \cdot \mathrm{ACT}, with F(T) following Kitchell et al. (1977) or a simple Q10 exponential (REQ 1–2).

Egestion and excretion follow Elliott (1976) or Stewart et al. (1983) (EGEQ/EXEQ 1–4).

Predator energy density can be modelled as weight-dependent or constant (PREDEDEQ 1–2; Hanson et al. 1997).

This package extends Fish Bioenergetics 4.0 (Deslauriers et al. 2017), itself an R-based re-implementation of Fish Bioenergetics 3.0 (Hanson et al. 1997) and its predecessors (Hewett and Johnson 1987, 1992).

Author(s)

Maintainer: Hans Ttito kvttitos@gmail.com

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI. WISCU-T-97-001.

Kitchell, J.F., Stewart, D.J. and Weininger, D. (1977). Applications of a bioenergetics model to yellow perch (Perca flavescens) and walleye (Stizostedion vitreum vitreum). Journal of the Fisheries Research Board of Canada, 34(10), 1922–1935. doi:10.1139/f77-258

Thornton, K.W. and Lessem, A.S. (1978). A temperature algorithm for modifying biological rates. Transactions of the American Fisheries Society, 107(2), 284–287.

Elliott, J.M. (1976). Energy losses in the waste products of brown trout (Salmo trutta L.). Journal of Animal Ecology, 45(2), 561–580.

Stewart, D.J., Weininger, D., Rottiers, D.V. and Edsall, T.A. (1983). An energetics model for lake trout, Salvelinus namaycush: application to the Lake Michigan population. Canadian Journal of Fisheries and Aquatic Sciences, 40(6), 681–698.

Hartman, K.J. and Hayward, R.S. (2007). Bioenergetics. In C.S. Guy and M.L. Brown (eds.), Analysis and Interpretation of Freshwater Fisheries Data. American Fisheries Society, Bethesda, MD.

Hewett, S.W. and Johnson, B.L. (1987). A Generalized Bioenergetics Model of Fish Growth for Microcomputers. University of Wisconsin Sea Grant Institute, Madison, WI.

Hewett, S.W. and Johnson, B.L. (1992). Fish Bioenergetics 2.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Winberg, G.G. (1956). Rate of metabolism and food requirements of fishes. Fisheries Research Board of Canada Translation Series No. 194.

Breck, J.E. (2014). Body composition in fishes: body size matters. Aquaculture, 433, 40–49. doi:10.1016/j.aquaculture.2014.05.049

Arnot, J.A. and Gobas, F.A.P.C. (2004). A food web bioaccumulation model for organic chemicals in aquatic ecosystems. Environmental Toxicology and Chemistry, 23(10), 2343–2355. doi:10.1897/03-438

See Also

Bioenergetic, run_fb4, fish4_parameters

Constructor for Bioenergetic Objects

Description

Creates a Bioenergetic class object that encapsulates all components of the fish bioenergetic model for streamlined simulation management.

Usage

Bioenergetic(
  species_params,
  species_info = NULL,
  environmental_data = NULL,
  diet_data = NULL,
  reproduction_data = NULL,
  model_options = list(),
  simulation_settings = list()
)

Arguments

Details

The Bioenergetic object serves as a comprehensive container for all bioenergetic model components.

Required Components:

species_params

Parameter sets for consumption, respiration, etc.

species_info

Species identification with scientific_name or common_name

Optional Components:

environmental_data

Temperature and other environmental variables

diet_data

Diet composition and prey energy densities

model_options

Sub-model toggles and advanced settings

simulation_settings

Initial conditions and duration

Value

An object of class "Bioenergetic": a named list with eight elements: species_info, species_params, environmental_data, diet_data, reproduction_data, model_options, simulation_settings, and fitted (logical, FALSE until a simulation is run). A results element is appended by set_environment, set_diet, and run_fb4 when they reset or populate the object.

Examples

# Create species parameters
params <- list(
  consumption = list(CEQ = 2, CA = 0.303, CB = -0.275, CQ = 3, CTO = 15, CTM = 25),
  respiration = list(REQ = 1, RA = 0.0548, RB = -0.299, RQ = 2, RTO = 5, RTM = 25)
)

# Create species info
species_info <- list(
  scientific_name = "Salmo salar",
  common_name = "Atlantic salmon",
  life_stage = "juvenile"
)

# Create bioenergetic object
bio_obj <- Bioenergetic(
  species_params = params,
  species_info = species_info,
  simulation_settings = list(initial_weight = 10, duration = 365)
)

Equation requirements for all FB4 components

Description

Equation requirements for all FB4 components

Usage

EQUATION_REQUIREMENTS

Format

An object of class list of length 5.

FB4 TMB Shared Functions

Description

Internal helper functions shared by the TMB-based MLE and hierarchical fitting strategies. Covers TMB objective validation (validate_tmb_objective), DLL availability checks (check_tmb_compilation), robust multi-start optimization (run_robust_optimization), parameter extraction from sdreport summaries (sdr_pull_est, sdr_pull_se, sdr_pull_vec, sdr_assign_scalars), and result assembly for basic and hierarchical models (extract_tmb_results).

Value

No return value; this page documents shared TMB backend functions. See individual function documentation for return values.

References

Kristensen, K., Nielsen, A., Berg, C.W., Skaug, H. and Bell, B.M. (2016). TMB: Automatic differentiation and Laplace approximation. Journal of Statistical Software, 70(5), 1–21. doi:10.18637/jss.v070.i05

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

FB4 Strategy Interface

Description

Defines the common interface that all FB4 execution strategies must implement. This ensures consistent behavior across different fitting methods while allowing for method-specific optimizations.

Usage

FB4Strategy

Format

An object of class list of length 3.

Details

All strategies must implement: - execute(execution_plan): Main execution logic - validate_plan(execution_plan): Strategy-specific validation - get_strategy_info(): Metadata about the strategy

Accumulate multiple validation results

Description

Combines multiple validation results into a single result, aggregating errors, warnings, and info messages.

Usage

accumulate_validations(..., level = "combined")

Arguments

Value

An object of class fb4_validation (see validation_result) representing the combined state of all inputs. valid is TRUE only if all supplied results are valid. errors and warnings are the concatenation of those fields across all inputs.

Examples

r1 <- validation_result(valid = TRUE)
r2 <- validation_result(valid = FALSE, errors = "value out of range")
accumulate_validations(r1, r2)

Add Confidence Bands to Plot

Description

Adds shaded confidence intervals to existing plots.

Usage

add_confidence_bands(x, lower, upper, color = "red", alpha = 0.2)

Arguments

Value

NULL (modifies current plot)

Add Standard Plot Annotations

Description

Adds common plot elements like grid, reference lines, and statistics text.

Usage

add_plot_annotations(
  add_grid = TRUE,
  reference_lines = NULL,
  stats_text = NULL,
  stats_position = "topright"
)

Arguments

Value

NULL (modifies current plot)

Add standard strategy metadata to results

Description

Adds consistent metadata structure to strategy results. Eliminates metadata creation duplication.

Usage

add_strategy_metadata(result_list, strategy_info, execution_plan)

Arguments

Value

Updated result list with strategy metadata

Core Analysis Functions for FB4 Results

Description

Core functions for extracting and accessing results from FB4 simulations. These functions provide a unified interface to access results regardless of the fitting method used ("direct", "optim", "binary_search", "mle", "bootstrap", "hierarchical"). Exported functions include is.fb4_result, get_consumption_uncertainty, get_efficiency_uncertainty, get_individual_results, get_population_results, and get_energy_budget_uncertainty.

Value

No return value; this page documents the core analysis functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Basic Analysis and Extraction Functions for FB4 Results

Description

Functions for basic analysis and extraction of FB4 simulation results. These functions build on the core extraction functions to provide meaningful biological interpretations and statistical summaries. Exported functions include analyze_growth_patterns, analyze_energy_budget, analyze_feeding_performance, and create_result_summary.

Value

No return value; this page documents the result extraction and summary functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Nutritional Analysis Functions for FB4 Results

Description

Specialized functions for nutritional analysis of FB4 simulation results. Includes N:P ratio analysis (calculate_np_ratios, compare_with_redfield), nutrient retention efficiency calculations (calculate_nutrient_efficiencies), stoichiometric balance assessment (calculate_stoichiometric_balance), body composition analysis (analyze_composition_by_size, analyze_composition_changes), diet quality assessment (assess_diet_quality), and an integrated wrapper (comprehensive_nutritional_analysis).

Value

No return value; this page documents the nutritional analysis functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Sensitivity and Comparative Analysis Functions for FB4 Results

Description

Functions for sensitivity analysis, comparative studies, and population-level analysis of FB4 simulation results. Includes individual comparisons (compare_individuals), population variation decomposition (analyze_population_variation), temperature-feeding sensitivity analysis (analyze_growth_temperature_sensitivity), and multi-scenario comparisons (compare_scenarios).

Value

No return value; this page documents the sensitivity analysis functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Analyze body composition by size range

Description

Analyzes body composition across a range of fish sizes to understand allometric relationships and size-dependent changes.

Usage

analyze_composition_by_size(
  weight_range = c(1, 500),
  n_points = 50,
  processed_composition_params
)

Arguments

Value

A data.frame with n_points rows and ten columns: Weight (g), Water_g, Protein_g, Ash_g, Fat_g (all in g), Water_fraction, Protein_fraction, Ash_fraction, Fat_fraction (dimensionless fractions of total wet weight), and Energy_density (J/g wet weight).

Examples

comp_params <- process_composition_params(list())
comp_analysis <- analyze_composition_by_size(c(1, 500), 20, comp_params)
plot(comp_analysis$Weight, comp_analysis$Energy_density)

Analyze composition changes with growth

Description

Analyzes how body composition changes as fish grow during a simulation. Useful for understanding ontogenetic changes in energy density and macronutrient allocation.

Usage

analyze_composition_changes(result, processed_composition_params)

Arguments

Value

A data.frame with one row per simulation day and thirteen columns: Weight (g), Water_g, Protein_g, Ash_g, Fat_g (g), Water_fraction, Protein_fraction, Ash_fraction, Fat_fraction (dimensionless), Energy_density (J/g), Day (integer), Energy_density_change (J/g/day; NA on day 1), Fat_fraction_change, and Protein_fraction_change (change per day; NA on day 1). Stops with an error if result has no daily_output.

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)
comp_params <- process_composition_params(list())
df <- analyze_composition_changes(result, comp_params)

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

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)

Analyze feeding performance from FB4 results

Description

Analyzes feeding-related metrics including consumption rates, feeding efficiency, and p_value estimates with uncertainty.

Usage

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

Arguments

Value

A named list with at minimum method (character), has_uncertainty (logical), and individual_id. Additional elements present when the relevant data are available:

total_consumption

The list returned by get_consumption_uncertainty (estimate, se, ci_lower, ci_upper, plus context scalars).

daily_consumption

Sub-list (estimate, se, ci_lower, ci_upper) for the daily consumption rate (g/day).

specific_consumption

Sub-list (same four slots) for the specific consumption rate (g consumption / g fish / day).

p_value

Structure depends on method: for hierarchical it contains population_mean, population_se, population_sd, and n_individuals; for single-individual methods it contains estimate, se, ci_lower, and ci_upper.

feeding_efficiency

Sub-list (estimate, se, ci_lower, ci_upper) for the ratio of total growth to total consumption (dimensionless).

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)
feeding <- analyze_feeding_performance(result)

Analyze growth patterns from FB4 results

Description

Extracts and analyzes growth patterns from FB4 simulation results. Calculates growth rates, efficiency metrics, and provides uncertainty estimates when available.

Usage

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

Arguments

Value

A named list with at minimum method (character), has_uncertainty (logical), individual_id, and initial_weight (numeric, g). The following growth metrics are included as sub-lists each with estimate, se, ci_lower, and ci_upper: final_weight (g), total_growth (g), and relative_growth (%). When simulation duration is available, daily_growth_rate (g/day) and specific_growth_rate (%/day) are appended. For fitted methods a p_value sub-list (estimate, se) is also included; for hierarchical population-level calls, n_individuals (integer) is added.

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)
growth <- analyze_growth_patterns(result)

Analyze growth rate sensitivity to temperature and feeding levels

Description

Analyzes how growth rates respond to different temperature and feeding level combinations. Uses p-values (proportion of maximum consumption capacity) to simulate feeding scenarios from survival levels (p ~0.2) to maximum capacity (p = 1.0). Parallelized for efficiency.

Usage

analyze_growth_temperature_sensitivity(
  bio_obj,
  temperatures = seq(8, 18, by = 2),
  p_values = seq(0.3, 1, by = 0.1),
  simulation_days = 365,
  oxycal = 13560,
  parallel = FALSE,
  n_cores = NULL,
  verbose = TRUE
)

Arguments

Value

A data frame with one row per temperature-p_value combination and columns:

temperature

Temperature tested (°C).

p_value

Feeding level (proportion of Cmax) tested.

growth_rate

Specific growth rate (percent per day).

final_weight

Predicted final weight (g).

total_consumption

Total consumption over the simulation period (g).

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
results <- analyze_growth_temperature_sensitivity(
  bio,
  temperatures     = c(2, 14),
  p_values         = c(0.4, 0.7),
  simulation_days  = 30,
  verbose          = FALSE
)

Analyze population variation in hierarchical models

Description

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

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

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

Assess nutritional quality of diet

Description

Assesses the nutritional quality of the diet based on energy density, macronutrient composition, and digestibility of prey items.

Usage

assess_diet_quality(diet_data, prey_energies, prey_digestibility = NULL)

Arguments

Value

A named list whose elements depend on whether the diet is time-varying or static. Always present: mean_energy_density (numeric, J/g), energy_density_sd (numeric), and energy_density_range (numeric vector of length 2). For time-varying diets, daily_energy_density (numeric vector) is also included. When prey_digestibility is supplied, the list additionally contains mean_digestibility, digestibility_sd, and (for time-varying diets) daily_digestibility. A diversity sub-list with mean_shannon and shannon_sd (and daily_shannon for time-varying diets) is always appended.

Examples

diet  <- list(proportions = data.frame(Day = 1:5,
                                       Prey1 = c(0.6, 0.6, 0.7, 0.5, 0.5),
                                       Prey2 = c(0.4, 0.4, 0.3, 0.5, 0.5)))
prey_e <- data.frame(Day = 1:5, Prey1 = 5000, Prey2 = 4500)
assess_diet_quality(diet, prey_e)

Fill energy budget components from a named source list

Description

Internal helper that populates the estimate and se slots of several energy components inside a budget result list. Avoids repeating the same assignment pattern across population, individual, and TMB branches of get_energy_budget_uncertainty().

Usage

assign_energy_components(budget, src, mapping, idx = NULL)

Arguments

Value

The updated budget list.

Basic Validation Functions for FB4

Description

Basic validation and utility functions built on top of the core validators in core-validators. They cover four common needs: scalar numeric validation (check_numeric_value), fundamental model-parameter feasibility (validate_basic_params), a safe fallback empty-composition constructor (create_empty_composition), and time-series structural checks (validate_time_series_data).

Value

No return value; this page documents the basic validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Binary search for optimal p_value

Description

Pure binary search algorithm for finding the p_value that achieves a target metric (final weight or total consumption).

Usage

binary_search_p_value(
  target_value,
  fit_type,
  lower_bound,
  upper_bound,
  simulation_function,
  tolerance = 0.001,
  max_iterations = 25
)

Arguments

Value

List with fitted p_value and convergence information

S3 Classes for FB4 Bioenergetic Model

Description

S3 class system for the Fish Bioenergetics 4.0 model, providing structured data containers and configuration methods for bioenergetic simulations. The central class "Bioenergetic" is created by Bioenergetic and configured via set_environment, set_diet, and set_simulation_settings. Utility functions is.Bioenergetic, get_parameter_value, and set_parameter_value support inspection and modification of the object.

Value

No return value; this page documents the S3 class definitions for the bioenergetic model. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Methods for FB4 Bioenergetic Model

Description

S3 print and summary methods for the two main classes of the FB4 package: "Bioenergetic" (the model configuration object) and "fb4_result" (the simulation output). print methods produce a concise one-screen overview; summary methods extend that with detailed per-method diagnostics (optimisation convergence, MLE statistics, bootstrap percentiles, or hierarchical population parameters).

Value

No return value; this page documents the S3 methods for bioenergetic objects. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Body Composition Functions for FB4 Model

Description

Functions for estimating and updating fish body composition (water, protein, ash, fat) and energy density from total wet weight. Composition is estimated via the allometric regressions of Breck (2014):

\log_{10}(\text{Component}) = \alpha + \beta \cdot \log_{10}(H_2O)

Fat is obtained by subtraction and bounded to biologically plausible limits. Energy density is computed as a weighted sum of fat and protein energy contents (J/g).

Value

No return value; this page documents the body composition functions module. See individual function documentation for return values.

References

Breck, J.E. (2014). Body composition in fishes: body size matters. Aquaculture, 433, 40–49. doi:10.1016/j.aquaculture.2014.05.049

Bootstrap estimation of p_values with optional parallel processing

Description

Estimates population p_value and consumption using bootstrap resampling of final weights. Parallel execution is supported via the future / furrr ecosystem when parallel = TRUE.

Each iteration delegates to bootstrap_single_iteration so that the sequential and parallel code paths share a single implementation.

Usage

bootstrap_p_values(
  processed_simulation_data,
  n_bootstrap = 1000,
  oxycal = 13560,
  sample_size = NULL,
  parallel = FALSE,
  n_cores = NULL,
  upper_p = 1,
  verbose = FALSE,
  store_predicted_weights = TRUE
)

Arguments

Value

Named list with:

p_values

Valid p_value estimates (NAs removed)

consumption_estimates

Valid consumption estimates

predicted_weights

Valid predicted weights, or NULL

success_rate, n_bootstrap, successful_iterations

Diagnostics

parallel_used, n_cores_used

Execution metadata

See Also

bootstrap_single_iteration, fit_fb4_bootstrap

Execute a single bootstrap iteration

Description

Internal helper: resamples weights, finds the p_value that achieves the resampled mean weight via optim_search_p_value, then extracts consumption and (optionally) the predicted final weight.

Extracted to eliminate code duplication between the sequential and parallel execution paths of bootstrap_p_values.

Usage

bootstrap_single_iteration(
  final_weights,
  n_sample,
  simulation_function,
  processed_simulation_data,
  oxycal,
  store_predicted_weights,
  upper_p = 1
)

Arguments

Value

Named list with fields p_estimate, consumption_estimate, predicted_weight, mean_fin, and success (logical).

Build a body-composition data frame from a list of composition results

Description

Internal helper shared by analyze_composition_by_size() and analyze_composition_changes(). Converts a list of calculate_body_composition() outputs into a tidy data frame, avoiding duplication of the identical sapply + data.frame block.

Usage

build_composition_df(compositions, weights)

Arguments

Value

Data frame with columns Weight, Water_g, Protein_g, Ash_g, Fat_g, and the corresponding *_fraction and Energy_density columns.

Build FB4 result object

Description

Unified result builder that creates a single fb4_result class with method-specific data embedded. Eliminates the complexity of multiple result classes while maintaining all functionality.

Usage

build_fb4_result_unified(raw_results, execution_plan, elapsed_time)

Arguments

Value

fb4_result object with method-specific data

Build individual-level uncertainty list for hierarchical results

Description

Extracts per-individual _est / _se vectors reported by the hierarchical TMB backend. Called by create_method_specific_data when method == "hierarchical".

Usage

build_individual_uncertainty(raw_results)

Arguments

Value

Named list of per-individual estimate/SE vectors

Build population-level uncertainty list for hierarchical results

Description

Extracts population-mean _est / _se scalars reported by the hierarchical TMB backend. Called by create_method_specific_data when method == "hierarchical".

Usage

build_population_uncertainty(raw_results)

Arguments

Value

Named list of population-mean estimate/SE scalars

Build TMB uncertainty list for MLE results

Description

Extracts all _est / _se pairs reported by the TMB backend into a single named list. Called by create_method_specific_data when method == "mle" and backend == "tmb".

Usage

build_tmb_uncertainty(raw_results)

Arguments

Value

Named list of estimate/SE pairs for core, energy, efficiency, proportion, and energy-density variables

Calculate activity factor for respiration (Mid-level)

Description

Calculates activity factor based on respiration equation with support for both simple and complex activity calculations

Usage

calculate_activity_factor_respiration(
  weight,
  temperature,
  processed_respiration_params
)

Arguments

Value

Activity factor

Calculate complete body composition (Mid-level - Main function)

Description

Main function that calculates all body composition components and energy density from weight and processed parameters

Usage

calculate_body_composition(weight, processed_composition_params)

Arguments

Value

A named list with 13 elements describing the body composition:

total_weight

Numeric. Total wet weight (g), equal to weight.

water_g

Numeric. Water content (g).

protein_g

Numeric. Protein content (g), estimated from water via Breck (2014) regression.

ash_g

Numeric. Ash content (g), estimated from water via Breck (2014) regression.

fat_g

Numeric. Fat content (g), calculated by subtraction and bounded to [0, max_fat_fraction * weight].

water_fraction

Numeric. Water as a fraction of total weight.

protein_fraction

Numeric. Protein as a fraction of total weight.

ash_fraction

Numeric. Ash as a fraction of total weight.

fat_fraction

Numeric. Fat as a fraction of total weight.

energy_density

Numeric. Energy density (J/g wet weight).

total_energy

Numeric. Total body energy (J).

total_fraction

Numeric. Sum of all four fractions; should be close to 1.

balanced

Logical. TRUE if total_fraction is within 0.05 of 1.

Returns create_empty_composition() when weight <= 0.

Examples

params <- list(water_fraction = 0.72, fat_energy = 36450,
               protein_energy = 17990, max_fat_fraction = 0.30)
calculate_body_composition(weight = 100,
                           processed_composition_params = params)

Calculate combined daily survival (Low-level)

Description

Calculates survival considering multiple mortality sources

Usage

calculate_combined_survival(mortality_rates, method = "independent")

Arguments

Value

Combined survival rate

Estimate composition from water using Breck (2014) regression (Low-level)

Description

Estimates grams of component based on water content using Breck regression

Usage

calculate_component_from_water(water_content, component_type)

Arguments

Value

Component content (g)

References

Breck, J.E. 2014. Body composition in fishes: body size matters. Aquaculture 433:40-49.

Confidence interval from estimate and standard error

Description

Computes a symmetric confidence interval given a point estimate and its standard error. Returns NA bounds when either input is NA.

Usage

calculate_confidence_intervals(
  estimate,
  se,
  confidence_level = 0.95,
  method = "normal"
)

Arguments

Value

Named list with ci_lower, ci_upper, method, and confidence_level

Examples

calculate_confidence_intervals(0.5, 0.05)
calculate_confidence_intervals(0.5, 0.05, confidence_level = 0.99)
calculate_confidence_intervals(NA, 0.05)

Calculate daily consumption (Mid-level - Main function)

Description

Main consumption calculation function called from simulation loop

Usage

calculate_consumption(
  temperature,
  weight,
  p_value,
  processed_consumption_params,
  method = "rate"
)

Arguments

Value

A non-negative numeric scalar giving the daily specific consumption rate in g prey per g fish per day. Returns 0 when the temperature-dependence factor is zero (e.g. temperature \ge CTM in equation 2). The value depends on method: "rate" (default) scales by p_value (C_{\max} \cdot p \cdot F(T)); "maximum" and "specific" return the unscaled value (C_{\max} \cdot F(T)).

Examples

# CEQ 1: simple exponential temperature dependence
params <- list(CEQ = 1, CA = 0.303, CB = -0.275, CQ = 0.06)
calculate_consumption(temperature = 15, weight = 100, p_value = 0.5,
                      processed_consumption_params = params)

Calculate additional parameters for consumption equation 2 (Mid-level)

Description

Calculates derived parameters needed for temperature equation 2

Usage

calculate_consumption_params_eq2(CQ, CTM, CTO, warn = TRUE)

Arguments

Value

List with CY, CZ, CX

Calculate additional parameters for consumption equation 3 (Mid-level)

Description

Calculates derived parameters needed for temperature equation 3

Usage

calculate_consumption_params_eq3(CTO, CQ, CTL, CTM, CK1, CK4)

Arguments

Value

List with CG1, CG2

Calculate contaminant accumulation (Mid-level - Main function)

Description

Calculates daily contaminant dynamics (uptake, elimination, body burden) for a fish using one of three bioaccumulation models (CONTEQ 1-3).

Usage

calculate_contaminant_accumulation(
  respiration_o2,
  consumption,
  weight,
  temperature,
  current_concentration,
  processed_contaminant_params
)

Arguments

Value

A named list with at least six elements (all numeric scalars unless noted):

clearance

Daily elimination of contaminant (ug/day).

uptake

Total daily uptake from food (ug/day); for CONTEQ 3 this is the sum of water and food uptake.

new_burden

Body burden at end of day (ug); floored at 0.

new_concentration

Whole-body concentration (ug/g wet weight); floored at 0.

weight

Fish weight (g), as supplied.

model_used

Integer. CONTEQ equation used (1, 2, or 3).

CONTEQ 3 (Arnot & Gobas 2004) appends two additional elements: uptake_water (ug/day from water) and uptake_food (ug/day from food).

Experimental

Contaminant modelling is an **experimental feature** under active development. This function can be called directly to compute daily bioaccumulation for a single time step, but it is **not yet integrated** into the main 'run_fb4()' simulation loop. Full integration (automatic contaminant tracking across all simulation days, inclusion in 'fb4_result' objects, and TMB backend support) is planned for a future release. The API may change.

Examples

# CONTEQ 1: food uptake only, no elimination
params <- list(
  CONTEQ = 1,
  prey_concentrations = c(0.05, 0.08),
  transfer_efficiency = c(0.8, 0.8)
)
calculate_contaminant_accumulation(
  respiration_o2 = 0.02, consumption = c(2.0, 1.0),
  weight = 100, temperature = 15,
  current_concentration = 0.1,
  processed_contaminant_params = params
)

Calculate daily consumption with multiple methods (Low-level)

Description

Calculates daily consumption using different input methods (p_value, ration, etc.) and returns standardized consumption metrics.

Usage

calculate_daily_consumption(
  current_weight,
  temperature,
  p_value = NULL,
  ration_percent = NULL,
  ration_grams = NULL,
  method = "p_value",
  processed_consumption_params,
  mean_prey_energy
)

Arguments

Value

List with specific and energetic consumption plus effective p_value

Calculate daily metabolic processes (Low-level)

Description

Calculates egestion, excretion, respiration, and SDA for a single day. Uses existing mid-level functions from other modules.

Usage

calculate_daily_metabolism(
  consumption_energy,
  current_weight,
  temperature,
  effective_p,
  processed_species_params,
  diet_proportions = NULL,
  indigestible_fractions = NULL,
  oxycal = 13560
)

Arguments

Value

List with all metabolic fluxes

Calculate reproductive energy loss for the day (Low-level)

Description

Calculates energy lost to reproduction on a given day based on reproduction data and current fish condition.

Usage

calculate_daily_spawn_energy(
  day,
  current_weight,
  predator_ed,
  reproduction_data = NULL
)

Arguments

Value

Spawning energy loss (J)

Calculate daily weight change (Low-level)

Description

Calculates final weight after growth, using existing predator energy density functions. Ensures biologically realistic weight changes.

Usage

calculate_daily_weight_change(
  current_weight,
  net_energy,
  spawn_energy,
  day,
  processed_predator_params
)

Arguments

Value

List with final weight and weight change

Calculate dissolved fraction of contaminant (Low-level)

Description

Calculates dissolved fraction based on organic carbon according to Arnot & Gobas (2004)

Usage

calculate_dissolved_fraction(poc_concentration, doc_concentration, kow)

Arguments

Value

Dissolved fraction

Calculate daily egestion (Mid-level - Main function)

Description

Main egestion calculation function called from simulation loop

Usage

calculate_egestion(
  consumption,
  temperature,
  p_value,
  processed_egestion_params
)

Arguments

Value

A non-negative numeric scalar giving the daily egestion rate in J per g fish per day. Returns 0 when consumption is zero. The equation used depends on processed_egestion_params$EGEQ (1 = constant fraction; 2-3 = temperature- and ration-dependent; 4 = temperature-dependent only). The result is always capped at consumption (egestion cannot exceed intake).

Examples

# EGEQ 1: constant fraction of consumption
params <- list(EGEQ = 1, FA = 0.16)
calculate_egestion(consumption = 5.0, temperature = 15, p_value = 0.5,
                   processed_egestion_params = params)

Calculate energy density from fat and protein (Low-level)

Description

Calculates energy density based on fat and protein content

Usage

calculate_energy_density(
  fat_content,
  protein_content,
  total_weight,
  fat_energy,
  protein_energy
)

Arguments

Value

Energy density (J/g wet weight)

Calculate daily excretion (Mid-level - Main function)

Description

Main excretion calculation function called from simulation loop

Usage

calculate_excretion(
  consumption,
  egestion,
  temperature,
  p_value,
  processed_excretion_params
)

Arguments

Value

A non-negative numeric scalar giving the daily excretion rate in J per g fish per day. Returns 0 when consumption is zero. The equation used depends on processed_excretion_params$EXEQ (1 = constant fraction of assimilated energy; 2-3 = temperature- and ration-dependent; 4 = temperature-dependent only).

Examples

# EXEQ 1: constant fraction of assimilated energy
params <- list(EXEQ = 1, UA = 0.1)
calculate_excretion(consumption = 5.0, egestion = 0.8, temperature = 15,
                    p_value = 0.5, processed_excretion_params = params)

Calculate fat content by subtraction (Low-level)

Description

Calculates grams of fat by subtracting water, protein and ash from total weight

Usage

calculate_fat_by_subtraction(
  total_weight,
  water_content,
  protein_content,
  ash_content
)

Arguments

Value

Fat content (g)

Calculate final weight using FB4 equations (Mid-level)

Description

Main function for calculating final weight from energy balance

Usage

calculate_final_weight_fb4(
  initial_weight,
  net_energy,
  spawn_energy = 0,
  processed_predator_params,
  day = 1
)

Arguments

Value

A named list with three elements:

final_weight

Numeric scalar. Fish weight (g) at end of day, after accounting for net energy and reproductive losses. Minimum value is 0.01 g.

final_energy_density

Numeric scalar. Energy density (J/g) corresponding to final_weight.

weight_change

Numeric scalar. Change in weight (g) during the day (final_weight - initial_weight); negative values indicate weight loss.

Examples

# PREDEDEQ 3: power function, positive net energy (weight gain)
params <- list(PREDEDEQ = 3, Alpha1 = 4800, Beta1 = 0.1)
calculate_final_weight_fb4(initial_weight = 100, net_energy = 500,
                           processed_predator_params = params)

Calculate fish:water partition coefficient (Low-level)

Description

Calculates Kbw based on body composition and Kow according to Arnot & Gobas (2004)

Usage

calculate_fish_water_partition(
  fat_fraction,
  protein_ash_fraction,
  water_fraction,
  kow
)

Arguments

Value

Fish:water partition coefficient

Calculate gill uptake efficiency (Low-level)

Description

Calculates gill efficiency based on Kow according to Arnot & Gobas (2004)

Usage

calculate_gill_efficiency(kow)

Arguments

Value

Gill uptake efficiency

Calculate Basic Growth Metrics

Description

Calculates basic growth metrics from daily weight data.

Usage

calculate_growth_metrics(daily_data)

Arguments

Value

List with growth metrics

Calculate daily mortality and reproduction (Mid-level - Main function)

Description

Calculates daily mortality probability and reproductive energy loss (natural mortality, fishing mortality, predation mortality, starvation, and weight-dependent survival) for a single time step.

Usage

calculate_mortality_reproduction(
  current_weight,
  temperature,
  day_of_year,
  processed_mortality_params,
  initial_weight = NULL
)

Arguments

Value

A named list with five elements:

mortality

Named list with seven numeric scalars (all daily rates, 0–1): survival_rate, combined_mortality, natural_mortality, fishing_mortality, predation_mortality, weight_effect (increment to mortality due to low body weight), and temperature_effect (increment due to thermal stress).

reproduction

NULL if no spawn pattern is defined in processed_mortality_params; otherwise a named list with weight_loss (g), energy_loss (J), spawn_fraction (0–1), and remaining_weight (g).

day_of_year

Integer. Day of year, as supplied.

current_weight

Numeric. Fish weight (g), as supplied.

temperature

Numeric. Water temperature (^\circC), as supplied.

Experimental

Mortality rate modelling is an **experimental feature** under active development. This function can be called directly to compute daily mortality probability for a single time step, but **mortality rates are not yet integrated** into the main 'run_fb4()' simulation loop. Full integration (automatic daily mortality application, population survival tracking, and result reporting) is planned for a future release. The API may change.

Note: **spawning energy loss** (reproductive cost) *is* already integrated into 'run_fb4()' and applies automatically when 'reproduction_data' is supplied to the 'Bioenergetic' object.

Examples

params <- list(
  base_mortality      = 0.001,
  natural_mortality   = 0.001,
  fishing_mortality   = 0.0005,
  predation_mortality = 0.0002,
  weight_threshold    = 10,
  starvation_factor   = 2,
  optimal_temp        = 18,
  thermal_tolerance   = 8,
  stress_factor       = 1.5,
  spawn_pattern       = NULL
)
calculate_mortality_reproduction(current_weight = 100, temperature = 15,
                                 day_of_year = 180,
                                 processed_mortality_params = params)

Calculate N:P ratios for all processes

Description

Calculates molar and mass N:P ratios for consumption, growth, excretion and egestion. Useful for understanding nutritional ecology and stoichiometric balance.

Usage

calculate_np_ratios(nitrogen_fluxes, phosphorus_fluxes, ratio_type = "mass")

Arguments

Value

A named list with three elements:

ratios

Named numeric vector of length 4 giving the N:P ratio for each process (consumed, growth, excretion, egestion). Values may be Inf when phosphorus is zero and NaN when both nutrients are zero.

ratio_type

Character. The ratio type as supplied ("mass" or "molar").

redfield_ratio

Numeric. Reference Redfield ratio: 7.2 for mass ratios and 16 for molar ratios.

Examples

nitrogen   <- list(consumed = 10, growth = 3, excretion = 5, egestion = 2)
phosphorus <- list(consumed = 1.5, growth = 0.5, excretion = 0.6, egestion = 0.4)
np_ratios  <- calculate_np_ratios(nitrogen, phosphorus)
np_ratios$ratios

Generic nutrient allocation in bioenergetic model (Low-level)

Description

Calculates nutrient balance in consumption, growth, excretion and egestion

Usage

calculate_nutrient_allocation(
  consumption,
  prey_nutrient_concentrations,
  nutrient_assimilation_efficiency,
  weight_gain,
  predator_nutrient_concentration
)

Arguments

Value

List with nutrient fluxes

Calculate nutrient balance (Mid-level - Main function)

Description

Calculates daily nitrogen and phosphorus fluxes (ingestion, retention, excretion) for a fish using prey and predator elemental concentrations.

Usage

calculate_nutrient_balance(consumption, weight_gain, processed_nutrient_params)

Arguments

Value

A named list with three elements:

nitrogen

Named list with six numeric scalars describing daily nitrogen fluxes (g N/day): consumed, assimilated, growth, excretion, egestion, and assimilation_efficiency (dimensionless fraction, 0–1).

phosphorus

Same structure as nitrogen but for phosphorus (g P/day).

weight_gain

Numeric scalar. Predator weight gain (g/day), as supplied.

Experimental

Nutrient regeneration modelling is an **experimental feature** under active development. This function can be called directly to compute daily N and P fluxes for a single time step, but it is **not yet integrated** into the main 'run_fb4()' simulation loop. Full integration (automatic daily nutrient tracking, inclusion in 'fb4_result' objects, and TMB backend support) is planned for a future release. The API may change.

Examples

params <- list(
  prey_n_concentrations     = c(0.025, 0.030),
  prey_p_concentrations     = c(0.004, 0.005),
  predator_n_concentration  = 0.030,
  predator_p_concentration  = 0.004,
  n_assimilation_efficiency = c(0.80, 0.80),
  p_assimilation_efficiency = c(0.60, 0.60)
)
calculate_nutrient_balance(consumption = c(2.0, 1.0),
                           weight_gain = 0.5,
                           processed_nutrient_params = params)

Calculate nutrient retention efficiencies

Description

Calculates assimilation and retention efficiencies for nitrogen and phosphorus. These metrics are important for understanding nutrient use efficiency.

Usage

calculate_nutrient_efficiencies(nitrogen_fluxes, phosphorus_fluxes)

Arguments

Value

A named list with four elements:

nitrogen

Named list with four numeric scalars: assimilation_efficiency (fraction consumed that is assimilated), retention_efficiency (fraction consumed retained in growth), excretion_rate (fraction consumed lost via excretion), and growth_efficiency (fraction assimilated retained in growth).

phosphorus

Same structure as nitrogen but for phosphorus.

relative_n_retention

Numeric. Ratio of nitrogen to phosphorus retention efficiency; NA when phosphorus retention is zero.

relative_n_excretion

Numeric. Ratio of nitrogen to phosphorus excretion rate; NA when phosphorus excretion rate is zero.

Examples

nitrogen   <- list(consumed = 10, assimilated = 8, growth = 3, excretion = 5,
                   egestion = 2, assimilation_efficiency = 0.8)
phosphorus <- list(consumed = 1.5, assimilated = 1.1, growth = 0.5,
                   excretion = 0.6, egestion = 0.4, assimilation_efficiency = 0.73)
calculate_nutrient_efficiencies(nitrogen, phosphorus)

Calculate predator energy density (Mid-level - Main function)

Description

Main energy density calculation function called from simulation loop

Usage

calculate_predator_energy_density(weight, day = 1, processed_predator_params)

Arguments

Value

A numeric scalar giving the predator energy density in J per g fish, calculated according to processed_predator_params$PREDEDEQ (1 = interpolated daily data; 2 = piecewise linear by weight; 3 = power function of weight).

Examples

# PREDEDEQ 3: power function of weight
params <- list(PREDEDEQ = 3, Alpha1 = 4800, Beta1 = 0.1)
calculate_predator_energy_density(weight = 100, processed_predator_params = params)

Calculate appropriate progress reporting interval

Description

Calculate appropriate progress reporting interval

Usage

calculate_progress_interval(n_days)

Calculate reproductive weight loss (Low-level)

Description

Calculates weight and energy loss during reproductive events

Usage

calculate_reproductive_loss(spawn_fraction, current_weight, energy_density)

Arguments

Value

List with weight and energy losses

Calculate daily respiration (Mid-level - Main function)

Description

Main respiration calculation function called from simulation loop

Usage

calculate_respiration(temperature, weight, processed_respiration_params)

Arguments

Value

A positive numeric scalar giving the daily specific respiration rate in g O_2 per g fish per day. Returns 0.000001 as a minimum safety floor when the result is non-finite or non-positive (e.g. at or above the lethal temperature RTM). The value accounts for both the temperature-dependence function (REQ 1 or 2) and the activity multiplier.

Examples

# REQ 2: Kitchell et al. (1977) temperature dependence
params <- list(REQ = 2, RA = 0.0033, RB = -0.227,
               RTM = 30, RTO = 18, RX = 0.5, ACT = 1.5)
calculate_respiration(temperature = 15, weight = 100,
                      processed_respiration_params = params)

Calculate additional parameters for respiration equation 2 (Mid-level)

Description

Calculates derived parameters needed for temperature equation 2

Usage

calculate_respiration_params_eq2(RQ, RTM, RTO)

Arguments

Value

List with RY, RZ, RX

Calculate Specific Dynamic Action (SDA) (Low-level)

Description

Implements SDA calculation for metabolic cost of feeding and digestion

Usage

calculate_sda(consumption_energy, egestion_energy, SDA_coeff)

Arguments

Details

Calculates SDA using: SDA = SDA_coeff × (consumption - egestion)

Special cases: - When egestion > consumption: egestion is capped at consumption value - Result is always >= 0

Value

SDA in energy (J/g)

Calculate spawning energy loss (Low-level)

Description

Calculates energy lost to reproduction on a given day

Usage

calculate_spawn_energy(spawn_fraction, current_weight, energy_density)

Arguments

Value

Spawning energy loss (J)

Calculate stoichiometric balance

Description

Analyzes nutritional limitations based on N:P ratios and determines which nutrient is limiting growth.

Usage

calculate_stoichiometric_balance(nutrient_balance)

Arguments

Value

A named list with ten elements:

nutrient_limitation

Character. Overall assessment: "N-limited", "P-limited", or "Undetermined".

limiting_nutrient

Character. The identified limiting nutrient ("nitrogen", "phosphorus", or "unknown").

excess_nutrient

Character. The nutrient in relative excess.

excess_factor

Numeric. Fold-excess of the non-limiting nutrient relative to the Redfield ratio; 1 when undetermined.

limiting_efficiency

Numeric. Retention efficiency of the limiting nutrient; NA when undetermined.

consumption_np_ratio

Numeric. Observed N:P ratio of consumed food.

redfield_ratio

Numeric. Reference Redfield ratio used.

np_deviation

Numeric. Difference between observed and Redfield N:P ratio.

efficiencies

List from calculate_nutrient_efficiencies.

np_ratios

List from calculate_np_ratios.

Examples

nb <- list(
  nitrogen   = list(consumed = 10, assimilated = 8, growth = 3, excretion = 5,
                    egestion = 2, assimilation_efficiency = 0.8),
  phosphorus = list(consumed = 1.5, assimilated = 1.1, growth = 0.5,
                    excretion = 0.6, egestion = 0.4, assimilation_efficiency = 0.73)
)
calculate_stoichiometric_balance(nb)

Calculate temperature-dependent mortality (Low-level)

Description

Adjusts mortality based on thermal stress

Usage

calculate_temperature_dependent_mortality(
  temperature,
  base_mortality,
  optimal_temp,
  thermal_tolerance,
  stress_factor
)

Arguments

Value

Adjusted mortality rate

Calculate temperature factor for consumption (Mid-level)

Description

Coordinates temperature equation selection and calculation

Usage

calculate_temperature_factor_consumption(
  temperature,
  processed_consumption_params
)

Arguments

Value

Temperature factor

Calculate temperature factor for respiration (Mid-level)

Description

Coordinates temperature equation selection and calculation

Usage

calculate_temperature_factor_respiration(
  temperature,
  processed_respiration_params
)

Arguments

Value

Temperature factor

Calculate weight-dependent mortality (Low-level)

Description

Adjusts mortality based on current fish weight

Usage

calculate_weight_dependent_mortality(
  current_weight,
  base_mortality,
  weight_threshold,
  starvation_factor,
  initial_weight = NULL
)

Arguments

Value

Adjusted mortality rate

Check Bioenergetic Object Readiness

Description

Returns a named logical list indicating which of the four required components (species parameters, temperature, diet, initial weight) are present in a Bioenergetic object. Centralises the readiness check that is otherwise duplicated across print.Bioenergetic and summary.Bioenergetic.

Usage

check_bioenergetic_readiness(x)

Arguments

Value

Named logical list with elements has_params, has_temp, has_diet, and has_initial.

Check Numeric Value

Description

Fast validation of numeric values with basic range checking. Simplified utility function for common validation needs.

Usage

check_numeric_value(value, name, min_val = -Inf, max_val = Inf)

Arguments

Details

Performs essential validations:

• Not NULL

• Numeric type

• Finite values (no NA, NaN, Inf)

• Within specified range

Value

The original value (numeric, same length as input), returned unchanged when all checks pass. Throws an error if value is NULL, non-numeric, contains non-finite elements (NA, NaN, Inf), or falls outside [min_val, max_val].

Examples

check_numeric_value(5, "weight")
try(check_numeric_value(-1, "weight", min_val = 0))
try(check_numeric_value(NA, "weight"))

Check if target was achieved for traditional methods

Description

Check if target was achieved for traditional methods

Usage

check_target_achievement(raw_results, execution_plan)

Check TMB model availability (simplified for installed package)

Description

Verify that TMB model is available in installed package.

Usage

check_tmb_compilation(dll_name = "fb4package", verbose = FALSE)

Arguments

Value

TRUE if model is available, FALSE otherwise

Check for outliers in weight data

Description

Identifies potential outliers in weight measurements using IQR method.

Usage

check_weight_outliers(individual_data)

Arguments

Clamp values to a range

Description

Restricts x to the interval [min_val, max_val]. Values outside the range are replaced by the nearest bound.

Usage

clamp(x, min_val, max_val, warn = TRUE, param_name = "value")

Arguments

Value

x with values outside [min_val, max_val] replaced by the bounds

Examples

suppressWarnings(clamp(1.5, 0, 1))
suppressWarnings(clamp(-0.5, 0, 1))
clamp(0.3, 0, 1)
suppressWarnings(clamp(c(-1, 0.5, 2), 0, 1))

Close graphics device after saving

Description

Closes graphics device and shows confirmation message.

Usage

close_save_device(save_path)

Arguments

Compare individuals from hierarchical models

Description

Compares performance metrics between individuals in hierarchical models. Provides statistical summaries and identifies outliers.

Usage

compare_individuals(result, metrics = "all", confidence_level = 0.95)

Arguments

Value

A named list with at minimum three context elements: n_individuals (integer), metrics_compared (character vector), and confidence_level (numeric). Depending on metrics, the following sub-lists are appended; each is produced by an internal summary helper and contains metric_name, n_valid, mean, sd, min, max, median, cv, range, outliers, and performance: consumption, efficiency, and p_value. The growth element (when requested) is itself a list with two such summaries (total_growth and relative_growth). A rankings data.frame (one row per individual; columns for per-metric ranks, composite_rank, and overall_rank) is always appended. Stops with an error if result was not produced by the hierarchical method.

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
mr_data <- data.frame(
  individual_id  = paste0("fish_", 1:5),
  initial_weight = c(10, 12, 11, 13, 9),
  final_weight   = c(80, 95, 85, 100, 70)
)
result_hier <- run_fb4(bio, strategy = "hierarchical", backend = "tmb",
                       fit_to = "Weight", observed_weights = mr_data,
                       verbose = FALSE)
comparison <- compare_individuals(result_hier)

Compare multiple FB4 results

Description

Compares multiple FB4 simulation results across different scenarios, parameters, or methods. Useful for comparing alternative models or experimental conditions.

Usage

compare_scenarios(
  result_list,
  metrics = c("consumption", "growth", "efficiency"),
  confidence_level = 0.95
)

Arguments

Value

A named list with five elements:

n_scenarios

Integer. Number of scenarios compared.

scenario_names

Character vector of scenario names.

metrics_compared

Character vector of metrics requested.

confidence_level

Numeric. Confidence level as supplied.

scenario_data

data.frame with one row per scenario. Always contains scenario, method, backend, and converged. Additional *_est and *_se columns are appended for each requested metric (consumption, growth, efficiency, p_value).

When at least two scenarios provide uncertainty estimates, statistical_tests is appended (list of pairwise test results). best_performers (named list of scenario names with highest estimated value per metric) is always appended.

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
r1 <- run_fb4(bio, strategy = "direct", p_value = 0.4, verbose = FALSE)
r2 <- run_fb4(bio, strategy = "direct", p_value = 0.7, verbose = FALSE)
comparison <- compare_scenarios(list(low_p = r1, high_p = r2))

Compare N:P ratios with Redfield ratios

Description

Compares calculated N:P ratios with the classical Redfield ratio. Useful for understanding deviations from typical oceanic proportions.

Usage

compare_with_redfield(np_ratios)

Arguments

Value

A data.frame with one row per process and six columns: Process (character), NP_Ratio (numeric), Redfield_Ratio (numeric), Difference (numeric; observed minus Redfield), Relative_Difference (numeric; % deviation from Redfield), and Interpretation (character; one of "N-rich relative to P", "N-poor relative to P", "No P available", or "No flux").

Examples

nitrogen   <- list(consumed = 10, growth = 3, excretion = 5, egestion = 2)
phosphorus <- list(consumed = 1.5, growth = 0.5, excretion = 0.6, egestion = 0.4)
np  <- calculate_np_ratios(nitrogen, phosphorus)
compare_with_redfield(np)

Comprehensive nutritional analysis

Description

Performs a comprehensive nutritional analysis combining all nutritional metrics including N:P ratios, nutrient efficiencies, body composition, and diet quality assessment.

Usage

comprehensive_nutritional_analysis(
  result,
  nutrient_balance = NULL,
  composition_params = NULL,
  diet_quality_data = NULL
)

Arguments

Value

A named list with at minimum two elements: model_info (list with method and has_daily_output) and energy_budget (from analyze_energy_budget). When optional inputs are provided, the following elements are appended:

np_ratios, redfield_comparison, nutrient_efficiencies, stoichiometric_balance

Added when nutrient_balance is supplied.

initial_composition, final_composition, composition_changes

Added when composition_params is supplied and both initial and final weights are available in result.

diet_quality

Added when diet_quality_data is supplied.

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)
analysis <- comprehensive_nutritional_analysis(result)

Compute likelihood profile for p_value

Description

Computes the likelihood profile by evaluating the log-likelihood function across a grid of p_values while keeping all other parameters at their MLE.

Usage

compute_likelihood_profile(
  p_estimate,
  p_se,
  simulation_function,
  observed_weights,
  sigma_estimate,
  grid_size = 50,
  grid_range_factor = 3
)

Arguments

Value

Data frame with p_values and corresponding log_likelihoods

Consumption Functions for FB4 Model

Description

Functions implementing the four consumption temperature-dependence equations (CEQ 1–4) and the allometric maximum-consumption function used in FB4. Consumption is modelled as:

C = C_{\max} \cdot p \cdot F(T), \quad C_{\max} = CA \cdot W^{CB}

where p is the proportion of maximum consumption (P-value), F(T) is a temperature-dependence function, W is body mass (g), and CA, CB are species-specific intercept and slope coefficients.

CEQ 1 — simple Q10 exponential: F(T) = e^{CQ \cdot T}

CEQ 2 — Kitchell et al. (1977): F(T) = V^{CX} \cdot e^{CX(1-V)}, where V = (CTM - T)/(CTM - CTO)

CEQ 3 — Thornton and Lessem (1978): two-part sigmoid using CQ, CTO, CTL, CTM, CK1, CK4

CEQ 4 — polynomial: F(T) = e^{CQ \cdot T + CK1 \cdot T^2 + CK4 \cdot T^3}

Value

No return value; this page documents the consumption functions module. See individual function documentation for return values.

References

Kitchell, J.F., Stewart, D.J. and Weininger, D. (1977). Applications of a bioenergetics model to yellow perch and walleye. Journal of the Fisheries Research Board of Canada, 34(10), 1922–1935. doi:10.1139/f77-258

Thornton, K.W. and Lessem, A.S. (1978). A temperature algorithm for modifying biological rates. Transactions of the American Fisheries Society, 107(2), 284–287.

Hartman, K.J. and Hayward, R.S. (2007). Bioenergetics. In C.S. Guy and M.L. Brown (eds.), Analysis and Interpretation of Freshwater Fisheries Data. American Fisheries Society, Bethesda, MD.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Temperature function for consumption - Equation 1 (Low-level)

Description

Implements temperature equation 1 (simple exponential)

Usage

consumption_temp_eq1(temperature, CQ)

Arguments

Value

Temperature factor

Temperature function for consumption - Equation 2 (Low-level)

Description

Implements temperature equation 2 (Kitchell et al. 1977)

Usage

consumption_temp_eq2(temperature, CTM, CTO, CX, warn = TRUE)

Arguments

Details

Special cases: - When temperature >= CTM: returns 0 (typically approximated by the upper incipient lethal temperature) - When V <= 0: returns 0 (mathematical fallback)

Value

Temperature factor

Temperature function for consumption - Equation 3 (Low-level)

Description

Implements temperature equation 3 (Thornton and Lessem 1978)

Usage

consumption_temp_eq3(temperature, CQ, CG1, CK1, CG2, CTL, CK4)

Arguments

Value

Temperature factor

Temperature function for consumption - Equation 4 (Low-level)

Description

Implements temperature equation 4 (polynomial)

Usage

consumption_temp_eq4(temperature, CQ, CK1, CK4)

Arguments

Value

Temperature factor

Contaminant Accumulation Functions for FB4 Model

Description

Experimental functions for modelling daily contaminant (e.g. methylmercury, PCBs) dynamics in fish using three bioaccumulation models (CONTEQ 1–3).

CONTEQ 1 — food uptake only, no elimination: \text{Burden}_{t+1} = \text{Burden}_t + \sum_i C_i \cdot [\text{prey}]_i \cdot \text{AE}_i

CONTEQ 2 — food uptake with temperature- and weight-dependent elimination (Trudel and Rasmussen 1997): K_x = \exp(0.066 T - 0.2 \ln W - 6.56)

CONTEQ 3 — Arnot and Gobas (2004): uptake from both water (via gill transfer) and food, elimination proportional to respiration.

Value

No return value; this page documents the contaminant accumulation functions module. See individual function documentation for return values.

References

Arnot, J.A. and Gobas, F.A.P.C. (2004). A food web bioaccumulation model for organic chemicals in aquatic ecosystems. Environmental Toxicology and Chemistry, 23(10), 2343–2355. doi:10.1897/03-438

Trudel, M. and Rasmussen, J.B. (1997). Modeling the elimination of mercury by fish. Environmental Science and Technology, 31(6), 1716–1722. doi:10.1021/es960609t

Contaminant model 1 - Food uptake only (Low-level)

Description

Simple model without elimination, only accumulation from food

Usage

contaminant_model_1(
  consumption,
  prey_concentrations,
  transfer_efficiency,
  current_burden
)

Arguments

Value

List with clearance, uptake, and new burden

Contaminant model 2 - With temperature and weight dependent elimination (Low-level)

Description

Model with food uptake and elimination dependent on temperature and weight Based on Trudel & Rasmussen (1997) for MeHg

Usage

contaminant_model_2(
  consumption,
  weight,
  temperature,
  prey_concentrations,
  assimilation_efficiency,
  current_burden
)

Arguments

Value

List with clearance, uptake, and new burden

Contaminant model 3 - Arnot & Gobas (2004) (Low-level)

Description

Complete model with uptake from water and food, elimination proportional to respiration

Usage

contaminant_model_3(
  respiration_o2,
  consumption,
  weight,
  temperature,
  prey_concentrations,
  assimilation_efficiency,
  current_burden,
  gill_efficiency,
  fish_water_partition,
  water_concentration,
  dissolved_fraction,
  do_saturation
)

Arguments

Value

List with clearance, uptake, and new burden

Convert list of daily results to data frame

Description

Convert list of daily results to data frame

Usage

convert_daily_results_to_dataframe(daily_results)

Convert respiration from O2 to energy units (Utility)

Description

Converts respiration from O2 consumption to energy equivalents

Usage

convert_respiration_to_energy(respiration_o2, oxycal = 13560)

Arguments

Value

Respiration in J/g fish/day

Convert hierarchical observed_weights to individual_data format

Description

Convert hierarchical observed_weights to individual_data format

Usage

convert_to_individual_data(observed_weights, verbose = FALSE)

Arguments

Value

data.frame in format expected by TMB hierarchical

Core Validation Functions for FB4

Description

Atomic validation functions that provide the foundation for all other validation operations. These functions handle the most basic validation patterns used throughout the FB4 system: numeric range checks, structural requirements (required columns, minimum rows), and domain-specific validators for fractions, positive quantities, and temperatures. All validators return standardised fb4_validation objects constructed by validation_result, which can be aggregated with accumulate_validations.

Value

No return value; this page documents the core validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Create Binary Search Strategy

Description

Create Binary Search Strategy

Usage

create_binary_search_strategy(execution_plan)

Arguments

Value

Strategy object implementing FB4Strategy interface

Create Bootstrap Strategy

Description

Create Bootstrap Strategy

Usage

create_bootstrap_strategy(execution_plan)

Arguments

Value

Strategy object implementing FB4Strategy interface

Create Direct Strategy

Description

Create Direct Strategy

Usage

create_direct_strategy(execution_plan, direct_type)

Arguments

Value

Strategy object implementing FB4Strategy interface

Create empty composition for invalid inputs (Utility)

Description

Create empty composition for invalid inputs (Utility)

Usage

create_empty_composition()

Value

A named list with 13 numeric/logical elements, all set to zero or FALSE: total_weight, water_g, protein_g, ash_g, fat_g, water_fraction, protein_fraction, ash_fraction, fat_fraction, energy_density, total_energy, total_fraction (all 0), and balanced (FALSE). Used as a safe fallback when fish weight is zero or negative.

Examples

create_empty_composition()

Create standardized error result

Description

Creates consistent error result structure across strategies.

Usage

create_error_result(error_message, strategy_type, execution_plan)

Arguments

Value

Standardized error result

Create execution plan for FB4 strategies

Description

Consolidates all parameters needed for FB4 execution into a single plan object. Handles method auto-detection, backend selection, and parameter validation.

Usage

create_execution_plan(
  bio_obj,
  fit_to = NULL,
  fit_value = NULL,
  observed_weights = NULL,
  covariates = NULL,
  strategy,
  backend,
  first_day = 1,
  last_day = NULL,
  oxycal = 13560,
  tolerance = 0.001,
  max_iterations = 25,
  verbose = FALSE,
  ...
)

Arguments

Value

List with complete execution plan

Create execution summary for verbose output

Description

Creates a summary of the execution for logging purposes. Works with the unified result structure.

Usage

create_execution_summary(result, execution_plan, elapsed_time)

Arguments

Value

Character vector with summary lines

Create FB4 strategy based on method

Description

Factory function that creates the appropriate strategy instance based on the specified method. Handles strategy instantiation and initial setup. Validates concordance between fit_to and strategy parameters.

Usage

create_fb4_strategy(execution_plan)

Arguments

Value

Strategy object implementing FB4Strategy interface

Create Hierarchical Strategy

Description

Create Hierarchical Strategy

Usage

create_hierarchical_strategy(execution_plan)

Arguments

Value

Strategy object implementing FB4Strategy interface

Create individual rankings across metrics

Description

Ranks individuals across multiple metrics and creates composite scores.

Usage

create_individual_rankings(individual_data, metrics)

Arguments

Value

Data frame with rankings

Create summary statistics for individual metric

Description

Internal function to create summary statistics for a single metric across all individuals.

Usage

create_individual_summary(data, metric_name)

Arguments

Value

List with summary statistics

Create method-specific data section

Description

Builds the $method_data slot of an fb4_result object. Dispatches on method and delegates large uncertainty list construction to dedicated helpers: build_tmb_uncertainty, build_individual_uncertainty, build_population_uncertainty.

Usage

create_method_specific_data(raw_results, execution_plan, method)

Arguments

Value

Named list that becomes result$method_data

Create MLE Strategy

Description

Create MLE Strategy

Usage

create_mle_strategy(execution_plan)

Arguments

Value

Strategy object implementing FB4Strategy interface

Create Optim Strategy

Description

Create Optim Strategy

Usage

create_optim_strategy(execution_plan)

Arguments

Value

Strategy object implementing FB4Strategy interface

Comprehensive post-simulation analysis summary

Description

**Post-hoc analysis function** — takes a finished fb4_result object and bundles growth, feeding, and energy-budget analyses into a single list. Useful when you need all major metrics in one call.

This is different from the internal $summary slot (built automatically during result construction by create_unified_summary()). This function re-derives richer metrics from daily_output and supports uncertainty propagation for MLE / bootstrap / hierarchical results.

Usage

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

Arguments

Value

Named list with model_info, growth, feeding, energy_budget, and model_fit sections

See Also

analyze_growth_patterns, analyze_feeding_performance, analyze_energy_budget

Create unified fit info section

Description

Create unified fit info section

Usage

create_unified_fit_info(raw_results, execution_plan, method)

Build the $summary slot of an fb4_result object

Description

**Internal constructor helper** — called once by build_fb4_result_unified() when the result object is first assembled. Translates raw strategy outputs into the standardised $summary slot that all downstream code reads from.

This is NOT a post-hoc analysis function. For user-facing comprehensive analysis of a finished result, see create_result_summary.

Usage

create_unified_summary(raw_results, execution_plan, method)

Arguments

Value

Named list that becomes result$summary

Data Processing Functions for FB4

Description

Functions for preparing, validating, and transforming the temporal and parameter data required by the FB4 simulation engine. The main entry point is prepare_simulation_data, which orchestrates species-parameter processing (via process_species_parameters) and temporal-data processing (via process_bioenergetic_data). Ancillary functions handle time-series interpolation (interpolate_time_series), diet normalisation, reproduction scheduling, and TMB-format transformations for statistical fitting strategies.

Value

No return value; this page documents the data processing functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Data Validation Functions for FB4

Description

Data validation functions built on top of the core validators in core-validators. Covers diet-energy consistency (validate_diet_consistency), individual mark-recapture data (validate_individual_data), processed temporal arrays (validate_temporal_data), the complete simulation data structure (validate_complete_simulation_data), and equation parameter requirements (validate_equation_params).

Value

No return value; this page documents the data validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Detect method from raw results or execution plan

Description

Detect method from raw results or execution plan

Usage

detect_method(raw_results, execution_plan)

Detect method and backend from fb4_result

Description

Internal function to detect the method and backend used in a simulation.

Usage

detect_result_type(result)

Arguments

Value

List with method, backend, and has_uncertainty flags

Egestion and Excretion Functions for FB4 Model

Description

Functions implementing four egestion models (EGEQ 1–4) and four excretion models (EXEQ 1–4). These represent losses of consumed energy as feces (F) and nitrogenous wastes (U) respectively.

Egestion models:

EGEQ 1 — constant fraction: F = FA \cdot C

EGEQ 2 — Elliott (1976), temperature- and feeding-dependent: F = FA \cdot T^{FB} \cdot e^{FG \cdot p} \cdot C

EGEQ 3 — Stewart et al. (1983), includes indigestible fraction: modified form of EGEQ 2 accounting for indigestible prey material.

EGEQ 4 — Elliott (1976), temperature-dependent only: F = FA \cdot T^{FB} \cdot C

Excretion models:

EXEQ 1 — constant fraction of assimilated energy: U = UA \cdot (C - F)

EXEQ 2–3 — Elliott (1976), temperature- and feeding-dependent: U = UA \cdot T^{UB} \cdot e^{UG \cdot p} \cdot (C - F)

EXEQ 4 — temperature-dependent only.

Value

No return value; this page documents the egestion and excretion functions module. See individual function documentation for return values.

References

Elliott, J.M. (1976). Energy losses in the waste products of brown trout (Salmo trutta L.). Journal of Animal Ecology, 45(2), 561–580.

Stewart, D.J., Weininger, D., Rottiers, D.V. and Edsall, T.A. (1983). An energetics model for lake trout, Salvelinus namaycush: application to the Lake Michigan population. Canadian Journal of Fisheries and Aquatic Sciences, 40(6), 681–698.

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Egestion model 1 - Basic (Low-level)

Description

Simple egestion model with constant fraction of consumption

Usage

egestion_model_1(consumption, FA)

Arguments

Value

Egestion (J/g)

Egestion model 2 - Elliott (1976) (Low-level)

Description

Egestion model dependent on temperature and feeding level

Usage

egestion_model_2(consumption, temperature, p_value, FA, FB, FG)

Arguments

Value

Egestion (J/g)

Egestion model 3 - Stewart et al. (1983) (Low-level)

Description

Model that includes indigestible prey

Usage

egestion_model_3(
  consumption,
  temperature,
  p_value,
  FA,
  FB,
  FG,
  indigestible_fraction
)

Arguments

Value

Egestion (J/g)

Egestion model 4 - Elliott (1976) without p_value (Low-level)

Description

Simplified model without feeding level dependence

Usage

egestion_model_4(consumption, temperature, FA, FB)

Arguments

Value

Egestion (J/g)

Excretion model 1 - Basic (Low-level)

Description

Simple excretion model proportional to assimilated matter

Usage

excretion_model_1(consumption, egestion, UA)

Arguments

Value

Excretion (J/g)

Excretion model 2 - With temperature and feeding dependence (Low-level)

Description

Excretion model dependent on temperature and feeding level

Usage

excretion_model_2(consumption, egestion, temperature, p_value, UA, UB, UG)

Arguments

Value

Excretion (J/g)

Excretion model 3 - Variant of model 2 (Low-level)

Description

Alternative implementation of temperature and feeding dependent model

Usage

excretion_model_3(consumption, egestion, temperature, p_value, UA, UB, UG)

Arguments

Value

Excretion (J/g)

Excretion model 4 - Without feeding dependence (Low-level)

Description

Excretion model with only temperature dependence

Usage

excretion_model_4(consumption, egestion, temperature, UA, UB)

Arguments

Value

Excretion (J/g)

Execute single day simulation (Mid-level)

Description

Coordinates all daily calculations for one simulation day. Main business logic function that orchestrates low-level calculations.

Usage

execute_daily_simulation(
  day,
  current_weight,
  consumption_method,
  processed_simulation_data,
  oxycal = 13560
)

Arguments

Value

List with all daily results

Execute hierarchical TMB using unified architecture and shared commons

Description

Execute hierarchical TMB using unified architecture and shared commons

Usage

execute_hierarchical_tmb(plan)

Execute MLE TMB using unified architecture

Description

Execute MLE TMB using unified architecture

Usage

execute_mle_tmb(plan)

Execute simulation with any method

Description

Unified simulation execution function used by all strategies. Wraps run_fb4_simulation with a common interface for p_value, ration_percent, and ration_grams methods.

Usage

execute_simulation_with_method(
  method_type,
  method_value,
  processed_simulation_data,
  oxycal = 13560,
  extract_metric = "full",
  output_daily = FALSE,
  verbose = FALSE
)

Arguments

Value

Extracted metric (if extract_metric specified) or full simulation result

Extract ADREPORT values from TMB report

Description

Extract ADREPORT values from TMB report

Usage

extract_adreport_values(report, model_type)

Arguments

Value

List of ADREPORT values

Extract parameters for basic model

Description

Extract parameters for basic model

Usage

extract_basic_parameters(results, params, obj, confidence_level, verbose)

Arguments

Value

Updated results list

Extract data sources from bioenergetic object

Description

Extract data sources from bioenergetic object

Usage

extract_data_sources(bio_obj)

Arguments

Value

List with data source information

Extract parameters for hierarchical model

Description

Extract parameters for hierarchical model

Usage

extract_hierarchical_parameters(
  results,
  params,
  obj,
  confidence_level,
  verbose
)

Arguments

Value

Updated results list

Extract Species Information for Titles

Description

Extracts species name from fb4_result object for plot titles.

Usage

extract_species_name(x)

Arguments

Value

Character string with species name or NULL if not available

Extract common strategy parameters from execution plan

Description

Extracts and validates common parameters used across multiple strategies. Eliminates parameter extraction duplication.

Usage

extract_strategy_parameters(
  execution_plan,
  required_params = NULL,
  default_values = list()
)

Arguments

Value

List with extracted and validated parameters

Extract comprehensive results from TMB optimization

Description

Extract and process optimization results for both basic and hierarchical models. Handles standard errors, confidence intervals, and model diagnostics.

Usage

extract_tmb_results(
  obj,
  opt_result,
  model_type = "basic",
  confidence_level = 0.95,
  verbose = FALSE
)

Arguments

Value

List with comprehensive results

Analysis Plots for FB4 Results (Uncertainty and Sensitivity)

Description

Plotting functions for uncertainty analysis and sensitivity analysis. Exported functions include plot_uncertainty.fb4_result (dispatches to MLE, bootstrap, and hierarchical sub-functions), plot_distributions.fb4_result, plot_sensitivity.fb4_result, and plot_growth_temperature_sensitivity.

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Bioenergetic Object Plots for Setup Validation

Description

Plotting functions for Bioenergetic objects (before running a simulation). These plots help validate model setup by displaying temperature profiles (plot_bio_temperature), diet composition over time (plot_bio_diet), predator energy density (plot_bio_energy), and an integrated readiness dashboard (plot_bio_dashboard).

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Daily Simulation Plots for FB4 Results

Description

Plotting functions for daily simulation output. These functions work with the daily_output data produced by run_fb4() and visualise growth (plot_growth), consumption (plot_consumption), temperature (plot_temperature), and energy (plot_energy) patterns over time, as well as an integrated dashboard (plot_dashboard).

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Core Plotting Functions for FB4 Results

Description

Core utilities and helper functions for the FB4 visualization system. Provides consistent color schemes (get_color_scheme), plot layout helpers (setup_plot_layout), graphics-device management (setup_save_device, close_save_device), annotation utilities (add_confidence_bands, add_plot_annotations), and data validation helpers (validate_plot_data) shared across all plotting modules.

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

FB4 Plotting Functions

Description

Main plotting functions for FB4 bioenergetic model results. Provides S3 methods (plot.fb4_result, plot.Bioenergetic) that dispatch to specialised plot types ("dashboard", "growth", "consumption", "temperature", "energy", "uncertainty", "sensitivity").

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Fish Bioenergetics 4.0 Official Parameters Database

Description

Comprehensive database containing species-specific bioenergetic parameters for the Fish Bioenergetics 4.0 model. This database includes consumption, respiration, egestion, excretion, and predator energy density parameters for multiple fish species across different life stages.

Usage

fish4_parameters

Format

A list containing bioenergetic parameters for fish species with the following structure:

species_name

List for each species containing:

species_info

Basic taxonomic information (scientific name, common name, family, order)

life_stages

Named list of life stages (e.g., "juvenile", "adult", "larval") containing:

consumption

Consumption parameters (CA, CB, CQ, CTO, CTM, CTL, CK1, CK4, CEQ)

respiration

Respiration parameters (RA, RB, RQ, RTO, RTM, RTL, RK1, RK4, RK5, REQ)

activity

Activity multipliers (ACT, BACT)

sda

Specific Dynamic Action coefficient (SDA)

egestion

Egestion parameters (FA, FB, FG, EGEQ)

excretion

Excretion parameters (UA, UB, UG, EXEQ)

predator

Predator energy density parameters (Alpha1, Beta1, Alpha2, Beta2, Cutoff, ED_data, PREDEDEQ)

source

Literature source reference

notes

Additional notes about the parameters

sources

Vector of literature sources for the species

Details

The database contains parameters for fish species from multiple families including Salmonidae, Percidae, Centrarchidae, Cyprinidae, and others. Each species entry includes one or more life stages with complete or partial parameter sets.

Parameter Categories:

Consumption:

Temperature-dependent consumption model parameters

Respiration:

Metabolic rate and activity parameters

Egestion:

Waste production and defecation parameters

Excretion:

Nitrogenous waste excretion parameters

Predator Energy Density:

Weight-dependent energy content parameters

Temperature Parameters:

CTO, RTO:

Optimum temperature for consumption/respiration

CTM, RTM:

Maximum temperature for consumption/respiration

CTL, RTL:

Lethal temperature for consumption/respiration

Usage: This database is primarily used with the Bioenergetic constructor to create species-specific bioenergetic model objects. Parameters can be extracted using utility functions or accessed directly by species and life stage.

Source

Parameters extracted from Parameters_official.csv, the official species database bundled with the Fish Bioenergetics 4.0 ('FB4') Shiny application (<https://github.com/biofish/FishBioenergetics>). Converted to R list format via generate_fish4_parameters(). Original parameter values compiled from peer-reviewed literature; see the source field within each species entry for individual references.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A., Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

See Also

Bioenergetic, run_fb4

Examples

data(fish4_parameters)
head(names(fish4_parameters))
salmon_info <- fish4_parameters[["Oncorhynchus mykiss"]]
names(salmon_info$life_stages)
juvenile_params <- salmon_info$life_stages$juvenile
names(juvenile_params$consumption)

Fish Bioenergetics 4.0 Parameters Database Metadata

Description

Metadata information about the Fish Bioenergetics 4.0 parameters database, including version information, creation details, and structural specifications.

Usage

fish4_parameters_metadata

Format

A list containing metadata about the fish4_parameters database:

version

Version number of the database

creation_date

Date when the database was generated

source_file

Original CSV file used to generate the database

description

Brief description of the database contents

n_species

Total number of species in the database

n_total_records

Total number of parameter records

families_included

Number of taxonomic families represented

parameter_groups

Vector of parameter category names

required_parameters

List of essential parameters for FB4 simulations

units

Description of parameter units and measurements

Details

This metadata object provides essential information about the structure, content, and requirements of the fish4_parameters database. It includes quality control information and parameter specifications necessary for proper use of the bioenergetic model.

Required Parameters: The metadata specifies which parameters are essential for running Fish Bioenergetics 4.0 simulations:

Consumption:

CA, CB, CQ, CTO, CTM, CTL

Respiration:

RA, RB, RQ, RTO, RTM, RTL

Units:

Temperature:

Degrees Celsius

Energy Density:

Joules per gram (J/g)

Weight:

Grams (g)

Rates:

Proportions or model coefficients

Source

Generated automatically when converting Parameters_official.csv (from the Fish Bioenergetics 4.0 Shiny application, <https://github.com/biofish/FishBioenergetics>) into an R list object.

See Also

fish4_parameters, Bioenergetic

Examples

data(fish4_parameters_metadata)
print(fish4_parameters_metadata$description)
print(paste("Species count:", fish4_parameters_metadata$n_species))

Fit FB4 model using binary search

Description

Coordinates the binary search fitting process for weight or consumption targets, then runs a final detailed simulation with the optimal p_value.

Usage

fit_fb4_binary_search(
  target_value,
  fit_type,
  processed_simulation_data,
  oxycal = 13560,
  tolerance = 0.001,
  max_iterations = 25,
  lower_bound = 0.01,
  upper_bound = 5,
  verbose = FALSE
)

Arguments

Value

List with fitting results and final simulation

Fit FB4 model using bootstrap estimation with parallel option

Description

Coordinates the bootstrap fitting process: runs the resampling loop via bootstrap_p_values, computes summary statistics and confidence intervals, and runs a final detailed simulation with the mean p_value.

Usage

fit_fb4_bootstrap(
  final_weights,
  processed_simulation_data,
  n_bootstrap = 1000,
  oxycal = 13560,
  confidence_level = 0.95,
  sample_size = NULL,
  compute_percentiles = TRUE,
  parallel = FALSE,
  n_cores = NULL,
  upper_p = 1,
  verbose = FALSE,
  store_predicted_weights = TRUE
)

Arguments

Value

List with bootstrap fitting results including consumption and predicted weights

Fit FB4 model using Maximum Likelihood Estimation

Description

Coordinates the MLE fitting process: runs the log-normal likelihood optimisation, optionally computes a likelihood profile, and runs a final detailed simulation with the estimated p_value.

Usage

fit_fb4_mle(
  observed_weights,
  processed_simulation_data,
  estimate_sigma = TRUE,
  oxycal = 13560,
  confidence_level = 0.95,
  compute_profile = FALSE,
  profile_grid_size = 50,
  verbose = FALSE
)

Arguments

Value

List with MLE fitting results

Fit FB4 model using optim()

Description

Coordinates the optim-based fitting process for weight or consumption targets, then runs a final detailed simulation with the optimal p_value.

Usage

fit_fb4_optim(
  target_value,
  fit_type,
  processed_simulation_data,
  method = "Brent",
  oxycal = 13560,
  lower = 0.01,
  upper = 5,
  hessian = FALSE,
  verbose = FALSE
)

Arguments

Value

List with fitting results and final simulation

Format Statistics Text for Plots

Description

Creates formatted text blocks with key statistics for plot annotations.

Usage

format_statistics_text(stats, digits = 3, prefix = "")

Arguments

Value

Character vector of formatted text lines

Generate seasonal reproduction pattern (Low-level)

Description

Creates a simplified seasonal reproduction pattern

Usage

generate_reproduction_pattern(
  days,
  peak_day,
  duration,
  max_spawn_fraction,
  pattern_type = "gaussian"
)

Arguments

Value

Vector with reproductive fractions by day

Get Available Plot Types

Description

Returns list of available plot types for fb4_result objects.

Usage

get_available_plot_types(x)

Arguments

Value

Character vector of available plot types

Get Color Scheme for Plots

Description

Returns standardized color schemes for consistent plot styling.

Usage

get_color_scheme(scheme = "blue")

Arguments

Value

Named list of colors for different plot elements

Get consumption results with uncertainty

Description

Extracts consumption results from FB4 simulations with uncertainty propagation when available. Works with all fitting methods.

Usage

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

Arguments

Value

A named list with eight elements:

estimate

Numeric. Total consumption estimate (g) for the simulation period; NA when unavailable.

se

Numeric. Standard error of the estimate; NA for methods without uncertainty quantification (e.g. "direct", "binary_search", "optim").

ci_lower

Numeric. Lower bound of the confidence interval; NA when se is unavailable.

ci_upper

Numeric. Upper bound of the confidence interval; NA when se is unavailable.

method

Character. Fitting method used (e.g. "direct", "mle", "hierarchical").

backend

Character. Computational backend ("r" or "tmb").

has_uncertainty

Logical. TRUE when standard errors and confidence intervals are populated.

individual_id

As supplied; the requested individual index, or NULL for the population mean.

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)
consumption <- get_consumption_uncertainty(result)

Get efficiency results with uncertainty

Description

Extracts growth efficiency results from FB4 simulations with uncertainty propagation when available.

Usage

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

Arguments

Value

A named list with six elements:

gross_growth_efficiency

Named sub-list with estimate, se, ci_lower, and ci_upper for the gross growth efficiency (dimensionless ratio of growth energy to consumption energy); values are NA when unavailable.

metabolic_scope

Named sub-list with the same four slots for the metabolic scope (ratio of active to standard metabolism); values are NA when unavailable.

method

Character. Fitting method used.

backend

Character. Computational backend.

has_uncertainty

Logical. TRUE when SEs and CIs are populated.

individual_id

As supplied.

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)
eff <- get_efficiency_uncertainty(result)

Get energy budget components with uncertainty

Description

Extracts energy budget components from FB4 simulations with uncertainty propagation when available.

Usage

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

Arguments

Value

A named list with ten elements: six energy-component sub-lists (consumption_energy, respiration_energy, egestion_energy, excretion_energy, sda_energy, net_energy), each containing estimate, se, ci_lower, and ci_upper (all numeric, NA when unavailable); plus method (character), backend (character), has_uncertainty (logical), and individual_id (as supplied).

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 <- get_energy_budget_uncertainty(result)

Get individual results from hierarchical models

Description

Extracts all individual-level results from hierarchical FB4 models. Returns a comprehensive summary for each individual.

Usage

get_individual_results(result, confidence_level = 0.95)

Arguments

Value

A data.frame with one row per individual. Base columns are individual_id, p_estimate, and p_se. When individual uncertainty data are available the frame additionally contains *_est, *_se, *_ci_lower, and *_ci_upper columns for final_weight, consumption, total_growth, relative_growth, gross_efficiency, and metabolic_scope. Stops with an error if result was not produced by the hierarchical method.

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
# Individual results require a hierarchical run; shown here for illustration
# result <- run_fb4(bio, strategy = "hierarchical", ...)
# df <- get_individual_results(result)

Get Parameter Value from Species Parameters

Description

Retrieves a specific parameter value from species parameter lists, searching across all parameter categories.

Usage

get_parameter_value(params, param)

Arguments

Value

The value associated with param in the first category of params where it is found, or NULL if param is not present in any category. The type of the returned value matches the stored parameter (typically a numeric scalar).

Examples

sp <- list(consumption = list(CA = 0.303, CB = -0.275))
get_parameter_value(sp, "CA")
get_parameter_value(sp, "nonexistent")

Get population results from hierarchical models

Description

Extracts population-level results from hierarchical FB4 models. Returns means, standard errors, and population parameters.

Usage

get_population_results(result, confidence_level = 0.95)

Arguments

Value

A named list containing at minimum ten elements: mu_p_estimate and mu_p_se (population-mean ration), sigma_p_estimate and sigma_p_se (among-individual SD), sigma_obs_estimate and sigma_obs_se (observation SD), n_individuals (integer), log_likelihood, aic, and bic. When population uncertainty data are available, additional mean_*_est, mean_*_se, mean_*_ci_lower, and mean_*_ci_upper elements are appended for final_weight, consumption, total_growth, relative_growth, gross_efficiency, and metabolic_scope. Confidence-interval elements are also added for mu_p, sigma_p, and sigma_obs. Stops with an error if result was not produced by the hierarchical method.

Examples

# Population results require a hierarchical run; shown here for illustration
# result <- run_fb4(bio, strategy = "hierarchical", ...)
# pop <- get_population_results(result)

Check if result has uncertainty information

Description

Checks if fb4_result contains uncertainty information.

Usage

has_uncertainty(x)

Arguments

Value

Logical indicating if uncertainty data is available

Identify best performing scenarios

Description

Identifies the best performing scenario for each metric.

Usage

identify_best_scenarios(scenario_data, metrics)

Arguments

Value

List with best performers

Interpolate time series with error handling

Description

Interpolate time series with error handling

Usage

interpolate_time_series(
  data,
  value_columns,
  target_days,
  method = "linear",
  fill_na_method = "extend",
  validate_input = TRUE
)

Arguments

Value

A data.frame with one row per element of target_days. The first column is Day (integer). Subsequent columns correspond to value_columns, each containing the interpolated numeric values at the requested days. NA values are resolved according to fill_na_method: "extend" fills with the nearest valid value, "zero" replaces with 0, and "mean" uses the column mean.

Examples

temp_data <- data.frame(Day = c(1, 100, 200, 365),
                        Temperature = c(5, 15, 18, 7))
interpolate_time_series(temp_data, value_columns = "Temperature",
                        target_days = 1:365)

Test if Object is Bioenergetic

Description

Tests whether an object inherits from the Bioenergetic class.

Usage

is.Bioenergetic(x)

Arguments

Value

A length-1 logical: TRUE if x inherits from class "Bioenergetic", FALSE otherwise.

Examples

bio <- Bioenergetic(
  species_params = list(
    consumption = list(CEQ = 1, CA = 0.303, CB = -0.275, CQ = 0.06)
  ),
  species_info = list(common_name = "Example fish")
)
is.Bioenergetic(bio)
is.Bioenergetic(list())

Test if Object is fb4_result

Description

Tests whether an object inherits from the fb4_result class.

Usage

is.fb4_result(x)

Arguments

Value

A length-1 logical: TRUE if x inherits from class "fb4_result", FALSE otherwise.

Examples

is.fb4_result(list())

Log execution plan details

Description

Log execution plan details

Usage

log_execution_plan(plan)

Main Validation Functions for FB4

Description

Top-level validation functions that orchestrate all lower-level validators. validate_bioenergetic_for_simulation checks a Bioenergetic object for simulation readiness (structure, species equations, temperature/diet data, initial weight). validate_fb4_inputs extends this with strategy- and data-range checks before calling run_fb4. validate_fb4_system provides a multi-layer diagnostic report (basic, standard, comprehensive) with per-component pass/fail summaries.

Value

No return value; this page documents the main validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Maximum Likelihood Estimation for p_value using log-normal distribution

Description

Estimates p_value and uncertainty using observed final weights with a frequentist likelihood approach assuming log-normal weight distribution.

Usage

mle_estimate_p_value_lognormal(
  observed_weights,
  simulation_function,
  estimate_sigma = TRUE,
  fixed_sigma = 0.1
)

Arguments

Value

List with MLE results

Mortality and Reproduction Functions for FB4 Model

Description

Experimental functions for computing daily fish mortality and reproductive energy costs in the FB4 framework. Mortality is decomposed into natural, fishing, and predation components, with optional adjustments for thermal stress and starvation (weight-dependent). Reproduction is modelled as a seasonal spawn-fraction pattern that removes a fraction of body weight (and its associated energy) on each spawning day.

Note: Mortality rate tracking is not yet integrated into the main run_fb4() loop; spawning energy loss is.

Value

No return value; this page documents the mortality and reproduction functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Calculate negative log-likelihood for log-normal weight observations

Description

Calculates the negative log-likelihood for observed final weights assuming they follow a log-normal distribution around the predicted weight. Consistent with the TMB backend implementation.

Usage

neg_log_likelihood_lognormal(params, observed_weights, simulation_function)

Arguments

Value

Negative log-likelihood value (scalar)

Normalize diet proportions to sum to 1

Description

Normalize diet proportions to sum to 1

Usage

normalize_diet_proportions(diet_matrix)

Arguments

Value

Normalized diet matrix

Nutrient Regeneration Functions for FB4 Model

Description

Experimental functions for computing daily nitrogen (N) and phosphorus (P) fluxes in fish using a mass-balance approach consistent with ecological stoichiometry theory. For each element the daily budget is:

\text{Consumed} = \text{Assimilated} + \text{Egested}

\text{Assimilated} = \text{Growth} + \text{Excreted}

Assimilation efficiencies for N and P are species- and prey-specific and can differ from those used for energy.

Value

No return value; this page documents the nutrient regeneration functions module. See individual function documentation for return values.

References

Sterner, R.W. and Elser, J.J. (2002). Ecological Stoichiometry: The Biology of Elements from Molecules to the Biosphere. Princeton University Press, Princeton, NJ.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Compute efficiency metrics for a single nutrient

Description

Internal helper that calculates retention, excretion, and growth efficiencies from raw flux values. Used by calculate_nutrient_efficiencies() to avoid duplicating the identical calculation for nitrogen and phosphorus.

Usage

nutrient_efficiency_block(consumed, growth, excretion, assimilated)

Arguments

Value

Named list: retention_efficiency, excretion_rate, growth_efficiency.

Null-coalescing operator

Description

Returns x if it is not NULL, otherwise returns y. Equivalent to rlang::%||% but without requiring that dependency.

Usage

x %||% y

Arguments

Value

x if not NULL, otherwise y

Examples

NULL %||% "default"
"value" %||% "default"
list()$missing %||% 0

Optimization using optim() for optimal p_value

Description

Uses R's optim to find the p_value that minimises the absolute difference between the simulated metric and the target value.

Usage

optim_search_p_value(
  target_value,
  fit_type,
  simulation_function,
  method = "Brent",
  lower = 0.01,
  upper = 5,
  hessian = FALSE
)

Arguments

Value

List with fitted p_value and convergence information

Parameter Processing Functions for FB4

Description

Functions for validating, transforming, and enriching raw user-supplied species parameters before they are passed to the simulation engine. Each major bioenergetic category (consumption, respiration, egestion, excretion, predator energy density, contaminant, nutrient, mortality, body composition) has a dedicated processor that (i) checks that the required parameters for the chosen equation are present, (ii) computes derived values (e.g., CX/CY/CZ for CEQ 2, gill efficiency for CONTEQ 3), and (iii) fills missing optional parameters with documented defaults. The top-level entry point is process_species_parameters.

Value

No return value; this page documents the parameter processing functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Parameter Validation Functions for FB4

Description

Parameter validation functions built on top of the core validators in core-validators. Covers species-equation validation (validate_species_equations), predator energy density (validate_predator_energy_params), contaminant parameters (validate_contaminant_params), nutrient concentrations (validate_nutrient_concentrations), and body composition (validate_body_composition). A central EQUATION_REQUIREMENTS registry stores the required parameters and valid ranges for each bioenergetic equation.

Value

No return value; this page documents the parameter validation functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Perform statistical tests between scenarios

Description

Performs statistical comparisons between scenarios when uncertainty estimates are available.

Usage

perform_scenario_tests(scenario_data, metrics)

Arguments

Value

List with test results

Plot Bioenergetic object setup

Description

Plotting method for Bioenergetic objects to validate setup before simulation.

Usage

## S3 method for class 'Bioenergetic'
plot(x, type = "dashboard", save_plot = NULL, ...)

Arguments

Value

Invisibly returns the input object x, called for its plotting side-effect.

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
plot(bio)
plot(bio, type = "temperature")

Plot FB4 simulation results

Description

Main plotting method for fb4_result objects. Automatically detects available data and provides appropriate visualizations.

Usage

## S3 method for class 'fb4_result'
plot(x, type = "dashboard", save_plot = NULL, ...)

Arguments

Value

Invisibly returns the input object x, called for its plotting side-effect.

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)
plot(result)
plot(result, type = "growth")

Plot Bioenergetic dashboard

Description

Plot Bioenergetic dashboard

Usage

plot_bio_dashboard(bio_obj, colors = "blue", title = NULL, ...)

Plot Bioenergetic diet

Description

Plot Bioenergetic diet

Usage

plot_bio_diet(bio_obj, colors = "green", max_prey = 5, ...)

Plot Bioenergetic energy

Description

Plot Bioenergetic energy

Usage

plot_bio_energy(bio_obj, colors = "purple", ...)

Plot Bioenergetic temperature

Description

Plot Bioenergetic temperature

Usage

plot_bio_temperature(bio_obj, colors = "red", ...)

Plot bootstrap distributions

Description

Internal function for bootstrap distribution plotting.

Usage

plot_bootstrap_distributions(fb4_result, colors)

Arguments

Plot bootstrap uncertainty

Description

Internal function for bootstrap uncertainty plotting.

Usage

plot_bootstrap_uncertainty(fb4_result, parameters, colors, add_ci_text)

Arguments

Plot consumption patterns

Description

Creates consumption rate plots with optional cumulative consumption.

Usage

plot_consumption(fb4_result, show_cumulative = TRUE, colors = "green", ...)

Arguments

Value

NULL (creates plot)

Create dashboard overview

Description

Creates a 4-panel dashboard showing key simulation results.

Usage

plot_dashboard(fb4_result, colors = "blue", title = NULL, ...)

Arguments

Value

NULL (creates plot)

Plot parameter distributions for bootstrap and hierarchical methods

Description

Shows distributions of parameters from bootstrap samples or hierarchical individual estimates.

Usage

plot_distributions.fb4_result(
  fb4_result,
  color_scheme = "green",
  show_individuals = TRUE
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

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
set.seed(42)
obs_weights <- rnorm(10, mean = 90, sd = 5)
result_boot <- run_fb4(bio, strategy = "bootstrap", fit_to = "Weight",
                       observed_weights = obs_weights, n_bootstrap = 20,
                       verbose = FALSE)
plot_distributions.fb4_result(result_boot)

Plot energy budget components

Description

Creates energy component plots with optional efficiency subplot.

Usage

plot_energy(
  fb4_result,
  components = NULL,
  show_efficiency = TRUE,
  colors = "purple",
  ...
)

Arguments

Value

NULL (creates plot)

Draw a single parameter estimate panel with confidence interval

Description

Internal helper shared by plot_mle_uncertainty, plot_bootstrap_uncertainty, and plot_hierarchical_uncertainty. Draws a dot-and-arrow panel for one parameter — estimate point, CI arrow, and optional CI text — so the identical plotting code is not triplicated.

Usage

plot_estimate_panel(
  estimate,
  ci_lower,
  ci_upper,
  param_name,
  method_label,
  colors,
  add_ci_text
)

Arguments

Value

NULL (modifies current graphics device).

Plot growth trajectory

Description

Creates growth trajectory plots with optional growth rate subplot.

Usage

plot_growth(fb4_result, show_rate = TRUE, colors = "blue", smooth = FALSE, ...)

Arguments

Value

NULL (creates plot)

Plot sensitivity analysis

Description

Creates sensitivity analysis plots for temperature and feeding effects.

Usage

plot_growth_temperature_sensitivity(
  sensitivity_data,
  temperatures = seq(5, 20, by = 2),
  feeding_levels = c(0.5, 0.75, 1),
  species = NULL,
  ylim = NULL,
  xlim = NULL,
  colors = "grayscale",
  verbose = FALSE,
  ...
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

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
sens_data <- analyze_growth_temperature_sensitivity(
  bio_obj         = bio,
  temperatures    = c(10, 14),
  p_values        = c(0.4, 0.7),
  simulation_days = 30,
  verbose         = FALSE
)
plot_growth_temperature_sensitivity(sens_data, species = "Chinook")

Plot growth rate vs temperature

Description

Creates growth vs temperature plots for sensitivity analysis.

Usage

plot_growth_vs_temperature(
  sensitivity_data,
  fb4_result,
  color_scheme = "grayscale",
  add_annotations = TRUE,
  ...
)

Arguments

Value

NULL (creates plot)

Plot hierarchical distributions

Description

Internal function for hierarchical distribution plotting.

Usage

plot_hierarchical_distributions(fb4_result, colors, show_individuals)

Arguments

Plot hierarchical uncertainty

Description

Internal function for hierarchical uncertainty plotting.

Usage

plot_hierarchical_uncertainty(fb4_result, parameters, colors, add_ci_text)

Arguments

Plot MLE uncertainty

Description

Internal function for MLE uncertainty plotting.

Usage

plot_mle_uncertainty(fb4_result, parameters, colors, add_ci_text)

Arguments

Plot temperature sensitivity analysis for a Bioenergetic object

Description

Runs analyze_growth_temperature_sensitivity and plots the result. Sensitivity analysis requires a Bioenergetic object (not an fb4_result), because it re-runs the model across a grid of temperatures and p_values. Use plot(bio_obj, type = "sensitivity") as the primary interface; this function is the underlying implementation.

Usage

plot_sensitivity.fb4_result(
  bio_obj,
  temperatures = seq(4, 20, by = 2),
  p_values = seq(0.3, 1, by = 0.1),
  simulation_days = 365,
  color_scheme = "grayscale",
  add_annotations = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

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
plot_sensitivity.fb4_result(
  bio_obj         = bio,
  temperatures    = c(10, 14),
  p_values        = c(0.4, 0.7),
  simulation_days = 30,
  verbose         = FALSE
)

Plot temperature profile

Description

Creates temperature plots with optional consumption correlation.

Usage

plot_temperature(
  fb4_result,
  show_correlation = TRUE,
  colors = "red",
  smooth = TRUE,
  ...
)

Arguments

Value

NULL (creates plot)

Plot parameter uncertainty for probabilistic methods

Description

Creates plots showing parameter estimates with confidence intervals. Adapts automatically to the method used (MLE, bootstrap, hierarchical).

Usage

plot_uncertainty.fb4_result(
  fb4_result,
  parameters = "all",
  color_scheme = "blue",
  add_ci_text = TRUE
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

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
set.seed(42)
obs_weights <- rnorm(10, mean = 90, sd = 5)
result_mle <- run_fb4(bio, strategy = "mle", fit_to = "Weight",
                      observed_weights = obs_weights, verbose = FALSE)
plot_uncertainty.fb4_result(result_mle)

Predator Energy Density Functions for FB4 Model

Description

Functions implementing three predator energy density models (PREDEDEQ 1–3) and the corresponding weight-solving routines used in the FB4 energy balance.

PREDEDEQ 1 — interpolated daily data: energy density supplied as a vector of length n_{\text{days}} + 1 (one value per day boundary).

PREDEDEQ 2 — piecewise linear by weight: ED = \alpha_1 + \beta_1 W below the cutoff, ED = \alpha_2 + \beta_2 W above.

PREDEDEQ 3 — power function: ED = \alpha_1 \cdot W^{\beta_1}.

Value

No return value; this page documents the predator energy density functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Energy density from interpolated data - Equation 1 (Low-level)

Description

Retrieves energy density from pre-calculated daily data. The function accesses both energy_data[day] (start of day) and energy_data[day + 1] (end of day) during weight calculations, so the vector must have n_days + 1 elements (e.g., 366 for a 365-day simulation: indices 1 to 366 represent days 0 to 365).

Usage

predator_energy_eq1(weight, day, energy_data)

Arguments

Value

Energy density (J/g)

Linear piecewise energy density - Equation 2 (Low-level)

Description

Two-segment linear relationship between weight and energy density

Usage

predator_energy_eq2(weight, Alpha1, Beta1, Alpha2, Beta2, Cutoff)

Arguments

Value

Energy density (J/g)

Power function energy density - Equation 3 (Low-level)

Description

Power relationship between weight and energy density

Usage

predator_energy_eq3(weight, Alpha1, Beta1)

Arguments

Value

Energy density (J/g)

Bootstrap method for consumption uncertainty propagation

Description

Propagates p-value uncertainty to consumption predictions using parametric bootstrap. Generates multiple samples from the p-value distribution and runs FB4 simulations for each sample. Provides full uncertainty distribution without linearity assumptions. Supports parallel processing for improved performance.

Usage

predict_consumption_bootstrap(
  p_mean,
  p_sd,
  bio_obj,
  n_sims = 1000,
  first_day = 1,
  last_day = 365,
  parallel = FALSE,
  n_cores = NULL,
  confidence_level = 0.95,
  verbose = FALSE
)

Arguments

Details

The bootstrap method: 1. Samples p-values from Normal(p_mean, p_sd) 2. Constrains samples to valid range [0.01, 5.0] 3. Runs FB4 simulation for each p-value sample 4. Summarizes consumption distribution

Parallel processing can significantly reduce computation time for large n_sims. The method handles simulation failures gracefully and reports success rates.

Value

A named list with elements:

method

Character string "bootstrap".

consumption_mean

Mean total consumption across bootstrap samples (g).

consumption_sd

Standard deviation of consumption across samples (g).

consumption_ci

Numeric vector of length 2 with lower and upper quantile-based confidence interval bounds (g).

consumption_samples

Numeric vector of all successful consumption estimates from bootstrap samples.

n_successful

Number of bootstrap iterations that produced valid consumption estimates.

p_mean

The supplied p_mean value.

p_sd

The supplied p_sd value.

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
uncertainty_result <- predict_consumption_bootstrap(
  p_mean   = 0.5,
  p_sd     = 0.05,
  bio_obj  = bio,
  n_sims   = 20,
  last_day = 30
)

Delta method for consumption uncertainty propagation

Description

Propagates p-value uncertainty to consumption predictions using the delta method. Computes numerical derivatives and applies first-order approximation for uncertainty propagation. Suitable when the relationship between p and consumption is approximately linear.

Usage

predict_consumption_delta(
  p_est,
  p_se,
  bio_obj,
  delta_size = 0.001,
  first_day = 1,
  last_day = 365,
  verbose = FALSE
)

Arguments

Details

The delta method uses first-order Taylor series approximation: Var(f(X)) ~ [f'(mu)]^2 * Var(X)

The linearity check verifies that the derivative times delta_size is small relative to the consumption estimate, indicating local linearity.

Value

A named list with elements:

method

Character string "delta".

consumption_est

Point estimate of total consumption (g).

consumption_se

Standard error of consumption estimate (g).

consumption_ci

Numeric vector of length 2 with lower and upper confidence interval bounds (g).

derivative

Numerical derivative of consumption with respect to p.

linearity_check

Logical; TRUE if the linearity assumption appears satisfied.

p_est

The supplied p_est value.

p_se

The supplied p_se value.

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
uncertainty_result <- predict_consumption_delta(
  p_est    = 0.5,
  p_se     = 0.05,
  bio_obj  = bio,
  last_day = 30
)

Prepare all simulation data

Description

Master function that processes and validates ALL data required for FB4 simulation. Combines species parameter processing with temporal data processing.

Usage

prepare_simulation_data(
  bio_obj,
  strategy,
  fit_to = NULL,
  fit_value = NULL,
  first_day = 1,
  last_day = NULL,
  validate_inputs = TRUE,
  oxycal = 13560,
  output_format = "simulation",
  observed_weights = NULL,
  covariates = NULL
)

Arguments

Value

For output_format = "simulation" (default), a named list with seven elements: species_params (processed species parameter sub-lists), temporal_data (processed temporal arrays), simulation_settings (processed settings), metadata (processing timestamp, duration, prey species, data sources), n_days (integer), temperatures (numeric vector), and initial_weight (numeric scalar). For output_format = "tmb_basic" or "tmb_hierarchical", returns a list formatted for TMB model fitting (structure differs).

Examples

# Requires a fully-configured Bioenergetic object; see ?Bioenergetic
# bio <- Bioenergetic(...)
# sim_data <- prepare_simulation_data(bio, strategy = "direct")

Print Method for Bioenergetic Objects

Description

Displays a concise one-page overview of a Bioenergetic object, including species identity, initial weight, simulation duration, and the status of each required component (parameters, temperature, diet). Readiness for fitting is reported in the final status line.

Usage

## S3 method for class 'Bioenergetic'
print(x, ...)

Arguments

Value

Invisibly returns the input object

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)
)
print(bio)

Print Method for fb4_result Objects

Description

Displays a concise summary of an fb4_result object. The output adapts to the fitting method used: traditional methods (binary search, optim, direct) show weight, growth, consumption, and convergence; "mle" shows parameter estimates with confidence intervals and AIC; "bootstrap" shows mean/SD estimates and CI; and "hierarchical" shows population-level parameters with model fit statistics.

Usage

## S3 method for class 'fb4_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object

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)
print(result)

Process Bioenergetic object temporal data for simulation

Description

Version that processes all temporal data required for FB4 simulation. Includes better error handling and additional data types.

Usage

process_bioenergetic_data(bio_obj, first_day, last_day)

Arguments

Value

A named list with ten elements containing the temporal arrays interpolated to each simulation day: temperature (numeric vector, °C), diet_proportions (numeric matrix, rows = days, columns = prey), prey_energies (numeric matrix, J/g), prey_indigestible (numeric matrix, fractions), reproduction (numeric vector, fractions), duration (integer, number of days), prey_names (character vector), first_day, last_day, and target_days (integer sequence of simulated days).

Examples

# Requires a fully-configured Bioenergetic object; see ?Bioenergetic
# bio <- Bioenergetic(...)
# temporal <- process_bioenergetic_data(bio, first_day = 1, last_day = 365)

Process body composition parameters

Description

Process body composition parameters

Usage

process_composition_params(composition_params)

Arguments

Value

A list containing all elements of composition_params with missing entries filled with defaults: water_fraction = 0.75, fat_energy = 39500 (J/g), protein_energy = 23600 (J/g), and max_fat_fraction = 0.25.

Examples

process_composition_params(list(water_fraction = 0.72))

Process consumption parameters

Description

Process consumption parameters

Usage

process_consumption_params(consumption_params)

Arguments

Value

A list containing all elements of consumption_params plus derived values required by the selected equation: CX, CY, CZ for CEQ 2 (Kitchell et al. 1977); CG1, CG2 for CEQ 3 (Thornton and Lessem 1978). For CEQ 1 and CEQ 4 the input list is returned unchanged after validation.

Examples

process_consumption_params(list(CEQ = 1, CA = 0.303, CB = -0.275, CQ = 0.06))

Process contaminant parameters

Description

Process contaminant parameters

Usage

process_contaminant_params(contaminant_params)

Arguments

Value

A list containing all elements of contaminant_params. For CONTEQ 3 (Arnot and Gobas 2004), three additional elements are computed when not already present: gill_efficiency (dimensionless), fish_water_partition (dimensionless), and dissolved_fraction (dimensionless). For CONTEQ 1 and 2 the list is returned after validation unchanged.

Examples

process_contaminant_params(list(
  CONTEQ = 1,
  prey_concentrations  = c(0.05, 0.08),
  transfer_efficiency  = c(0.80, 0.80)
))

Process egestion parameters

Description

Process egestion parameters

Usage

process_egestion_params(egestion_params)

Arguments

Value

A list identical to egestion_params after validation. No additional derived values are computed; the function ensures the required parameters for the selected EGEQ are present and valid.

Examples

process_egestion_params(list(EGEQ = 1, FA = 0.16))

Process excretion parameters

Description

Process excretion parameters

Usage

process_excretion_params(excretion_params)

Arguments

Value

A list identical to excretion_params after validation. No additional derived values are computed; the function ensures the required parameters for the selected EXEQ are present and valid.

Examples

process_excretion_params(list(EXEQ = 1, UA = 0.10))

Process mortality parameters

Description

Process mortality parameters

Usage

process_mortality_params(mortality_params)

Arguments

Value

A list containing all elements of mortality_params with missing entries filled with defaults: base_mortality = 0.001, natural_mortality (copied from base_mortality), fishing_mortality = 0, predation_mortality = 0, optimal_temp = 15, thermal_tolerance = 5, and stress_factor = 2. If a reproduction sub-list is present, a spawn_pattern numeric vector (length 365) is appended.

Examples

process_mortality_params(list(base_mortality = 0.001,
                              natural_mortality = 0.001))

Process nutrient parameters

Description

Process nutrient parameters

Usage

process_nutrient_params(nutrient_params)

Arguments

Value

A list containing all elements of nutrient_params. Default assimilation efficiencies are inserted when absent: n_assimilation_efficiency = 0.85 and p_assimilation_efficiency = 0.80 (with a warning in each case).

Examples

process_nutrient_params(list(
  prey_n_concentrations    = c(0.025, 0.030),
  prey_p_concentrations    = c(0.004, 0.005),
  predator_n_concentration = 0.030,
  predator_p_concentration = 0.004
))

Process predator energy data for equation 1 (PREDEDEQ = 1)

Description

Ensures ED_data is available as a numeric vector of length n_days + 1. Accepts either a pre-built vector via ED_data or a pair of scalars via ED_ini/ED_end (which are linearly interpolated to produce the full vector internally).

Usage

process_predator_energy_data(predator_params)

Arguments