Package 'fb4package'

Description

Combines multiple validation results into a single result, aggregating errors, warnings, and info messages.

Usage

accumulate_validations(..., level = "combined")

Arguments

Value

An object of class fb4_validation (see validation_result) representing the combined state of all inputs. valid is TRUE only if all supplied results are valid. errors and warnings are the concatenation of those fields across all inputs.

Examples

r1 <- validation_result(valid = TRUE)
r2 <- validation_result(valid = FALSE, errors = "value out of range")
accumulate_validations(r1, r2)

Description

Core functions for extracting and accessing results from FB4 simulations. These functions provide a unified interface to access results regardless of the fitting method used ("direct", "optim", "binary_search", "mle", "bootstrap", "hierarchical"). Exported functions include is.fb4_result, get_consumption_uncertainty, get_efficiency_uncertainty, get_individual_results, get_population_results, and get_energy_budget_uncertainty.

Value

No return value; this page documents the core analysis functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Functions for basic analysis and extraction of FB4 simulation results. These functions build on the core extraction functions to provide meaningful biological interpretations and statistical summaries. Exported functions include analyze_growth_patterns, analyze_energy_budget, analyze_feeding_performance, and create_result_summary.

Value

No return value; this page documents the result extraction and summary functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Specialized functions for nutritional analysis of FB4 simulation results. Includes N:P ratio analysis (calculate_np_ratios, compare_with_redfield), nutrient retention efficiency calculations (calculate_nutrient_efficiencies), stoichiometric balance assessment (calculate_stoichiometric_balance), body composition analysis (analyze_composition_by_size, analyze_composition_changes), diet quality assessment (assess_diet_quality), and an integrated wrapper (comprehensive_nutritional_analysis).

Value

No return value; this page documents the nutritional analysis functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Functions for sensitivity analysis, comparative studies, and population-level analysis of FB4 simulation results. Includes individual comparisons (compare_individuals), population variation decomposition (analyze_population_variation), temperature-feeding sensitivity analysis (analyze_growth_temperature_sensitivity), and multi-scenario comparisons (compare_scenarios).

Value

No return value; this page documents the sensitivity analysis functions. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Analyzes body composition across a range of fish sizes to understand allometric relationships and size-dependent changes.

Usage

analyze_composition_by_size(
  weight_range = c(1, 500),
  n_points = 50,
  processed_composition_params
)

Arguments

Value

A data.frame with n_points rows and ten columns: Weight (g), Water_g, Protein_g, Ash_g, Fat_g (all in g), Water_fraction, Protein_fraction, Ash_fraction, Fat_fraction (dimensionless fractions of total wet weight), and Energy_density (J/g wet weight).

Examples

comp_params <- process_composition_params(list())
comp_analysis <- analyze_composition_by_size(c(1, 500), 20, comp_params)
plot(comp_analysis$Weight, comp_analysis$Energy_density)

Description

Analyzes how body composition changes as fish grow during a simulation. Useful for understanding ontogenetic changes in energy density and macronutrient allocation.

Usage

analyze_composition_changes(result, processed_composition_params)

Arguments

Value

A data.frame with one row per simulation day and thirteen columns: Weight (g), Water_g, Protein_g, Ash_g, Fat_g (g), Water_fraction, Protein_fraction, Ash_fraction, Fat_fraction (dimensionless), Energy_density (J/g), Day (integer), Energy_density_change (J/g/day; NA on day 1), Fat_fraction_change, and Protein_fraction_change (change per day; NA on day 1). Stops with an error if result has no daily_output.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result      <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
comp_params <- process_composition_params(list())
df <- analyze_composition_changes(result, comp_params)

Description

Analyzes energy budget components from FB4 simulation results. Calculates proportional allocation to different processes with uncertainty propagation when available.

Usage

analyze_energy_budget(result, individual_id = NULL, confidence_level = 0.95)

Arguments

Value

A named list with four elements:

energy_components

The list returned by get_energy_budget_uncertainty, containing six component sub-lists each with estimate, se, ci_lower, and ci_upper.

proportions

Named list of proportional allocations (prop_respiration, prop_egestion, prop_excretion, prop_sda, prop_net), each a sub-list with estimate, se, ci_lower, and ci_upper. NULL when consumption energy is zero or unavailable.

summary_metrics

Named list with gross_growth_efficiency, metabolic_scope, and assimilation_efficiency sub-lists (each estimate + se). NULL when proportions are unavailable.

balance_check

Named list with consumption_energy, total_allocated, balance_error, and relative_error (all numeric) to verify mass-balance closure.

Plus the context scalars method, has_uncertainty, and individual_id.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
budget <- analyze_energy_budget(result)

Description

Analyzes feeding-related metrics including consumption rates, feeding efficiency, and p_value estimates with uncertainty.

Usage

analyze_feeding_performance(
  result,
  individual_id = NULL,
  confidence_level = 0.95
)

Arguments

Value

A named list with at minimum method (character), has_uncertainty (logical), and individual_id. Additional elements present when the relevant data are available:

total_consumption

The list returned by get_consumption_uncertainty (estimate, se, ci_lower, ci_upper, plus context scalars).

daily_consumption

Sub-list (estimate, se, ci_lower, ci_upper) for the daily consumption rate (g/day).

specific_consumption

Sub-list (same four slots) for the specific consumption rate (g consumption / g fish / day).

p_value

Structure depends on method: for hierarchical it contains population_mean, population_se, population_sd, and n_individuals; for single-individual methods it contains estimate, se, ci_lower, and ci_upper.

feeding_efficiency

Sub-list (estimate, se, ci_lower, ci_upper) for the ratio of total growth to total consumption (dimensionless).

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
feeding <- analyze_feeding_performance(result)

Description

Extracts and analyzes growth patterns from FB4 simulation results. Calculates growth rates, efficiency metrics, and provides uncertainty estimates when available.

Usage

analyze_growth_patterns(result, individual_id = NULL, confidence_level = 0.95)

Arguments

Value

A named list with at minimum method (character), has_uncertainty (logical), individual_id, and initial_weight (numeric, g). The following growth metrics are included as sub-lists each with estimate, se, ci_lower, and ci_upper: final_weight (g), total_growth (g), and relative_growth (%). When simulation duration is available, daily_growth_rate (g/day) and specific_growth_rate (%/day) are appended. For fitted methods a p_value sub-list (estimate, se) is also included; for hierarchical population-level calls, n_individuals (integer) is added.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
growth <- analyze_growth_patterns(result)

Description

Analyzes how growth rates respond to different temperature and feeding level combinations. Uses p-values (proportion of maximum consumption capacity) to simulate feeding scenarios from survival levels (p ~0.2) to maximum capacity (p = 1.0). Parallelized for efficiency.

Usage

analyze_growth_temperature_sensitivity(
  bio_obj,
  temperatures = seq(8, 18, by = 2),
  p_values = seq(0.3, 1, by = 0.1),
  simulation_days = 365,
  oxycal = 13560,
  parallel = FALSE,
  n_cores = NULL,
  verbose = TRUE
)

Arguments

Value

A data frame with one row per temperature-p_value combination and columns:

temperature

Temperature tested (°C).

p_value

Feeding level (proportion of Cmax) tested.

growth_rate

Specific growth rate (percent per day).

final_weight

Predicted final weight (g).

total_consumption

Total consumption over the simulation period (g).

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
results <- analyze_growth_temperature_sensitivity(
  bio,
  temperatures     = c(2, 14),
  p_values         = c(0.4, 0.7),
  simulation_days  = 30,
  verbose          = FALSE
)

Description

Analyzes the magnitude and sources of variation in hierarchical models. Decomposes total variation into between-individual and within-individual components.

Usage

analyze_population_variation(result, include_covariates = TRUE)

Arguments

Value

A named list with at minimum three elements:

n_individuals

Integer. Number of individuals in the analysis.

population_parameters

Named list with sub-lists mu_p, sigma_p, and sigma_obs, each containing estimate, se, ci_lower, and ci_upper.

variance_decomposition

