fb4package — Fish Bioenergetics 4.0 in R • fb4package

About

The fb4package provides a modern R-based implementation of fish bioenergetics modeling, built upon the foundation of Fish Bioenergetics 4.0 developed by Deslauriers et al. (2017). This package enables comprehensive energy budget modeling for fish growth, consumption, and metabolic processes.

For detailed background, scientific foundation, and development history, see: vignette("fb4-introduction")

Key Features

Comprehensive Energy Budget Modeling: Complete simulation of consumption, metabolism, excretion, egestion, and growth
Multi-Species Support: Built-in parameters for 105+ fish species models across different life stages
Automatic Parameter Fitting: Iterative optimization to reach target weights or consumption rates using binary search algorithms
Environmental Integration: Temperature effects and habitat-dependent functions (dissolved oxygen, salinity)
Flexible Diet Modeling: Multi-prey diet compositions with daily variation and indigestible fractions
Temporal Dynamics: Daily resolution with seasonal environmental variation support
Advanced Visualization: Comprehensive plotting functions for growth, consumption, energy budgets, and diet analysis
Research Reproducibility: Scriptable, version-controlled bioenergetics analyses

Installation

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

Quick Start

Basic Simulation Example

library(fb4package)

# Load built-in species parameters
data("fish4_parameters", package = "fb4package")
chinook_params <- fish4_parameters[["Oncorhynchus tshawytscha"]]

# Create temperature data (seasonal variation)
temperature_data <- data.frame(
  Day = 1:365,
  Temperature = 10 + 6 * sin(2 * pi * (1:365) / 365)  # 4°C ± 6°C seasonal cycle
)

# Define diet composition
diet_data <- data.frame(
  Day = 1:365,
  anchoveta = 0.37,  # 37% anchoveta
  sardina = 0.63     # 63% sardina
)

# Prey energy densities (J/g)
prey_energy_data <- data.frame(
  Day = 1:365,
  anchoveta = 5553,
  sardina = 5000
)

# Indigestible fractions
indigestible_data <- data.frame(
  Day = 1:365,
  anchoveta = 0.05,
  sardina = 0.05
)

# Create bioenergetic object
bio_obj <- Bioenergetic(
  species_info = chinook_params$species_info,
  species_params = chinook_params$life_stages$adult,
  environmental_data = list(temperature = temperature_data),
  diet_data = list(
    proportions = diet_data,
    energies = prey_energy_data,
    indigestible = indigestible_data,
    prey_names = c("anchoveta", "sardina")
  ),
  simulation_settings = list(
    initial_weight = 11115.358,  # Initial weight (g)
    duration = 365               # Simulation days
  )
)

# Set predator energy density parameters
bio_obj$species_params <- set_parameter_value(bio_obj$species_params, "ED_ini", 6308.570)
bio_obj$species_params <- set_parameter_value(bio_obj$species_params, "ED_end", 6320.776)

# Run simulation with automatic fitting to target weight
results <- run_fb4(
  bio_obj,
  fit_to = "Weight",
  fit_value = 14883.695,  # Target final weight (g)
  max_iterations = 25
)

# View results
print(paste("Final weight:", round(results$summary$final_weight, 2), "g"))
print(paste("p estimate  :", round(results$summary$p_estimate, 4)))

Visualization

The package includes comprehensive visualization functions for analyzing simulation results:

Growth, consumption, temperature, energy

plot(results, type = "growth")       # weight trajectory + daily growth rate
plot(results, type = "consumption")  # daily consumption (g/g/day) and total
plot(results, type = "temperature")  # temperature profile vs p_value
plot(results, type = "energy")       # energy components (respiration, SDA, net)
plot(results, type = "dashboard")    # 2×2 summary panel

Uncertainty (bootstrap / MLE)

set.seed(42)
obs_weights <- rnorm(20, mean = 14500, sd = 500)

results_boot <- run_fb4(
  bio_obj,
  strategy         = "bootstrap",
  fit_to           = "Weight",
  observed_weights = obs_weights,
  n_bootstrap      = 500,
  upper            = 1.0,
  parallel         = FALSE
)

plot(results_boot, type = "uncertainty")

Temperature sensitivity

