--- title: "Exploring the Species Parameter Database" author: "Hans Ttito" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Exploring the Species Parameter Database} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} 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 ```{r load-db} 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 ``` ```{r db-structure} # 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) ```{r search-name} # 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 ```{r search-common} # 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 ```{r 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. ```{r compare-params} # 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 ```{r temp-optima-plot, fig.cap="Distribution of consumption temperature optima (CTO) across all database entries."} 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` | ```{r prededeq-dist} 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 ```{r from-db} # 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. Hanson PC, Johnson TB, Schindler DE, Kitchell JF (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Report WISSG-97-250.