Named list (present when total variance is positive) with between_individual_variance, within_individual_variance, total_variance, between_individual_prop, within_individual_prop, and intraclass_correlation.

When individual outcome data are available, outcome_variation is appended (sub-lists consumption and optionally growth, each with variance, cv, and range). When covariate effects are present and include_covariates = TRUE, covariate_effects is also appended. Stops with an error if result was not produced by the hierarchical method.

Examples

# Population variation requires a hierarchical run; shown here for illustration
# result <- run_fb4(bio, strategy = "hierarchical", ...)
# pv <- analyze_population_variation(result)

Description

Assesses the nutritional quality of the diet based on energy density, macronutrient composition, and digestibility of prey items.

Usage

assess_diet_quality(diet_data, prey_energies, prey_digestibility = NULL)

Arguments

Value

A named list whose elements depend on whether the diet is time-varying or static. Always present: mean_energy_density (numeric, J/g), energy_density_sd (numeric), and energy_density_range (numeric vector of length 2). For time-varying diets, daily_energy_density (numeric vector) is also included. When prey_digestibility is supplied, the list additionally contains mean_digestibility, digestibility_sd, and (for time-varying diets) daily_digestibility. A diversity sub-list with mean_shannon and shannon_sd (and daily_shannon for time-varying diets) is always appended.

Examples

diet  <- list(proportions = data.frame(Day = 1:5,
                                       Prey1 = c(0.6, 0.6, 0.7, 0.5, 0.5),
                                       Prey2 = c(0.4, 0.4, 0.3, 0.5, 0.5)))
prey_e <- data.frame(Day = 1:5, Prey1 = 5000, Prey2 = 4500)
assess_diet_quality(diet, prey_e)

Description

Basic validation and utility functions built on top of the core validators in core-validators. They cover four common needs: scalar numeric validation (check_numeric_value), fundamental model-parameter feasibility (validate_basic_params), a safe fallback empty-composition constructor (create_empty_composition), and time-series structural checks (validate_time_series_data).

Value

No return value; this page documents the basic validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Creates a Bioenergetic class object that encapsulates all components of the fish bioenergetic model for streamlined simulation management.

Usage

Bioenergetic(
  species_params,
  species_info = NULL,
  environmental_data = NULL,
  diet_data = NULL,
  reproduction_data = NULL,
  model_options = list(),
  simulation_settings = list()
)

Arguments

Details

The Bioenergetic object serves as a comprehensive container for all bioenergetic model components.

Required Components:

species_params

Parameter sets for consumption, respiration, etc.

species_info

Species identification with scientific_name or common_name

Optional Components:

environmental_data

Temperature and other environmental variables

diet_data

Diet composition and prey energy densities

model_options

Sub-model toggles and advanced settings

simulation_settings

Initial conditions and duration

Value

An object of class "Bioenergetic": a named list with eight elements: species_info, species_params, environmental_data, diet_data, reproduction_data, model_options, simulation_settings, and fitted (logical, FALSE until a simulation is run). A results element is appended by set_environment, set_diet, and run_fb4 when they reset or populate the object.

Examples

# Create species parameters
params <- list(
  consumption = list(CEQ = 2, CA = 0.303, CB = -0.275, CQ = 3, CTO = 15, CTM = 25),
  respiration = list(REQ = 1, RA = 0.0548, RB = -0.299, RQ = 2, RTO = 5, RTM = 25)
)

# Create species info
species_info <- list(
  scientific_name = "Salmo salar",
  common_name = "Atlantic salmon",
  life_stage = "juvenile"
)

# Create bioenergetic object
bio_obj <- Bioenergetic(
  species_params = params,
  species_info = species_info,
  simulation_settings = list(initial_weight = 10, duration = 365)
)

Description

S3 class system for the Fish Bioenergetics 4.0 model, providing structured data containers and configuration methods for bioenergetic simulations. The central class "Bioenergetic" is created by Bioenergetic and configured via set_environment, set_diet, and set_simulation_settings. Utility functions is.Bioenergetic, get_parameter_value, and set_parameter_value support inspection and modification of the object.

Value

No return value; this page documents the S3 class definitions for the bioenergetic model. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

S3 print and summary methods for the two main classes of the FB4 package: "Bioenergetic" (the model configuration object) and "fb4_result" (the simulation output). print methods produce a concise one-screen overview; summary methods extend that with detailed per-method diagnostics (optimisation convergence, MLE statistics, bootstrap percentiles, or hierarchical population parameters).

Value

No return value; this page documents the S3 methods for bioenergetic objects. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Functions for estimating and updating fish body composition (water, protein, ash, fat) and energy density from total wet weight. Composition is estimated via the allometric regressions of Breck (2014):

$\log_{10}(\text{Component}) = \alpha + \beta \cdot \log_{10}(H_2O)$

Fat is obtained by subtraction and bounded to biologically plausible limits. Energy density is computed as a weighted sum of fat and protein energy contents (J/g).

Value

No return value; this page documents the body composition functions module. See individual function documentation for return values.

References

Breck, J.E. (2014). Body composition in fishes: body size matters. Aquaculture, 433, 40–49. doi:10.1016/j.aquaculture.2014.05.049

Description

Main function that calculates all body composition components and energy density from weight and processed parameters

Usage

calculate_body_composition(weight, processed_composition_params)

Arguments

Value

A named list with 13 elements describing the body composition:

total_weight

Numeric. Total wet weight (g), equal to weight.

water_g

Numeric. Water content (g).

protein_g

Numeric. Protein content (g), estimated from water via Breck (2014) regression.

ash_g

Numeric. Ash content (g), estimated from water via Breck (2014) regression.

fat_g

Numeric. Fat content (g), calculated by subtraction and bounded to [0, max_fat_fraction * weight].

water_fraction

Numeric. Water as a fraction of total weight.

protein_fraction

Numeric. Protein as a fraction of total weight.

ash_fraction

Numeric. Ash as a fraction of total weight.

fat_fraction

Numeric. Fat as a fraction of total weight.

energy_density

Numeric. Energy density (J/g wet weight).

total_energy

Numeric. Total body energy (J).

total_fraction

Numeric. Sum of all four fractions; should be close to 1.

balanced

Logical. TRUE if total_fraction is within 0.05 of 1.

Returns create_empty_composition() when weight <= 0.

Examples

params <- list(water_fraction = 0.72, fat_energy = 36450,
               protein_energy = 17990, max_fat_fraction = 0.30)
calculate_body_composition(weight = 100,
                           processed_composition_params = params)

Description

Main consumption calculation function called from simulation loop

Usage

calculate_consumption(
  temperature,
  weight,
  p_value,
  processed_consumption_params,
  method = "rate"
)

Arguments

Value

A non-negative numeric scalar giving the daily specific consumption rate in g prey per g fish per day. Returns 0 when the temperature-dependence factor is zero (e.g. temperature $\ge$ CTM in equation 2). The value depends on method: "rate" (default) scales by p_value ($C_{\max} \cdot p \cdot F(T)$); "maximum" and "specific" return the unscaled value ($C_{\max} \cdot F(T)$).

Examples

# CEQ 1: simple exponential temperature dependence
params <- list(CEQ = 1, CA = 0.303, CB = -0.275, CQ = 0.06)
calculate_consumption(temperature = 15, weight = 100, p_value = 0.5,
                      processed_consumption_params = params)

Description

Calculates daily contaminant dynamics (uptake, elimination, body burden) for a fish using one of three bioaccumulation models (CONTEQ 1-3).

Usage

calculate_contaminant_accumulation(
  respiration_o2,
  consumption,
  weight,
  temperature,
  current_concentration,
  processed_contaminant_params
)

Arguments

Value

A named list with at least six elements (all numeric scalars unless noted):

clearance

Daily elimination of contaminant (ug/day).

uptake

Total daily uptake from food (ug/day); for CONTEQ 3 this is the sum of water and food uptake.

new_burden

Body burden at end of day (ug); floored at 0.

new_concentration

Whole-body concentration (ug/g wet weight); floored at 0.

weight

Fish weight (g), as supplied.

model_used

