Learn R Programming

fb4package

An R implementation of Fish Bioenergetics 4.0 (Deslauriers et al. 2017). The model partitions consumed energy among metabolism, waste, and growth to produce daily estimates of fish consumption and weight gain.

Installation

# Development version from GitHub
devtools::install_github("HansTtito/fb4package")

Usage

library(fb4package)

data(fish4_parameters)
chinook <- fish4_parameters[["Oncorhynchus tshawytscha"]]

bio <- Bioenergetic(
  species_params     = chinook$life_stages$adult,
  species_info       = chinook$species_info,
  environmental_data = list(
    temperature = data.frame(Day = 1:100,
                             Temperature = 10 + 5 * sin(2 * pi * (1:100) / 365))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:100, Alewife = 0.7, Shrimp = 0.3),
    prey_names  = c("Alewife", "Shrimp"),
    energies    = data.frame(Day = 1:100, Alewife = 4900, Shrimp = 3200)
  ),
  simulation_settings = list(initial_weight = 1800, duration = 100)
)

# Fit p to a target final weight
res <- run_fb4(bio, strategy = "binary_search", fit_to = "Weight", fit_value = 3000)
print(res)

Full documentation, vignettes, and function reference are available at https://hansttito.github.io/fb4package/.

Documentation

Reference

Deslauriers D, Chipps SR, Breck JE, Rice JA, Madenjian CP (2017). Fish Bioenergetics 4.0: An R-Based Modeling Application. Fisheries 42(11):586–596. https://doi.org/10.1080/03632415.2017.1377558

Code of Conduct

Please note that fb4package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

MIT

Copy Link

Version

Install

install.packages('fb4package')

Version

2.0.0

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Hans Ttito

Last Published

May 7th, 2026

Functions in fb4package (2.0.0)

EQUATION_REQUIREMENTS

Equation requirements for all FB4 components
FB4Strategy

FB4 Strategy Interface
analyze_composition_by_size

Analyze body composition by size range
analyze_composition_changes

Analyze composition changes with growth
analyze_growth_patterns

Analyze growth patterns from FB4 results
build_composition_df

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

S3 Classes for FB4 Bioenergetic Model
binary_search_p_value

Binary search for optimal p_value
analysis-nutritional

Nutritional Analysis Functions for FB4 Results
calculate_consumption

Calculate daily consumption (Mid-level - Main function)
analyze_energy_budget

Analyze energy budget from FB4 results
calculate_daily_consumption

Calculate daily consumption with multiple methods (Low-level)
calculate_consumption_params_eq2

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

Sensitivity and Comparative Analysis Functions for FB4 Results
analyze_population_variation

Analyze population variation in hierarchical models
calculate_daily_metabolism

Calculate daily metabolic processes (Low-level)
analyze_feeding_performance

Analyze feeding performance from FB4 results
build_tmb_uncertainty

Build TMB uncertainty list for MLE results
build_fb4_result_unified

Build FB4 result object
calculate_body_composition

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

Assess nutritional quality of diet
calculate_np_ratios

Calculate N:P ratios for all processes
calculate_temperature_factor_respiration

Calculate temperature factor for respiration (Mid-level)
bootstrap_p_values

Bootstrap estimation of p_values with optional parallel processing
calculate_respiration_params_eq2

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

Generic nutrient allocation in bioenergetic model (Low-level)
bootstrap_single_iteration

Execute a single bootstrap iteration
analyze_growth_temperature_sensitivity

Analyze growth rate sensitivity to temperature and feeding levels
calculate_sda

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

Calculate weight-dependent mortality (Low-level)
calculate_combined_survival

Calculate combined daily survival (Low-level)
calculate_component_from_water

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

Body Composition Functions for FB4 Model
bioenergetic-methods

Methods for FB4 Bioenergetic Model
calculate_confidence_intervals

Confidence interval from estimate and standard error
build_population_uncertainty