# Sensitivity of growth to temperature × feeding level
plot(bio_obj, type = "sensitivity",
     temperatures = seq(4, 20, by = 2),
     p_values     = seq(0.3, 1.0, by = 0.1))

Export daily results to CSV

write.csv(results$daily_output, "simulation_results.csv", row.names = FALSE)

Advanced Usage

Custom Species Parameters

# Modify specific physiological parameters
bio_obj$species_params <- set_parameter_value(bio_obj$species_params, "CA", 0.303)
bio_obj$species_params <- set_parameter_value(bio_obj$species_params, "CB", -0.275)

# Set custom energy density parameters
bio_obj$species_params <- set_parameter_value(bio_obj$species_params, "ED_ini", 6308.570)
bio_obj$species_params <- set_parameter_value(bio_obj$species_params, "ED_end", 6320.743)

Different Fitting Options

# Fit to consumption instead of weight
results_consumption <- run_fb4(
  bio_obj,
  fit_to = "Consumption",
  fit_value = 6000,  # Target consumption rate (g/g/d)
  max_iterations = 25
)

# Fit with custom tolerance
results_precise <- run_fb4(
  bio_obj,
  fit_to = "Weight",
  fit_value = 14883.695,
  max_iterations = 50,
  tolerance = 0.0001  # Higher precision
)

Package Structure

Core Functions: Bioenergetic(), run_fb4(), run_fb4_simulation_complete()
Parameter Management: set_parameter_value(), get_parameter_value()
Visualization: plot(fb4_result, type = ...) — types: "growth", "consumption", "temperature", "energy", "uncertainty", "dashboard"; plot(bio_obj, type = ...) — types: "dashboard", "temperature", "diet", "energy", "sensitivity"
Analysis: analyze_growth_patterns(), analyze_feeding_performance(), analyze_energy_budget(), comprehensive_nutritional_analysis()
Built-in Data: fish4_parameters — comprehensive species parameter database
Validation Tools: Model checking and parameter validation functions

Visualization Features

Automatic Plot Types

Growth: Weight trajectory, cumulative growth, growth statistics
Consumption: Consumption rates, total consumption, diet breakdown by prey species
Temperature: Temperature profiles, temperature-consumption relationships
Energy: Energy budget components, growth efficiency
Dashboard: Multi-panel overview of key metrics

Customization Options

Multiple color schemes (default, colorblind-friendly, monochrome)
Flexible plot layouts (single, panel, dashboard)
Save options (PNG, PDF, JPEG) with custom dimensions
Statistical annotations and trend lines
Diet composition analysis for multiple prey species

Data Export

CSV export of daily simulation data
Summary statistics in text format
Publication-ready plots in multiple formats

Scientific Applications

This package supports research in:

Fish Biology: Growth rate estimation, metabolic rate analysis, feeding ecology
Population Ecology: Individual-based modeling, population dynamics, life history studies
Fisheries Management: Stock assessment, habitat evaluation, climate change impacts
Aquaculture: Feed optimization, growth prediction, production planning
Conservation Biology: Species responses to environmental change, habitat restoration
Ecosystem Modeling: Predator-prey dynamics, energy flow analysis

Contributing

We welcome contributions from the bioenergetics modeling community! Whether you’re interested in:

Adding new species parameters
Improving existing functions
Developing new modeling capabilities
Enhancing visualization functions
Reporting bugs or suggesting features
Improving documentation or examples

Please see: vignette("fb4-introduction") for detailed information about the project’s scientific foundation and how to get involved.

Development Guidelines

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Documentation

Introduction: vignette("fb4-introduction") - Scientific background and package overview
Function Reference: help(package = "fb4package") - Complete function documentation
Visualization Guide: vignette("fb4-visualization") - Comprehensive plotting examples
Examples: vignette("fb4-examples") - Additional usage examples and case studies

References

Primary Reference: 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. https://doi.org/10.1080/03632415.2017.1377558

Original FB4 Application: - Website: fishbioenergetics.org - GitHub: jim-breck/FB4

License

This package is licensed under the MIT License. See LICENSE file for details.

Support

Bug Reports: GitHub Issues
Questions: GitHub Discussions
Email: kvttitos@gmail.com