Integer. CONTEQ equation used (1, 2, or 3).

CONTEQ 3 (Arnot & Gobas 2004) appends two additional elements: uptake_water (ug/day from water) and uptake_food (ug/day from food).

Experimental

Contaminant modelling is an **experimental feature** under active development. This function can be called directly to compute daily bioaccumulation for a single time step, but it is **not yet integrated** into the main 'run_fb4()' simulation loop. Full integration (automatic contaminant tracking across all simulation days, inclusion in 'fb4_result' objects, and TMB backend support) is planned for a future release. The API may change.

Examples

# CONTEQ 1: food uptake only, no elimination
params <- list(
  CONTEQ = 1,
  prey_concentrations = c(0.05, 0.08),
  transfer_efficiency = c(0.8, 0.8)
)
calculate_contaminant_accumulation(
  respiration_o2 = 0.02, consumption = c(2.0, 1.0),
  weight = 100, temperature = 15,
  current_concentration = 0.1,
  processed_contaminant_params = params
)

Description

Main egestion calculation function called from simulation loop

Usage

calculate_egestion(
  consumption,
  temperature,
  p_value,
  processed_egestion_params
)

Arguments

Value

A non-negative numeric scalar giving the daily egestion rate in J per g fish per day. Returns 0 when consumption is zero. The equation used depends on processed_egestion_params$EGEQ (1 = constant fraction; 2-3 = temperature- and ration-dependent; 4 = temperature-dependent only). The result is always capped at consumption (egestion cannot exceed intake).

Examples

# EGEQ 1: constant fraction of consumption
params <- list(EGEQ = 1, FA = 0.16)
calculate_egestion(consumption = 5.0, temperature = 15, p_value = 0.5,
                   processed_egestion_params = params)

Description

Main excretion calculation function called from simulation loop

Usage

calculate_excretion(
  consumption,
  egestion,
  temperature,
  p_value,
  processed_excretion_params
)

Arguments

Value

A non-negative numeric scalar giving the daily excretion rate in J per g fish per day. Returns 0 when consumption is zero. The equation used depends on processed_excretion_params$EXEQ (1 = constant fraction of assimilated energy; 2-3 = temperature- and ration-dependent; 4 = temperature-dependent only).

Examples

# EXEQ 1: constant fraction of assimilated energy
params <- list(EXEQ = 1, UA = 0.1)
calculate_excretion(consumption = 5.0, egestion = 0.8, temperature = 15,
                    p_value = 0.5, processed_excretion_params = params)

Description

Main function for calculating final weight from energy balance

Usage

calculate_final_weight_fb4(
  initial_weight,
  net_energy,
  spawn_energy = 0,
  processed_predator_params,
  day = 1
)

Arguments

Value

A named list with three elements:

final_weight

Numeric scalar. Fish weight (g) at end of day, after accounting for net energy and reproductive losses. Minimum value is 0.01 g.

final_energy_density

Numeric scalar. Energy density (J/g) corresponding to final_weight.

weight_change

Numeric scalar. Change in weight (g) during the day (final_weight - initial_weight); negative values indicate weight loss.

Examples

# PREDEDEQ 3: power function, positive net energy (weight gain)
params <- list(PREDEDEQ = 3, Alpha1 = 4800, Beta1 = 0.1)
calculate_final_weight_fb4(initial_weight = 100, net_energy = 500,
                           processed_predator_params = params)

Description

Calculates daily mortality probability and reproductive energy loss (natural mortality, fishing mortality, predation mortality, starvation, and weight-dependent survival) for a single time step.

Usage

calculate_mortality_reproduction(
  current_weight,
  temperature,
  day_of_year,
  processed_mortality_params,
  initial_weight = NULL
)

Arguments

Value

A named list with five elements:

mortality

Named list with seven numeric scalars (all daily rates, 0–1): survival_rate, combined_mortality, natural_mortality, fishing_mortality, predation_mortality, weight_effect (increment to mortality due to low body weight), and temperature_effect (increment due to thermal stress).

reproduction

NULL if no spawn pattern is defined in processed_mortality_params; otherwise a named list with weight_loss (g), energy_loss (J), spawn_fraction (0–1), and remaining_weight (g).

day_of_year

Integer. Day of year, as supplied.

current_weight

Numeric. Fish weight (g), as supplied.

temperature

Numeric. Water temperature ($^\circ$C), as supplied.

Experimental

Mortality rate modelling is an **experimental feature** under active development. This function can be called directly to compute daily mortality probability for a single time step, but **mortality rates are not yet integrated** into the main 'run_fb4()' simulation loop. Full integration (automatic daily mortality application, population survival tracking, and result reporting) is planned for a future release. The API may change.

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

Examples

params <- list(
  base_mortality      = 0.001,
  natural_mortality   = 0.001,
  fishing_mortality   = 0.0005,
  predation_mortality = 0.0002,
  weight_threshold    = 10,
  starvation_factor   = 2,
  optimal_temp        = 18,
  thermal_tolerance   = 8,
  stress_factor       = 1.5,
  spawn_pattern       = NULL
)
calculate_mortality_reproduction(current_weight = 100, temperature = 15,
                                 day_of_year = 180,
                                 processed_mortality_params = params)

Description

Calculates molar and mass N:P ratios for consumption, growth, excretion and egestion. Useful for understanding nutritional ecology and stoichiometric balance.

Usage

calculate_np_ratios(nitrogen_fluxes, phosphorus_fluxes, ratio_type = "mass")

Arguments

Value

A named list with three elements:

ratios

Named numeric vector of length 4 giving the N:P ratio for each process (consumed, growth, excretion, egestion). Values may be Inf when phosphorus is zero and NaN when both nutrients are zero.

ratio_type

Character. The ratio type as supplied ("mass" or "molar").

redfield_ratio

Numeric. Reference Redfield ratio: 7.2 for mass ratios and 16 for molar ratios.

Examples

nitrogen   <- list(consumed = 10, growth = 3, excretion = 5, egestion = 2)
phosphorus <- list(consumed = 1.5, growth = 0.5, excretion = 0.6, egestion = 0.4)
np_ratios  <- calculate_np_ratios(nitrogen, phosphorus)
np_ratios$ratios

Description

Calculates daily nitrogen and phosphorus fluxes (ingestion, retention, excretion) for a fish using prey and predator elemental concentrations.

Usage

calculate_nutrient_balance(consumption, weight_gain, processed_nutrient_params)

Arguments

Value

A named list with three elements:

nitrogen

Named list with six numeric scalars describing daily nitrogen fluxes (g N/day): consumed, assimilated, growth, excretion, egestion, and assimilation_efficiency (dimensionless fraction, 0–1).

phosphorus

Same structure as nitrogen but for phosphorus (g P/day).

weight_gain

Numeric scalar. Predator weight gain (g/day), as supplied.

Experimental

Nutrient regeneration modelling is an **experimental feature** under active development. This function can be called directly to compute daily N and P fluxes for a single time step, but it is **not yet integrated** into the main 'run_fb4()' simulation loop. Full integration (automatic daily nutrient tracking, inclusion in 'fb4_result' objects, and TMB backend support) is planned for a future release. The API may change.

Examples

params <- list(
  prey_n_concentrations     = c(0.025, 0.030),
  prey_p_concentrations     = c(0.004, 0.005),
  predator_n_concentration  = 0.030,
  predator_p_concentration  = 0.004,
  n_assimilation_efficiency = c(0.80, 0.80),
  p_assimilation_efficiency = c(0.60, 0.60)
)
calculate_nutrient_balance(consumption = c(2.0, 1.0),
                           weight_gain = 0.5,
                           processed_nutrient_params = params)

Description

Calculates assimilation and retention efficiencies for nitrogen and phosphorus. These metrics are important for understanding nutrient use efficiency.

Usage

calculate_nutrient_efficiencies(nitrogen_fluxes, phosphorus_fluxes)

Arguments

Value

A named list with four elements:

nitrogen

Named list with four numeric scalars: assimilation_efficiency (fraction consumed that is assimilated), retention_efficiency (fraction consumed retained in growth), excretion_rate (fraction consumed lost via excretion), and growth_efficiency (fraction assimilated retained in growth).