Build population-level uncertainty list for hierarchical results
build_individual_uncertainty

Build individual-level uncertainty list for hierarchical results
calculate_daily_spawn_energy

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

Calculate fat content by subtraction (Low-level)
calculate_dissolved_fraction

Calculate dissolved fraction of contaminant (Low-level)
calculate_daily_weight_change

Calculate daily weight change (Low-level)
assign_energy_components

Fill energy budget components from a named source list
calculate_egestion

Calculate daily egestion (Mid-level - Main function)
calculate_mortality_reproduction

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

Check TMB model availability (simplified for installed package)
check_target_achievement

Check if target was achieved for traditional methods
calculate_growth_metrics

Calculate Basic Growth Metrics
calculate_final_weight_fb4

Calculate final weight using FB4 equations (Mid-level)
calculate_nutrient_balance

Calculate nutrient balance (Mid-level - Main function)
calculate_nutrient_efficiencies

Calculate nutrient retention efficiencies
calculate_reproductive_loss

Calculate reproductive weight loss (Low-level)
calculate_activity_factor_respiration

Calculate activity factor for respiration (Mid-level)
consumption-functions

Consumption Functions for FB4 Model
calculate_respiration

Calculate daily respiration (Mid-level - Main function)
convert_daily_results_to_dataframe

Convert list of daily results to data frame
contaminant_model_3

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

Calculate temperature-dependent mortality (Low-level)
consumption_temp_eq1

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

Create empty composition for invalid inputs (Utility)
check_bioenergetic_readiness

Check Bioenergetic Object Readiness
calculate_temperature_factor_consumption

Calculate temperature factor for consumption (Mid-level)
basic-validators

Basic Validation Functions for FB4
check_numeric_value

Check Numeric Value
contaminant-accumulation

Contaminant Accumulation Functions for FB4 Model
calculate_predator_energy_density

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

Calculate daily excretion (Mid-level - Main function)
calculate_progress_interval

Calculate appropriate progress reporting interval
consumption_temp_eq4

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

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

Comprehensive nutritional analysis
calculate_contaminant_accumulation

Calculate contaminant accumulation (Mid-level - Main function)
compare_individuals

Compare individuals from hierarchical models
close_save_device

Close graphics device after saving
create_error_result

Create standardized error result
calculate_consumption_params_eq3

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

Compare multiple FB4 results
compare_with_redfield

Compare N:P ratios with Redfield ratios
detect_method

Detect method from raw results or execution plan
create_individual_rankings

Create individual rankings across metrics
create_bootstrap_strategy

Create Bootstrap Strategy
create_direct_strategy

Create Direct Strategy
convert_respiration_to_energy

Convert respiration from O2 to energy units (Utility)
convert_to_individual_data

Convert hierarchical observed_weights to individual_data format
calculate_fish_water_partition

Calculate fish:water partition coefficient (Low-level)
data-processing

Data Processing Functions for FB4
data-validators

Data Validation Functions for FB4
create_unified_fit_info

Create unified fit info section
create_unified_summary

Build the $summary slot of an fb4_result object
compute_likelihood_profile

Compute likelihood profile for p_value
create_individual_summary

Create summary statistics for individual metric
create_mle_strategy

Create MLE Strategy
core-validators

Core Validation Functions for FB4
create_method_specific_data

Create method-specific data section
create_optim_strategy

Create Optim Strategy
create_result_summary

Comprehensive post-simulation analysis summary
egestion_model_2

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

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

Calculate spawning energy loss (Low-level)
fit_fb4_binary_search

Fit FB4 model using binary search
calculate_gill_efficiency

Calculate gill uptake efficiency (Low-level)
mortality-reproduction

Mortality and Reproduction Functions for FB4 Model
calculate_stoichiometric_balance

Calculate stoichiometric balance
fit_fb4_bootstrap

Fit FB4 model using bootstrap estimation with parallel option
neg_log_likelihood_lognormal

