Introduction to fb4package

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

knitr::opts_chunk$set(
  collapse  = TRUE,
  comment   = "#>",
  fig.width = 7,
  fig.height = 5,
  message   = FALSE,
  warning   = FALSE
)
library(fb4package)

Overview

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

Working with the package follows a three-step pattern: build a Bioenergetic object that holds species parameters, temperature, diet, and initial conditions; pass it to run_fb4() to run a simulation or fit a feeding level; then extract or plot the results.

---

1. Species parameters

The package ships with a built-in database covering 105 models (73 species).

data(fish4_parameters)
cat("Species in database:", length(fish4_parameters), "\n")
head(names(fish4_parameters), 8)

Retrieve Chinook salmon (Oncorhynchus tshawytscha) and inspect one life stage:

chinook_db  <- fish4_parameters[["Oncorhynchus tshawytscha"]]
stage       <- names(chinook_db$life_stages)[1]
cat("Life stage used:", stage, "\n")

sp_params   <- chinook_db$life_stages[[stage]]
sp_info     <- chinook_db$species_info

# Key consumption parameters
cat("CEQ:", sp_params$consumption$CEQ,
    "  CA:", sp_params$consumption$CA,
    "  CB:", sp_params$consumption$CB, "\n")

---

2. Environmental and diet data

Temperature and diet are supplied as data frames with a Day column.

days <- 1:100

# Seasonal temperature (°C)
temp_data <- data.frame(
  Day         = days,
  Temperature = round(10 + 5 * sin(2 * pi * (days - 60) / 365), 2)
)

# Two-prey diet (constant proportions, J/g energy densities)
diet_data <- list(
  proportions = data.frame(Day = days, Alewife = 0.7, Shrimp = 0.3),
  prey_names  = c("Alewife", "Shrimp"),
  energies    = data.frame(Day = days, Alewife = 4900, Shrimp = 3200)
)

head(temp_data, 3)

---

3. Building a Bioenergetic object

bio <- Bioenergetic(
  species_params      = sp_params,
  species_info        = sp_info,
  environmental_data  = list(temperature = temp_data),
  diet_data           = diet_data,
  simulation_settings = list(initial_weight = 1800, duration = 100)
)

# Required when PREDEDEQ = 2 (energy density as function of weight)
bio$species_params$predator$ED_ini <- 4500
bio$species_params$predator$ED_end <- 5500

print(bio)

---

4. Running simulations

4a. Direct simulation — fixed feeding level

Run the model with a constant proportion of maximum consumption (p = 0.8):

res_direct <- run_fb4(bio, strategy = "direct", p_value = 0.8)
print(res_direct)

4b. Binary search — fit to a target final weight

Find the p that produces a target weight of 3 000 g after 100 days:

res_bs <- run_fb4(bio,
                  strategy  = "binary_search",
                  fit_to    = "Weight",
                  fit_value = 3000)

cat("Estimated p-value :", round(res_bs$summary$p_value, 4), "\n")
cat("Final weight      :", round(res_bs$summary$final_weight, 1), "g\n")
cat("Total consumption :", round(res_bs$summary$total_consumption_g, 1), "g\n")

set.seed(42)
obs_weights <- rnorm(30, mean = 3000, sd = 80)

4c. MLE — uncertainty on p from observed weights

When multiple fish weights are available, strategy = "mle" returns a point estimate of p together with its standard error and 95% confidence interval:

set.seed(42)
obs_weights <- rnorm(30, mean = 3000, sd = 80)   # 30 observed final weights

res_mle <- run_fb4(bio,
                   strategy         = "mle",
                   fit_to           = "Weight",
                   observed_weights = obs_weights)

cat("p-value (MLE)  :", round(res_mle$summary$p_value, 4), "\n")
cat("SE             :", round(res_mle$summary$p_se,    4), "\n")
cat("Converged      :", res_mle$summary$converged, "\n")

4d. Bootstrap — non-parametric uncertainty

set.seed(42)
res_boot <- run_fb4(bio,
                    strategy         = "bootstrap",
                    fit_to           = "Weight",
                    observed_weights = obs_weights,
                    upper            = 1,
                    n_bootstrap      = 100,
                    parallel         = FALSE)

cat("p mean (bootstrap):", round(res_boot$summary$p_mean, 4), "\n")
cat("p SD              :", round(res_boot$summary$p_sd,   4), "\n")

---

5. Comparing strategies

All three methods converge on similar p estimates for the same data — binary search gives a point estimate, while MLE and bootstrap additionally quantify uncertainty:

comparison <- data.frame(
  Strategy        = c("binary_search", "mle", "bootstrap"),
  p_estimate      = round(c(res_bs$summary$p_value,
                             res_mle$summary$p_value,
                             res_boot$summary$p_mean), 4),
  SE_or_SD        = round(c(NA, res_mle$summary$p_se, res_boot$summary$p_sd), 4),
  Uncertainty     = c("none (point estimate)", "SE (asymptotic)", "SD (non-parametric)"),
  stringsAsFactors = FALSE
)
knitr::kable(comparison,
             col.names = c("Strategy", "p estimate", "SE / SD", "Uncertainty type"),
             align     = c("l", "r", "r", "l"),
             caption   = "All strategies use the same bio object (Chinook salmon, 100-day simulation). MLE and bootstrap fit to obs_weights; binary search fits to a target weight.")

---

6. Analysing results

growth   <- analyze_growth_patterns(res_bs)
feeding  <- analyze_feeding_performance(res_bs)
energy   <- analyze_energy_budget(res_bs)

cat(sprintf("Final weight              : %.1f g\n",
            growth$final_weight$estimate))
cat(sprintf("Specific growth rate      : %.4f g/g/day\n",
            growth$specific_growth_rate$estimate))
cat(sprintf("Total consumption         : %.1f g\n",
            feeding$total_consumption$estimate))
cat(sprintf("Gross conversion efficiency: %.3f\n",
            feeding$gross_conversion_efficiency$estimate))

---

7. Visualising results

plot(res_bs, type = "growth")

plot(res_bs, type = "energy")

plot(res_bs, type = "dashboard")

---

8. Temperature × p sensitivity

Explore how final weight varies across temperatures and feeding levels:

plot(bio,
     type         = "sensitivity",
     temperatures = seq(6, 20, by = 2),
     p_values     = seq(0.3, 1.0, by = 0.1))

---

9. Experimental features

The following modules are implemented as standalone functions but are not yet integrated into the main run_fb4() loop. They can be called directly for custom analyses and will be connected automatically in a future release.

Contaminant bioaccumulation

Three bioaccumulation models (dietary uptake, gill exchange, bioenergetics-based):

• calculate_contaminant_accumulation() — daily bioaccumulation
• process_contaminant_params() — parameter pre-processing

Nutrient regeneration

Daily nitrogen and phosphorus fluxes (ingestion, retention, excretion):

• calculate_nutrient_balance() — daily N/P budget
• calculate_nutrient_efficiencies() — N and P use efficiencies
• process_nutrient_params() — parameter pre-processing

Mortality rates

Natural, fishing, and predation mortality rates can be processed via process_mortality_params() and computed step-by-step with calculate_mortality_reproduction(), but mortality rates are not yet applied automatically inside run_fb4().

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

---

References

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

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