phosphorus

Same structure as nitrogen but for phosphorus.

relative_n_retention

Numeric. Ratio of nitrogen to phosphorus retention efficiency; NA when phosphorus retention is zero.

relative_n_excretion

Numeric. Ratio of nitrogen to phosphorus excretion rate; NA when phosphorus excretion rate is zero.

Examples

nitrogen   <- list(consumed = 10, assimilated = 8, growth = 3, excretion = 5,
                   egestion = 2, assimilation_efficiency = 0.8)
phosphorus <- list(consumed = 1.5, assimilated = 1.1, growth = 0.5,
                   excretion = 0.6, egestion = 0.4, assimilation_efficiency = 0.73)
calculate_nutrient_efficiencies(nitrogen, phosphorus)

Description

Main energy density calculation function called from simulation loop

Usage

calculate_predator_energy_density(weight, day = 1, processed_predator_params)

Arguments

Value

A numeric scalar giving the predator energy density in J per g fish, calculated according to processed_predator_params$PREDEDEQ (1 = interpolated daily data; 2 = piecewise linear by weight; 3 = power function of weight).

Examples

# PREDEDEQ 3: power function of weight
params <- list(PREDEDEQ = 3, Alpha1 = 4800, Beta1 = 0.1)
calculate_predator_energy_density(weight = 100, processed_predator_params = params)

Description

Main respiration calculation function called from simulation loop

Usage

calculate_respiration(temperature, weight, processed_respiration_params)

Arguments

Value

A positive numeric scalar giving the daily specific respiration rate in g O$_2$ per g fish per day. Returns 0.000001 as a minimum safety floor when the result is non-finite or non-positive (e.g. at or above the lethal temperature RTM). The value accounts for both the temperature-dependence function (REQ 1 or 2) and the activity multiplier.

Examples

# REQ 2: Kitchell et al. (1977) temperature dependence
params <- list(REQ = 2, RA = 0.0033, RB = -0.227,
               RTM = 30, RTO = 18, RX = 0.5, ACT = 1.5)
calculate_respiration(temperature = 15, weight = 100,
                      processed_respiration_params = params)

Description

Analyzes nutritional limitations based on N:P ratios and determines which nutrient is limiting growth.

Usage

calculate_stoichiometric_balance(nutrient_balance)

Arguments

Value

A named list with ten elements:

nutrient_limitation

Character. Overall assessment: "N-limited", "P-limited", or "Undetermined".

limiting_nutrient

Character. The identified limiting nutrient ("nitrogen", "phosphorus", or "unknown").

excess_nutrient

Character. The nutrient in relative excess.

excess_factor

Numeric. Fold-excess of the non-limiting nutrient relative to the Redfield ratio; 1 when undetermined.

limiting_efficiency

Numeric. Retention efficiency of the limiting nutrient; NA when undetermined.

consumption_np_ratio

Numeric. Observed N:P ratio of consumed food.

redfield_ratio

Numeric. Reference Redfield ratio used.

np_deviation

Numeric. Difference between observed and Redfield N:P ratio.

efficiencies

List from calculate_nutrient_efficiencies.

np_ratios

List from calculate_np_ratios.

Examples

nb <- list(
  nitrogen   = list(consumed = 10, assimilated = 8, growth = 3, excretion = 5,
                    egestion = 2, assimilation_efficiency = 0.8),
  phosphorus = list(consumed = 1.5, assimilated = 1.1, growth = 0.5,
                    excretion = 0.6, egestion = 0.4, assimilation_efficiency = 0.73)
)
calculate_stoichiometric_balance(nb)

Description

Fast validation of numeric values with basic range checking. Simplified utility function for common validation needs.

Usage

check_numeric_value(value, name, min_val = -Inf, max_val = Inf)

Arguments

Details

Performs essential validations:

• Not NULL

• Numeric type

• Finite values (no NA, NaN, Inf)

• Within specified range

Value

The original value (numeric, same length as input), returned unchanged when all checks pass. Throws an error if value is NULL, non-numeric, contains non-finite elements (NA, NaN, Inf), or falls outside [min_val, max_val].

Examples

check_numeric_value(5, "weight")
try(check_numeric_value(-1, "weight", min_val = 0))
try(check_numeric_value(NA, "weight"))

Description

Compares performance metrics between individuals in hierarchical models. Provides statistical summaries and identifies outliers.

Usage

compare_individuals(result, metrics = "all", confidence_level = 0.95)

Arguments

Value

A named list with at minimum three context elements: n_individuals (integer), metrics_compared (character vector), and confidence_level (numeric). Depending on metrics, the following sub-lists are appended; each is produced by an internal summary helper and contains metric_name, n_valid, mean, sd, min, max, median, cv, range, outliers, and performance: consumption, efficiency, and p_value. The growth element (when requested) is itself a list with two such summaries (total_growth and relative_growth). A rankings data.frame (one row per individual; columns for per-metric ranks, composite_rank, and overall_rank) is always appended. Stops with an error if result was not produced by the hierarchical method.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
mr_data <- data.frame(
  individual_id  = paste0("fish_", 1:5),
  initial_weight = c(10, 12, 11, 13, 9),
  final_weight   = c(80, 95, 85, 100, 70)
)
result_hier <- run_fb4(bio, strategy = "hierarchical", backend = "tmb",
                       fit_to = "Weight", observed_weights = mr_data,
                       verbose = FALSE)
comparison <- compare_individuals(result_hier)

Description

Compares multiple FB4 simulation results across different scenarios, parameters, or methods. Useful for comparing alternative models or experimental conditions.

Usage

compare_scenarios(
  result_list,
  metrics = c("consumption", "growth", "efficiency"),
  confidence_level = 0.95
)

Arguments

Value

A named list with five elements:

n_scenarios

Integer. Number of scenarios compared.

scenario_names

Character vector of scenario names.

metrics_compared

Character vector of metrics requested.

confidence_level

Numeric. Confidence level as supplied.

scenario_data

data.frame with one row per scenario. Always contains scenario, method, backend, and converged. Additional *_est and *_se columns are appended for each requested metric (consumption, growth, efficiency, p_value).

When at least two scenarios provide uncertainty estimates, statistical_tests is appended (list of pairwise test results). best_performers (named list of scenario names with highest estimated value per metric) is always appended.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
r1 <- run_fb4(bio, strategy = "direct", p_value = 0.4, verbose = FALSE)
r2 <- run_fb4(bio, strategy = "direct", p_value = 0.7, verbose = FALSE)
comparison <- compare_scenarios(list(low_p = r1, high_p = r2))

Description

Compares calculated N:P ratios with the classical Redfield ratio. Useful for understanding deviations from typical oceanic proportions.

Usage

compare_with_redfield(np_ratios)

Arguments

Value

A data.frame with one row per process and six columns: Process (character), NP_Ratio (numeric), Redfield_Ratio (numeric), Difference (numeric; observed minus Redfield), Relative_Difference (numeric; % deviation from Redfield), and Interpretation (character; one of "N-rich relative to P", "N-poor relative to P", "No P available", or "No flux").

Examples

nitrogen   <- list(consumed = 10, growth = 3, excretion = 5, egestion = 2)
phosphorus <- list(consumed = 1.5, growth = 0.5, excretion = 0.6, egestion = 0.4)
np  <- calculate_np_ratios(nitrogen, phosphorus)
compare_with_redfield(np)

Description

Performs a comprehensive nutritional analysis combining all nutritional metrics including N:P ratios, nutrient efficiencies, body composition, and diet quality assessment.

Usage

comprehensive_nutritional_analysis(
  result,
  nutrient_balance = NULL,
  composition_params = NULL,
  diet_quality_data = NULL
)

Arguments

Value

A named list with at minimum two elements: model_info (list with method and has_daily_output) and energy_budget (from analyze_energy_budget). When optional inputs are provided, the following elements are appended:

np_ratios, redfield_comparison, nutrient_efficiencies, stoichiometric_balance