Calculate negative log-likelihood for log-normal weight observations
excretion_model_4

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

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

Clamp values to a range
consumption_temp_eq3

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

Extract common strategy parameters from execution plan
check_weight_outliers

Check for outliers in weight data
get_parameter_value

Get Parameter Value from Species Parameters
extract_tmb_results

Extract comprehensive results from TMB optimization
fish4_parameters

Fish Bioenergetics 4.0 Official Parameters Database
fish4_parameters_metadata

Fish Bioenergetics 4.0 Parameters Database Metadata
get_population_results

Get population results from hierarchical models
parameter-validators

Parameter Validation Functions for FB4
create_binary_search_strategy

Create Binary Search Strategy
execute_daily_simulation

Execute single day simulation (Mid-level)
extract_basic_parameters

Extract parameters for basic model
contaminant_model_1

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

Execute MLE TMB using unified architecture
detect_result_type

Detect method and backend from fb4_result
extract_hierarchical_parameters

Extract parameters for hierarchical model
perform_scenario_tests

Perform statistical tests between scenarios
execute_hierarchical_tmb

Execute hierarchical TMB using unified architecture and shared commons
plot_bootstrap_distributions

Plot bootstrap distributions
create_hierarchical_strategy

Create Hierarchical Strategy
create_fb4_strategy

Create FB4 strategy based on method
contaminant_model_2

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

Plot bootstrap uncertainty
egestion-excretion

Egestion and Excretion Functions for FB4 Model
egestion_model_1

Egestion model 1 - Basic (Low-level)
create_execution_summary

Create execution summary for verbose output
extract_species_name

Extract Species Information for Titles
create_execution_plan

Create execution plan for FB4 strategies
log_execution_plan

Log execution plan details
extract_data_sources

Extract data sources from bioenergetic object
egestion_model_4

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

Excretion model 1 - Basic (Low-level)
execute_simulation_with_method

Execute simulation with any method
is.fb4_result

Test if Object is fb4_result
op-null-default

Null-coalescing operator
nutrient_efficiency_block

Compute efficiency metrics for a single nutrient
plot_consumption

Plot consumption patterns
plot_dashboard

Create dashboard overview
plot_hierarchical_distributions

Plot hierarchical distributions
extract_adreport_values

Extract ADREPORT values from TMB report
fit_fb4_mle

Fit FB4 model using Maximum Likelihood Estimation
fb4-analysis-plots

Analysis Plots for FB4 Results (Uncertainty and Sensitivity)
fb4-bioenergetic-plots

Bioenergetic Object Plots for Setup Validation
fit_fb4_optim

Fit FB4 model using optim()
excretion_model_2

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

Get Available Plot Types
excretion_model_3

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

FB4 Plotting Functions
predator-energy-density

Predator Energy Density Functions for FB4 Model
plot_hierarchical_uncertainty

Plot hierarchical uncertainty
fb4package-package

Fish Bioenergetics 4.0 Package
fb4-plot-core

Core Plotting Functions for FB4 Results
fb4-daily-plots

Daily Simulation Plots for FB4 Results
get_energy_budget_uncertainty

Get energy budget components with uncertainty
get_individual_results

Get individual results from hierarchical models
plot_growth_temperature_sensitivity

Plot sensitivity analysis
print.fb4_result

Print Method for fb4_result Objects
plot_growth_vs_temperature

Plot growth rate vs temperature
predator_energy_eq1

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

Format Statistics Text for Plots
get_color_scheme

Get Color Scheme for Plots
nutrient-regeneration

Nutrient Regeneration Functions for FB4 Model
main-validators

Main Validation Functions for FB4
plot_distributions.fb4_result

Plot parameter distributions for bootstrap and hierarchical methods
generate_reproduction_pattern

Generate seasonal reproduction pattern (Low-level)
normalize_diet_proportions

Normalize diet proportions to sum to 1
predict_consumption_delta

