Exploring the Species Parameter Database"

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 ships with fish4_parameters, a curated database of bioenergetics parameter sets for more than 70 fish species compiled from the primary literature and from Fish Bioenergetics 4.0 (Deslauriers et al. 2017). This vignette shows how to:

1. Inspect the database structure
2. Search for species by name or family
3. Understand the parameter organisation (equations and life stages)
4. Compare key parameters across species
5. Use database parameters in a simulation

---

1. Loading and inspecting the database

data(fish4_parameters)

n_entries <- length(fish4_parameters)
cat("Total entries in database :", n_entries, "\n")
cat("First 12 entries:\n")
print(head(names(fish4_parameters), 12))

Each entry is a named list keyed by the species' scientific name.

---

2. Database structure

Every entry follows the same hierarchical structure:

fish4_parameters[["Species name"]]
├── species_info        # taxonomic information
├── life_stages         # named list of life-stage parameter sets
│   ├── juvenile        # (or adult, larval, etc.)
│   │   ├── consumption
│   │   ├── respiration
│   │   ├── activity
│   │   ├── sda
│   │   ├── egestion
│   │   ├── excretion
│   │   └── predator    # energy density equation
│   └── adult           # (if present)
└── sources             # literature references

# Inspect a single entry
chinook <- fish4_parameters[["Oncorhynchus tshawytscha"]]

cat("=== Species info ===\n")
print(chinook$species_info)

cat("\n=== Life stages available ===\n")
print(names(chinook$life_stages))

cat("\n=== Sources ===\n")
print(chinook$sources)

---

3. Searching the database

By scientific name (partial match)

# Find all Oncorhynchus species
onco_keys <- grep("Oncorhynchus", names(fish4_parameters),
                  value = TRUE, ignore.case = TRUE)
cat("Oncorhynchus species in database:\n")
print(onco_keys)

By common name

# Extract all common names and search
common_names <- sapply(fish4_parameters, function(x) {
  x$species_info$common_name %||% NA_character_
})

trout_idx <- grep("trout|salmon|char", common_names,
                  value = FALSE, ignore.case = TRUE)
cat("Salmonid entries (trout / salmon / char):\n")
print(common_names[trout_idx])

---

4. Listing available life stages

# Summary of life stages per species
stage_summary <- sapply(fish4_parameters, function(x) {
  paste(names(x$life_stages), collapse = ", ")
})

# Show species that have more than one life stage
multi_stage <- stage_summary[sapply(strsplit(stage_summary, ", "), length) > 1]
cat("Species with multiple life stages (first 8):\n")
print(head(multi_stage, 8))

---

5. Comparing consumption parameters across species

The maximum consumption rate is governed by:

$$C_{\max} = C_A \cdot W^{C_B} \cdot f(T)$$

where C~A~ scales the intercept and C~B~ the weight exponent. Higher C~A~ values indicate a higher maximum ration relative to body weight.

# Extract CA, CB, CEQ for all entries (first life stage)
param_table <- do.call(rbind, lapply(names(fish4_parameters), function(sp) {
  entry <- fish4_parameters[[sp]]
  stage <- names(entry$life_stages)[1]
  cons  <- entry$life_stages[[stage]]$consumption

  data.frame(
    Species    = sp,
    Stage      = stage,
    CEQ        = cons$CEQ  %||% NA,
    CA         = cons$CA   %||% NA,
    CB         = cons$CB   %||% NA,
    CTO        = cons$CTO  %||% NA,
    CTM        = cons$CTM  %||% NA,
    stringsAsFactors = FALSE
  )
}))

# Show top 10 by CA (highest maximum ration)
param_table_sorted <- param_table[order(-param_table$CA, na.last = TRUE), ]
knitr::kable(
  head(param_table_sorted[, c("Species", "Stage", "CEQ", "CA", "CB", "CTO", "CTM")], 10),
  caption = "Top 10 entries by CA (maximum consumption coefficient)",
  digits  = 4
)

Temperature optima distribution

cto_vals <- na.omit(param_table$CTO)

hist(cto_vals,
     breaks = 15,
     main   = "Consumption temperature optima (CTO)",
     xlab   = "CTO (°C)",
     ylab   = "Number of entries",
     col    = "steelblue",
     border = "white")
abline(v = median(cto_vals), col = "tomato", lwd = 2, lty = 2)
legend("topright", legend = paste("Median =", round(median(cto_vals), 1), "°C"),
       col = "tomato", lty = 2, lwd = 2, bty = "n")

---

6. Predator energy density equations

The database includes three equations for predator (fish) energy density:

| PREDEDEQ | Form | Parameters | |---|---|---| | 1 | Daily interpolation | ED_data or ED_ini + ED_end | | 2 | Piecewise linear in weight | Alpha1, Beta1, Alpha2, Beta2, Cutoff | | 3 | Power function of weight | Alpha1, Beta1 |

prededeq_vals <- sapply(names(fish4_parameters), function(sp) {
  entry <- fish4_parameters[[sp]]
  stage <- names(entry$life_stages)[1]
  entry$life_stages[[stage]]$predator$PREDEDEQ %||% NA
})

cat("Distribution of PREDEDEQ across database:\n")
print(table(prededeq_vals, useNA = "ifany"))

When PREDEDEQ = 1 (the most common), the user must supply ED_ini and ED_end (or a full ED_data vector) since daily energy density varies with season and condition factor. See the Introduction vignette for an example.

---

7. Building a model directly from the database

# Retrieve brown trout if available, otherwise fall back to first salmonid
target_sp <- grep("Salmo trutta|brown trout",
                  names(fish4_parameters),
                  value = TRUE, ignore.case = TRUE)

if (length(target_sp) == 0) {
  target_sp <- onco_keys[1]   # Fall back to first Oncorhynchus
}
target_sp <- target_sp[1]
cat("Using species:", target_sp, "\n")

entry  <- fish4_parameters[[target_sp]]
stage  <- names(entry$life_stages)[1]
params <- entry$life_stages[[stage]]
info   <- entry$species_info
info$life_stage <- stage

# Minimal 60-day setup
days_short <- 1:60
bio_db <- Bioenergetic(
  species_params     = params,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = days_short,
                             Temperature = 10 + 3 * sin(pi * days_short / 60))
  ),
  diet_data = list(
    proportions = data.frame(Day = days_short, Invertebrates = 1),
    prey_names  = "Invertebrates",
    energies    = data.frame(Day = days_short, Invertebrates = 2800)
  ),
  simulation_settings = list(initial_weight = 50, duration = 60)
)

# Supply energy density bounds for PREDEDEQ = 1
bio_db$species_params$predator$ED_ini <- 4000
bio_db$species_params$predator$ED_end <- 4500

res_db <- run_fb4(bio_db,
                  fit_to    = "Weight",
                  fit_value = 80,
                  strategy  = "binary_search",
                  verbose   = FALSE)

cat(sprintf("Estimated p : %.4f  |  Final weight : %.1f g\n",
            res_db$summary$p_value,
            res_db$summary$final_weight))

---

8. Adding a custom species

If your species is not in the database, supply parameters manually in the same list structure and pass them directly to Bioenergetic(). See the Introduction vignette for a full example with Stewart & Ibarra (1991) parameters for Chinook salmon.

---

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

Hanson PC, Johnson TB, Schindler DE, Kitchell JF (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Report WISSG-97-250.

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