Added when nutrient_balance is supplied.

initial_composition, final_composition, composition_changes

Added when composition_params is supplied and both initial and final weights are available in result.

diet_quality

Added when diet_quality_data is supplied.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
analysis <- comprehensive_nutritional_analysis(result)

Description

Functions implementing the four consumption temperature-dependence equations (CEQ 1–4) and the allometric maximum-consumption function used in FB4. Consumption is modelled as:

$C = C_{\max} \cdot p \cdot F(T), \quad C_{\max} = CA \cdot W^{CB}$

where $p$ is the proportion of maximum consumption (P-value), $F(T)$ is a temperature-dependence function, $W$ is body mass (g), and $CA$, $CB$ are species-specific intercept and slope coefficients.

CEQ 1 — simple Q10 exponential: $F(T) = e^{CQ \cdot T}$

CEQ 2 — Kitchell et al. (1977): $F(T) = V^{CX} \cdot e^{CX(1-V)}$, where $V = (CTM - T)/(CTM - CTO)$

CEQ 3 — Thornton and Lessem (1978): two-part sigmoid using $CQ$, $CTO$, $CTL$, $CTM$, $CK1$, $CK4$

CEQ 4 — polynomial: $F(T) = e^{CQ \cdot T + CK1 \cdot T^2 + CK4 \cdot T^3}$

Value

No return value; this page documents the consumption functions module. See individual function documentation for return values.

References

Kitchell, J.F., Stewart, D.J. and Weininger, D. (1977). Applications of a bioenergetics model to yellow perch and walleye. Journal of the Fisheries Research Board of Canada, 34(10), 1922–1935. doi:10.1139/f77-258

Thornton, K.W. and Lessem, A.S. (1978). A temperature algorithm for modifying biological rates. Transactions of the American Fisheries Society, 107(2), 284–287.

Hartman, K.J. and Hayward, R.S. (2007). Bioenergetics. In C.S. Guy and M.L. Brown (eds.), Analysis and Interpretation of Freshwater Fisheries Data. American Fisheries Society, Bethesda, MD.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Experimental functions for modelling daily contaminant (e.g. methylmercury, PCBs) dynamics in fish using three bioaccumulation models (CONTEQ 1–3).

CONTEQ 1 — food uptake only, no elimination: $\text{Burden}_{t+1} = \text{Burden}_t + \sum_i C_i \cdot [\text{prey}]_i \cdot \text{AE}_i$

CONTEQ 2 — food uptake with temperature- and weight-dependent elimination (Trudel and Rasmussen 1997): $K_x = \exp(0.066 T - 0.2 \ln W - 6.56)$

CONTEQ 3 — Arnot and Gobas (2004): uptake from both water (via gill transfer) and food, elimination proportional to respiration.

Value

No return value; this page documents the contaminant accumulation functions module. See individual function documentation for return values.

References

Arnot, J.A. and Gobas, F.A.P.C. (2004). A food web bioaccumulation model for organic chemicals in aquatic ecosystems. Environmental Toxicology and Chemistry, 23(10), 2343–2355. doi:10.1897/03-438

Trudel, M. and Rasmussen, J.B. (1997). Modeling the elimination of mercury by fish. Environmental Science and Technology, 31(6), 1716–1722. doi:10.1021/es960609t

Description

Atomic validation functions that provide the foundation for all other validation operations. These functions handle the most basic validation patterns used throughout the FB4 system: numeric range checks, structural requirements (required columns, minimum rows), and domain-specific validators for fractions, positive quantities, and temperatures. All validators return standardised fb4_validation objects constructed by validation_result, which can be aggregated with accumulate_validations.

Value

No return value; this page documents the core validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Create empty composition for invalid inputs (Utility)

Usage

create_empty_composition()

Value

A named list with 13 numeric/logical elements, all set to zero or FALSE: total_weight, water_g, protein_g, ash_g, fat_g, water_fraction, protein_fraction, ash_fraction, fat_fraction, energy_density, total_energy, total_fraction (all 0), and balanced (FALSE). Used as a safe fallback when fish weight is zero or negative.

Examples

create_empty_composition()

Description

**Post-hoc analysis function** — takes a finished fb4_result object and bundles growth, feeding, and energy-budget analyses into a single list. Useful when you need all major metrics in one call.

This is different from the internal $summary slot (built automatically during result construction by create_unified_summary()). This function re-derives richer metrics from daily_output and supports uncertainty propagation for MLE / bootstrap / hierarchical results.

Usage

create_result_summary(result, individual_id = NULL, confidence_level = 0.95)

Arguments

Value

Named list with model_info, growth, feeding, energy_budget, and model_fit sections

See Also

analyze_growth_patterns, analyze_feeding_performance, analyze_energy_budget

Description

Functions for preparing, validating, and transforming the temporal and parameter data required by the FB4 simulation engine. The main entry point is prepare_simulation_data, which orchestrates species-parameter processing (via process_species_parameters) and temporal-data processing (via process_bioenergetic_data). Ancillary functions handle time-series interpolation (interpolate_time_series), diet normalisation, reproduction scheduling, and TMB-format transformations for statistical fitting strategies.

Value

No return value; this page documents the data processing functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Data validation functions built on top of the core validators in core-validators. Covers diet-energy consistency (validate_diet_consistency), individual mark-recapture data (validate_individual_data), processed temporal arrays (validate_temporal_data), the complete simulation data structure (validate_complete_simulation_data), and equation parameter requirements (validate_equation_params).

Value

No return value; this page documents the data validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Functions implementing four egestion models (EGEQ 1–4) and four excretion models (EXEQ 1–4). These represent losses of consumed energy as feces (F) and nitrogenous wastes (U) respectively.

Egestion models:

EGEQ 1 — constant fraction: $F = FA \cdot C$

EGEQ 2 — Elliott (1976), temperature- and feeding-dependent: $F = FA \cdot T^{FB} \cdot e^{FG \cdot p} \cdot C$

EGEQ 3 — Stewart et al. (1983), includes indigestible fraction: modified form of EGEQ 2 accounting for indigestible prey material.

EGEQ 4 — Elliott (1976), temperature-dependent only: $F = FA \cdot T^{FB} \cdot C$

Excretion models:

EXEQ 1 — constant fraction of assimilated energy: $U = UA \cdot (C - F)$

EXEQ 2–3 — Elliott (1976), temperature- and feeding-dependent: $U = UA \cdot T^{UB} \cdot e^{UG \cdot p} \cdot (C - F)$

EXEQ 4 — temperature-dependent only.

Value

No return value; this page documents the egestion and excretion functions module. See individual function documentation for return values.

References

Elliott, J.M. (1976). Energy losses in the waste products of brown trout (Salmo trutta L.). Journal of Animal Ecology, 45(2), 561–580.

Stewart, D.J., Weininger, D., Rottiers, D.V. and Edsall, T.A. (1983). An energetics model for lake trout, Salvelinus namaycush: application to the Lake Michigan population. Canadian Journal of Fisheries and Aquatic Sciences, 40(6), 681–698.

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Plotting functions for uncertainty analysis and sensitivity analysis. Exported functions include plot_uncertainty.fb4_result (dispatches to MLE, bootstrap, and hierarchical sub-functions), plot_distributions.fb4_result, plot_sensitivity.fb4_result, and plot_growth_temperature_sensitivity.

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Plotting functions for Bioenergetic objects (before running a simulation). These plots help validate model setup by displaying temperature profiles (plot_bio_temperature), diet composition over time (plot_bio_diet), predator energy density (plot_bio_energy), and an integrated readiness dashboard (plot_bio_dashboard).

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Plotting functions for daily simulation output. These functions work with the daily_output data produced by run_fb4() and visualise growth (plot_growth), consumption (plot_consumption), temperature (plot_temperature), and energy (plot_energy) patterns over time, as well as an integrated dashboard (plot_dashboard).

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Core utilities and helper functions for the FB4 visualization system. Provides consistent color schemes (get_color_scheme), plot layout helpers (setup_plot_layout), graphics-device management (setup_save_device, close_save_device), annotation utilities (add_confidence_bands, add_plot_annotations), and data validation helpers (validate_plot_data) shared across all plotting modules.

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Main plotting functions for FB4 bioenergetic model results. Provides S3 methods (plot.fb4_result, plot.Bioenergetic) that dispatch to specialised plot types ("dashboard", "growth", "consumption", "temperature", "energy", "uncertainty", "sensitivity").