Delta method for consumption uncertainty propagation
predict_consumption_bootstrap

Bootstrap method for consumption uncertainty propagation
plot_energy

Plot energy budget components
mle_estimate_p_value_lognormal

Maximum Likelihood Estimation for p_value using log-normal distribution
plot_uncertainty.fb4_result

Plot parameter uncertainty for probabilistic methods
prepare_simulation_data

Prepare all simulation data
print.Bioenergetic

Print Method for Bioenergetic Objects
process_bioenergetic_data

Process Bioenergetic object temporal data for simulation
process_excretion_params

Process excretion parameters
process_reproduction_pattern

Process reproduction pattern
plot_temperature

Plot temperature profile
process_contaminant_params

Process contaminant parameters
process_egestion_params

Process egestion parameters
respiration_temp_eq1

Temperature function for respiration - Equation 1 (Low-level)
set_parameter_value

Set Parameter Value in Species Parameters
result-builders-unified

Result Builders for FB4 Model
process_respiration_params

Process respiration parameters
get_consumption_uncertainty

Get consumption results with uncertainty
run-fb4-orchestrator

FB4 Main Orchestrator
run_final_simulation

Run final simulation with optimal parameter
process_predator_params

Process predator energy density parameters
run_robust_optimization

Run robust optimization with multiple fallback strategies
respiration_temp_eq2

Temperature function for respiration - Equation 2 (Low-level)
is.Bioenergetic

Test if Object is Bioenergetic
interpolate_time_series

Interpolate time series with error handling
get_efficiency_uncertainty

Get efficiency results with uncertainty
has_uncertainty

Check if result has uncertainty information
optim_search_p_value

Optimization using optim() for optimal p_value
process_mortality_params

Process mortality parameters
plot.Bioenergetic

Plot Bioenergetic object setup
identify_best_scenarios

Identify best performing scenarios
set_simulation_settings

Set Simulation Settings for Bioenergetic Objects
transform_to_tmb_basic

Transform simulation data to TMB basic format
validate_range_core

Core range validation with multiple strategies
transform_to_tmb_hierarchical

Transform simulation data to TMB hierarchical format
solve_weight_iterative

Solve weight using iterative method (Mid-level)
validate_temporal_data

Validate temporal data
validate_respiration_requirements

Validate respiration requirements (multiple categories)
validate_time_series_data

Validate Time Series Data Structure (Basic Level)
process_reproduction_data

Process reproduction data
plot.fb4_result

Plot FB4 simulation results
respiration-functions

Respiration Functions for FB4 Model
run_single_optimization

Run single optimization attempt
report_simulation_summary

Report final simulation summary
run_fb4_simulation

Run complete FB4 simulation (Mid-level - Main function)
safe_sqrt

Safe square root
run_fb4_direct_method

Run FB4 with direct method
safe_extract_param

Safe parameter extraction with defaults
sdr_pull_se

Pull a scalar standard error from an sdreport summary
safe_exp

Safe exponential
should_mark_as_fitted

Determine if bio_obj should be marked as fitted
strategy-bootstrap

Bootstrap Estimation Strategy for FB4 Model
update_body_composition

Update body composition during simulation (Mid-level)
sdr_pull_vec

Pull a vector of estimates and SEs from an sdreport summary
uncertainty-prediction

FB4 Uncertainty Propagation Functions
summary.Bioenergetic

Summary Method for Bioenergetic Objects
strategy-commons

Strategy Commons for FB4 Model
strategy-optim

Optimisation Strategy for FB4 Model
validate_fraction

Validate fraction values (0-1 range)
simulation-engine

Simulation Engine for FB4 Model
validate_fitting_settings

Validate fitting settings
summary.fb4_result

Summary Method for fb4_result Objects
parameter-processing

Parameter Processing Functions for FB4
plot_bio_diet

Plot Bioenergetic diet
plot_bio_dashboard

Plot Bioenergetic dashboard
plot_bio_energy