Value

No return value, called for side effects (plots). See individual function documentation for details.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Internal helper functions shared by the TMB-based MLE and hierarchical fitting strategies. Covers TMB objective validation (validate_tmb_objective), DLL availability checks (check_tmb_compilation), robust multi-start optimization (run_robust_optimization), parameter extraction from sdreport summaries (sdr_pull_est, sdr_pull_se, sdr_pull_vec, sdr_assign_scalars), and result assembly for basic and hierarchical models (extract_tmb_results).

Value

No return value; this page documents shared TMB backend functions. See individual function documentation for return values.

References

Kristensen, K., Nielsen, A., Berg, C.W., Skaug, H. and Bell, B.M. (2016). TMB: Automatic differentiation and Laplace approximation. Journal of Statistical Software, 70(5), 1–21. doi:10.18637/jss.v070.i05

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Comprehensive database containing species-specific bioenergetic parameters for the Fish Bioenergetics 4.0 model. This database includes consumption, respiration, egestion, excretion, and predator energy density parameters for multiple fish species across different life stages.

Usage

fish4_parameters

Format

A list containing bioenergetic parameters for fish species with the following structure:

species_name

List for each species containing:

species_info

Basic taxonomic information (scientific name, common name, family, order)

life_stages

Named list of life stages (e.g., "juvenile", "adult", "larval") containing:

consumption

Consumption parameters (CA, CB, CQ, CTO, CTM, CTL, CK1, CK4, CEQ)

respiration

Respiration parameters (RA, RB, RQ, RTO, RTM, RTL, RK1, RK4, RK5, REQ)

activity

Activity multipliers (ACT, BACT)

sda

Specific Dynamic Action coefficient (SDA)

egestion

Egestion parameters (FA, FB, FG, EGEQ)

excretion

Excretion parameters (UA, UB, UG, EXEQ)

predator

Predator energy density parameters (Alpha1, Beta1, Alpha2, Beta2, Cutoff, ED_data, PREDEDEQ)

source

Literature source reference

notes

Additional notes about the parameters

sources

Vector of literature sources for the species

Details

The database contains parameters for fish species from multiple families including Salmonidae, Percidae, Centrarchidae, Cyprinidae, and others. Each species entry includes one or more life stages with complete or partial parameter sets.

Parameter Categories:

Consumption:

Temperature-dependent consumption model parameters

Respiration:

Metabolic rate and activity parameters

Egestion:

Waste production and defecation parameters

Excretion:

Nitrogenous waste excretion parameters

Predator Energy Density:

Weight-dependent energy content parameters

Temperature Parameters:

CTO, RTO:

Optimum temperature for consumption/respiration

CTM, RTM:

Maximum temperature for consumption/respiration

CTL, RTL:

Lethal temperature for consumption/respiration

Usage: This database is primarily used with the Bioenergetic constructor to create species-specific bioenergetic model objects. Parameters can be extracted using utility functions or accessed directly by species and life stage.

Source

Parameters extracted from Parameters_official.csv, the official species database bundled with the Fish Bioenergetics 4.0 ('FB4') Shiny application (<https://github.com/biofish/FishBioenergetics>). Converted to R list format via generate_fish4_parameters(). Original parameter values compiled from peer-reviewed literature; see the source field within each species entry for individual references.

References

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. doi:10.1080/03632415.2017.1377558

See Also

Bioenergetic, run_fb4

Examples

data(fish4_parameters)
head(names(fish4_parameters))
salmon_info <- fish4_parameters[["Oncorhynchus mykiss"]]
names(salmon_info$life_stages)
juvenile_params <- salmon_info$life_stages$juvenile
names(juvenile_params$consumption)

Description

Metadata information about the Fish Bioenergetics 4.0 parameters database, including version information, creation details, and structural specifications.

Usage

fish4_parameters_metadata

Format

A list containing metadata about the fish4_parameters database:

version

Version number of the database

creation_date

Date when the database was generated

source_file

Original CSV file used to generate the database

description

Brief description of the database contents

n_species

Total number of species in the database

n_total_records

Total number of parameter records

families_included

Number of taxonomic families represented

parameter_groups

Vector of parameter category names

required_parameters

List of essential parameters for FB4 simulations

units

Description of parameter units and measurements

Details

This metadata object provides essential information about the structure, content, and requirements of the fish4_parameters database. It includes quality control information and parameter specifications necessary for proper use of the bioenergetic model.

Required Parameters: The metadata specifies which parameters are essential for running Fish Bioenergetics 4.0 simulations:

Consumption:

CA, CB, CQ, CTO, CTM, CTL

Respiration:

RA, RB, RQ, RTO, RTM, RTL

Units:

Temperature:

Degrees Celsius

Energy Density:

Joules per gram (J/g)

Weight:

Grams (g)

Rates:

Proportions or model coefficients

Source

Generated automatically when converting Parameters_official.csv (from the Fish Bioenergetics 4.0 Shiny application, <https://github.com/biofish/FishBioenergetics>) into an R list object.

See Also

fish4_parameters, Bioenergetic

Examples

data(fish4_parameters_metadata)
print(fish4_parameters_metadata$description)
print(paste("Species count:", fish4_parameters_metadata$n_species))

Description

Extracts consumption results from FB4 simulations with uncertainty propagation when available. Works with all fitting methods.

Usage

get_consumption_uncertainty(
  result,
  individual_id = NULL,
  confidence_level = 0.95
)

Arguments

Value

A named list with eight elements:

estimate

Numeric. Total consumption estimate (g) for the simulation period; NA when unavailable.

se

Numeric. Standard error of the estimate; NA for methods without uncertainty quantification (e.g. "direct", "binary_search", "optim").

ci_lower

Numeric. Lower bound of the confidence interval; NA when se is unavailable.

ci_upper

Numeric. Upper bound of the confidence interval; NA when se is unavailable.

method

Character. Fitting method used (e.g. "direct", "mle", "hierarchical").

backend

Character. Computational backend ("r" or "tmb").

has_uncertainty

Logical. TRUE when standard errors and confidence intervals are populated.

individual_id

As supplied; the requested individual index, or NULL for the population mean.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
consumption <- get_consumption_uncertainty(result)

Description

Extracts growth efficiency results from FB4 simulations with uncertainty propagation when available.

Usage

get_efficiency_uncertainty(
  result,
  individual_id = NULL,
  confidence_level = 0.95
)

Arguments

Value

A named list with six elements:

gross_growth_efficiency

Named sub-list with estimate, se, ci_lower, and ci_upper for the gross growth efficiency (dimensionless ratio of growth energy to consumption energy); values are NA when unavailable.

metabolic_scope

Named sub-list with the same four slots for the metabolic scope (ratio of active to standard metabolism); values are NA when unavailable.

method

Character. Fitting method used.

backend

Character. Computational backend.

has_uncertainty

Logical. TRUE when SEs and CIs are populated.

individual_id

As supplied.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
eff <- get_efficiency_uncertainty(result)

Description

Extracts energy budget components from FB4 simulations with uncertainty propagation when available.

Usage

get_energy_budget_uncertainty(
  result,
  individual_id = NULL,
  confidence_level = 0.95
)

Arguments

Value

A named list with ten elements: six energy-component sub-lists (consumption_energy, respiration_energy, egestion_energy, excretion_energy, sda_energy, net_energy), each containing estimate, se, ci_lower, and ci_upper (all numeric, NA when unavailable); plus method (character), backend (character), has_uncertainty (logical), and individual_id (as supplied).

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
budget <- get_energy_budget_uncertainty(result)

Description

Extracts all individual-level results from hierarchical FB4 models. Returns a comprehensive summary for each individual.

Usage

get_individual_results(result, confidence_level = 0.95)

Arguments

Value

A data.frame with one row per individual. Base columns are individual_id, p_estimate, and p_se. When individual uncertainty data are available the frame additionally contains *_est, *_se, *_ci_lower, and *_ci_upper columns for final_weight, consumption, total_growth, relative_growth, gross_efficiency, and metabolic_scope. Stops with an error if result was not produced by the hierarchical method.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
# Individual results require a hierarchical run; shown here for illustration
# result <- run_fb4(bio, strategy = "hierarchical", ...)
# df <- get_individual_results(result)

Description

Retrieves a specific parameter value from species parameter lists, searching across all parameter categories.

Usage

get_parameter_value(params, param)

Arguments

Value

The value associated with param in the first category of params where it is found, or NULL if param is not present in any category. The type of the returned value matches the stored parameter (typically a numeric scalar).

Examples

sp <- list(consumption = list(CA = 0.303, CB = -0.275))
get_parameter_value(sp, "CA")
get_parameter_value(sp, "nonexistent")

Description

Extracts population-level results from hierarchical FB4 models. Returns means, standard errors, and population parameters.

Usage

get_population_results(result, confidence_level = 0.95)

Arguments

Value

A named list containing at minimum ten elements: mu_p_estimate and mu_p_se (population-mean ration), sigma_p_estimate and sigma_p_se (among-individual SD), sigma_obs_estimate and sigma_obs_se (observation SD), n_individuals (integer), log_likelihood, aic, and bic. When population uncertainty data are available, additional mean_*_est, mean_*_se, mean_*_ci_lower, and mean_*_ci_upper elements are appended for final_weight, consumption, total_growth, relative_growth, gross_efficiency, and metabolic_scope. Confidence-interval elements are also added for mu_p, sigma_p, and sigma_obs. Stops with an error if result was not produced by the hierarchical method.

Examples

# Population results require a hierarchical run; shown here for illustration
# result <- run_fb4(bio, strategy = "hierarchical", ...)
# pop <- get_population_results(result)

Description

Interpolate time series with error handling

Usage

interpolate_time_series(
  data,
  value_columns,
  target_days,
  method = "linear",
  fill_na_method = "extend",
  validate_input = TRUE
)

Arguments

Value

A data.frame with one row per element of target_days. The first column is Day (integer). Subsequent columns correspond to value_columns, each containing the interpolated numeric values at the requested days. NA values are resolved according to fill_na_method: "extend" fills with the nearest valid value, "zero" replaces with 0, and "mean" uses the column mean.

Examples

temp_data <- data.frame(Day = c(1, 100, 200, 365),
                        Temperature = c(5, 15, 18, 7))
interpolate_time_series(temp_data, value_columns = "Temperature",
                        target_days = 1:365)

Description

Tests whether an object inherits from the Bioenergetic class.

Usage

is.Bioenergetic(x)

Arguments

Value

A length-1 logical: TRUE if x inherits from class "Bioenergetic", FALSE otherwise.

Examples

bio <- Bioenergetic(
  species_params = list(
    consumption = list(CEQ = 1, CA = 0.303, CB = -0.275, CQ = 0.06)
  ),
  species_info = list(common_name = "Example fish")
)
is.Bioenergetic(bio)
is.Bioenergetic(list())

Description

Tests whether an object inherits from the fb4_result class.

Usage

is.fb4_result(x)

Arguments

Value

A length-1 logical: TRUE if x inherits from class "fb4_result", FALSE otherwise.

Examples

is.fb4_result(list())

Description

Top-level validation functions that orchestrate all lower-level validators. validate_bioenergetic_for_simulation checks a Bioenergetic object for simulation readiness (structure, species equations, temperature/diet data, initial weight). validate_fb4_inputs extends this with strategy- and data-range checks before calling run_fb4. validate_fb4_system provides a multi-layer diagnostic report (basic, standard, comprehensive) with per-component pass/fail summaries.

Value

No return value; this page documents the main validation functions module. See individual function documentation for return values.

References

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Experimental functions for computing daily fish mortality and reproductive energy costs in the FB4 framework. Mortality is decomposed into natural, fishing, and predation components, with optional adjustments for thermal stress and starvation (weight-dependent). Reproduction is modelled as a seasonal spawn-fraction pattern that removes a fraction of body weight (and its associated energy) on each spawning day.

Note: Mortality rate tracking is not yet integrated into the main run_fb4() loop; spawning energy loss is.

Value

No return value; this page documents the mortality and reproduction functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Experimental functions for computing daily nitrogen (N) and phosphorus (P) fluxes in fish using a mass-balance approach consistent with ecological stoichiometry theory. For each element the daily budget is:

$\text{Consumed} = \text{Assimilated} + \text{Egested}$

$\text{Assimilated} = \text{Growth} + \text{Excreted}$

Assimilation efficiencies for N and P are species- and prey-specific and can differ from those used for energy.

Value

No return value; this page documents the nutrient regeneration functions module. See individual function documentation for return values.

References

Sterner, R.W. and Elser, J.J. (2002). Ecological Stoichiometry: The Biology of Elements from Molecules to the Biosphere. Princeton University Press, Princeton, NJ.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Functions for validating, transforming, and enriching raw user-supplied species parameters before they are passed to the simulation engine. Each major bioenergetic category (consumption, respiration, egestion, excretion, predator energy density, contaminant, nutrient, mortality, body composition) has a dedicated processor that (i) checks that the required parameters for the chosen equation are present, (ii) computes derived values (e.g., CX/CY/CZ for CEQ 2, gill efficiency for CONTEQ 3), and (iii) fills missing optional parameters with documented defaults. The top-level entry point is process_species_parameters.

Value

No return value; this page documents the parameter processing functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Parameter validation functions built on top of the core validators in core-validators. Covers species-equation validation (validate_species_equations), predator energy density (validate_predator_energy_params), contaminant parameters (validate_contaminant_params), nutrient concentrations (validate_nutrient_concentrations), and body composition (validate_body_composition). A central EQUATION_REQUIREMENTS registry stores the required parameters and valid ranges for each bioenergetic equation.

Value

No return value; this page documents the parameter validation functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Shows distributions of parameters from bootstrap samples or hierarchical individual estimates.

Usage

plot_distributions.fb4_result(
  fb4_result,
  color_scheme = "green",
  show_individuals = TRUE
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
set.seed(42)
obs_weights <- rnorm(10, mean = 90, sd = 5)
result_boot <- run_fb4(bio, strategy = "bootstrap", fit_to = "Weight",
                       observed_weights = obs_weights, n_bootstrap = 20,
                       verbose = FALSE)
plot_distributions.fb4_result(result_boot)

Description

Creates sensitivity analysis plots for temperature and feeding effects.

Usage

plot_growth_temperature_sensitivity(
  sensitivity_data,
  temperatures = seq(5, 20, by = 2),
  feeding_levels = c(0.5, 0.75, 1),
  species = NULL,
  ylim = NULL,
  xlim = NULL,
  colors = "grayscale",
  verbose = FALSE,
  ...
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
sens_data <- analyze_growth_temperature_sensitivity(
  bio_obj         = bio,
  temperatures    = c(10, 14),
  p_values        = c(0.4, 0.7),
  simulation_days = 30,
  verbose         = FALSE
)
plot_growth_temperature_sensitivity(sens_data, species = "Chinook")

Description

Runs analyze_growth_temperature_sensitivity and plots the result. Sensitivity analysis requires a Bioenergetic object (not an fb4_result), because it re-runs the model across a grid of temperatures and p_values. Use plot(bio_obj, type = "sensitivity") as the primary interface; this function is the underlying implementation.

Usage

plot_sensitivity.fb4_result(
  bio_obj,
  temperatures = seq(4, 20, by = 2),
  p_values = seq(0.3, 1, by = 0.1),
  simulation_days = 365,
  color_scheme = "grayscale",
  add_annotations = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
plot_sensitivity.fb4_result(
  bio_obj         = bio,
  temperatures    = c(10, 14),
  p_values        = c(0.4, 0.7),
  simulation_days = 30,
  verbose         = FALSE
)

Description

Creates plots showing parameter estimates with confidence intervals. Adapts automatically to the method used (MLE, bootstrap, hierarchical).

Usage

plot_uncertainty.fb4_result(
  fb4_result,
  parameters = "all",
  color_scheme = "blue",
  add_ci_text = TRUE
)

Arguments

Value

Called for its plotting side-effect. Invisibly returns NULL.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
set.seed(42)
obs_weights <- rnorm(10, mean = 90, sd = 5)
result_mle <- run_fb4(bio, strategy = "mle", fit_to = "Weight",
                      observed_weights = obs_weights, verbose = FALSE)
plot_uncertainty.fb4_result(result_mle)

Description

Plotting method for Bioenergetic objects to validate setup before simulation.

Usage

## S3 method for class 'Bioenergetic'
plot(x, type = "dashboard", save_plot = NULL, ...)

Arguments

Value

Invisibly returns the input object x, called for its plotting side-effect.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
plot(bio)
plot(bio, type = "temperature")

Description

Main plotting method for fb4_result objects. Automatically detects available data and provides appropriate visualizations.

Usage

## S3 method for class 'fb4_result'
plot(x, type = "dashboard", save_plot = NULL, ...)

Arguments

Value

Invisibly returns the input object x, called for its plotting side-effect.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
plot(result)
plot(result, type = "growth")

Description

Functions implementing three predator energy density models (PREDEDEQ 1–3) and the corresponding weight-solving routines used in the FB4 energy balance.

PREDEDEQ 1 — interpolated daily data: energy density supplied as a vector of length $n_{\text{days}} + 1$ (one value per day boundary).

PREDEDEQ 2 — piecewise linear by weight: $ED = \alpha_1 + \beta_1 W$ below the cutoff, $ED = \alpha_2 + \beta_2 W$ above.

PREDEDEQ 3 — power function: $ED = \alpha_1 \cdot W^{\beta_1}$.

Value

No return value; this page documents the predator energy density functions module. See individual function documentation for return values.

References

Hanson, P.C., Johnson, T.B., Schindler, D.E. and Kitchell, J.F. (1997). Fish Bioenergetics 3.0. University of Wisconsin Sea Grant Institute, Madison, WI.

Deslauriers, D., Chipps, S.R., Breck, J.E., Rice, J.A. and Madenjian, C.P. (2017). Fish Bioenergetics 4.0: An R-based modeling application. Fisheries, 42(11), 586–596. doi:10.1080/03632415.2017.1377558

Description

Propagates p-value uncertainty to consumption predictions using parametric bootstrap. Generates multiple samples from the p-value distribution and runs FB4 simulations for each sample. Provides full uncertainty distribution without linearity assumptions. Supports parallel processing for improved performance.

Usage

predict_consumption_bootstrap(
  p_mean,
  p_sd,
  bio_obj,
  n_sims = 1000,
  first_day = 1,
  last_day = 365,
  parallel = FALSE,
  n_cores = NULL,
  confidence_level = 0.95,
  verbose = FALSE
)

Arguments

Details

The bootstrap method: 1. Samples p-values from Normal(p_mean, p_sd) 2. Constrains samples to valid range [0.01, 5.0] 3. Runs FB4 simulation for each p-value sample 4. Summarizes consumption distribution

Parallel processing can significantly reduce computation time for large n_sims. The method handles simulation failures gracefully and reports success rates.

Value

A named list with elements:

method

Character string "bootstrap".

consumption_mean

Mean total consumption across bootstrap samples (g).

consumption_sd

Standard deviation of consumption across samples (g).

consumption_ci

Numeric vector of length 2 with lower and upper quantile-based confidence interval bounds (g).

consumption_samples

Numeric vector of all successful consumption estimates from bootstrap samples.

n_successful

Number of bootstrap iterations that produced valid consumption estimates.

p_mean

The supplied p_mean value.

p_sd

The supplied p_sd value.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
uncertainty_result <- predict_consumption_bootstrap(
  p_mean   = 0.5,
  p_sd     = 0.05,
  bio_obj  = bio,
  n_sims   = 20,
  last_day = 30
)

Description

Propagates p-value uncertainty to consumption predictions using the delta method. Computes numerical derivatives and applies first-order approximation for uncertainty propagation. Suitable when the relationship between p and consumption is approximately linear.

Usage

predict_consumption_delta(
  p_est,
  p_se,
  bio_obj,
  delta_size = 0.001,
  first_day = 1,
  last_day = 365,
  verbose = FALSE
)

Arguments

Details

The delta method uses first-order Taylor series approximation: Var(f(X)) ~ [f'(mu)]^2 * Var(X)

The linearity check verifies that the derivative times delta_size is small relative to the consumption estimate, indicating local linearity.

Value

A named list with elements:

method

Character string "delta".

consumption_est

Point estimate of total consumption (g).

consumption_se

Standard error of consumption estimate (g).

consumption_ci

Numeric vector of length 2 with lower and upper confidence interval bounds (g).

derivative

Numerical derivative of consumption with respect to p.

linearity_check

Logical; TRUE if the linearity assumption appears satisfied.

p_est

The supplied p_est value.

p_se

The supplied p_se value.

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
uncertainty_result <- predict_consumption_delta(
  p_est    = 0.5,
  p_se     = 0.05,
  bio_obj  = bio,
  last_day = 30
)

Description

Master function that processes and validates ALL data required for FB4 simulation. Combines species parameter processing with temporal data processing.

Usage

prepare_simulation_data(
  bio_obj,
  strategy,
  fit_to = NULL,
  fit_value = NULL,
  first_day = 1,
  last_day = NULL,
  validate_inputs = TRUE,
  oxycal = 13560,
  output_format = "simulation",
  observed_weights = NULL,
  covariates = NULL
)

Arguments

Value

For output_format = "simulation" (default), a named list with seven elements: species_params (processed species parameter sub-lists), temporal_data (processed temporal arrays), simulation_settings (processed settings), metadata (processing timestamp, duration, prey species, data sources), n_days (integer), temperatures (numeric vector), and initial_weight (numeric scalar). For output_format = "tmb_basic" or "tmb_hierarchical", returns a list formatted for TMB model fitting (structure differs).

Examples

# Requires a fully-configured Bioenergetic object; see ?Bioenergetic
# bio <- Bioenergetic(...)
# sim_data <- prepare_simulation_data(bio, strategy = "direct")

Description

Displays a concise one-page overview of a Bioenergetic object, including species identity, initial weight, simulation duration, and the status of each required component (parameters, temperature, diet). Readiness for fitting is reported in the final status line.

Usage

## S3 method for class 'Bioenergetic'
print(x, ...)

Arguments

Value

Invisibly returns the input object

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
print(bio)

Description

Displays a concise summary of an fb4_result object. The output adapts to the fitting method used: traditional methods (binary search, optim, direct) show weight, growth, consumption, and convergence; "mle" shows parameter estimates with confidence intervals and AIC; "bootstrap" shows mean/SD estimates and CI; and "hierarchical" shows population-level parameters with model fit statistics.

Usage

## S3 method for class 'fb4_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object

Examples

data(fish4_parameters)
sp   <- fish4_parameters[["Oncorhynchus tshawytscha"]]$life_stages$adult
info <- fish4_parameters[["Oncorhynchus tshawytscha"]]$species_info
bio  <- Bioenergetic(
  species_params     = sp,
  species_info       = info,
  environmental_data = list(
    temperature = data.frame(Day = 1:30, Temperature = rep(12, 30))
  ),
  diet_data = list(
    proportions = data.frame(Day = 1:30, Prey1 = 1.0),
    energies    = data.frame(Day = 1:30, Prey1 = 5000),
    prey_names  = "Prey1"
  ),
  simulation_settings = list(initial_weight = 100, duration = 30)
)
bio$species_params$predator$ED_ini <- 5000
bio$species_params$predator$ED_end <- 5500
result <- run_fb4(bio, strategy = "direct", p_value = 0.5, verbose = FALSE)
print(result)