Plot Bioenergetic energy
solve_weight_linear_segments

Solve weight for linear segments (Low-level)
plot_estimate_panel

Draw a single parameter estimate panel with confidence interval
plot_growth

Plot growth trajectory
validate_basic_params

Validate Basic Model Parameters
predator_energy_eq2

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

Test differences between metric estimates
validate_diet_consistency

Validate Consistency Between Diet and Energy Data
validate_common_strategy_inputs

Validate common strategy inputs
validate_complete_simulation_data

Validate complete simulation data
plot_mle_uncertainty

Plot MLE uncertainty
plot_bio_temperature

Plot Bioenergetic temperature
validate_predator_energy_params

Validate predator energy density parameters
validation_result

Create standardized validation result
validate_predator_requirements

Validate predator requirements (special data handling)
validate_equation_params

Validate equation parameters against requirements
validate_contaminant_params

Validate contaminant parameters
validate_bioenergetic_for_simulation

Comprehensive validation for Bioenergetic objects
validate_data_consistency

Validate data consistency between components
validate_tmb_objective

Validate TMB objective function
validate_plot_data

Validate Plot Data Availability
process_simulation_settings

Process simulation settings
process_consumption_params

Process consumption parameters
process_composition_params

Process body composition parameters
process_nutrient_params

Process nutrient parameters
plot_sensitivity.fb4_result

Plot temperature sensitivity analysis for a Bioenergetic object
predator_energy_eq3

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

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

Process single temperature with all p-values
validate_positive

Validate positive values
validate_species_equations

Main function to validate all species equations
set_diet

Set Diet Data for Bioenergetic Objects
report_simulation_progress

Report simulation progress
validate_statistical_method_inputs

Validate statistical strategy inputs
strategy-binary-search

Binary Search Strategy for FB4 Model
run_fb4

Run FB4 Simulation
set_environment

Set Environmental Data for Bioenergetic Objects
process_species_parameters

Process all species parameters for simulation
run_fb4.Bioenergetic

Run FB4 simulation on Bioenergetic object
solve_weight_power_function

Solve weight for power function (Low-level)
strategy-direct

Direct Strategies for FB4 Model
sdr_assign_scalars

Batch-assign scalar estimate/SE pairs to a results list
utils

Utility Functions for fb4package
strategy-hierarchical

Hierarchical Estimation Strategy for FB4 Model
validate_backend_compatibility

Validate backend compatibility
setup_plot_layout

Setup Plot Layout
sdr_pull_est

Pull a scalar estimate from an sdreport summary
setup_save_device

Setup graphics device for saving
validate_fb4_inputs

Validate inputs for FB4 simulation
validate_fb4_result

Validate unified result object structure
validate_individual_data

Validate individual data for hierarchical models
validate_numeric_core

Core numeric validation with flexible handling strategies
validate_category_equation

Validate equation parameters for a specific category
validate_fb4_system

Validate complete FB4 system ready for simulation
strategy-mle

Maximum Likelihood Estimation Strategy for FB4 Model
strategy-interface

Strategy Interface and Factory for FB4 Model
validate_body_composition

Validate body composition
validate_fit_to_strategy_concordance

Validate concordance between fit_to and strategy parameters
validate_nutrient_concentrations

Validate nutrient concentrations
validate_temperature

Validate temperature values
validate_structure_core

Core data structure validation
validate_parameter_ranges

Validate parameter ranges
Bioenergetic

Constructor for Bioenergetic Objects
FB4-TMB-Shared

FB4 TMB Shared Functions
add_confidence_bands

Add Confidence Bands to Plot
analysis-extraction

Basic Analysis and Extraction Functions for FB4 Results
analysis-core

Core Analysis Functions for FB4 Results
accumulate_validations

Accumulate multiple validation results
add_plot_annotations

Add Standard Plot Annotations
add_strategy_metadata

Add standard strategy metadata to results