run_fb4.Bioenergetic: Run FB4 simulation on Bioenergetic object

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

Run FB4 simulation on Bioenergetic object

Description

S3 method with automatic backend selection and bootstrap estimation. Supports traditional optimization methods, MLE approaches, and new bootstrap estimation for final weight data. This is the main entry point that coordinates all FB4 execution strategies.

Usage

## S3 method for class 'Bioenergetic'
run_fb4(
  x,
  fit_to = NULL,
  fit_value = NULL,
  observed_weights = NULL,
  covariates = NULL,
  first_day = 1,
  last_day = NULL,
  backend = "r",
  strategy = "binary_search",
  oxycal = 13560,
  tolerance = 0.001,
  max_iterations = 25,
  optim_method = "Brent",
  lower = 0.01,
  upper = 5,
  hessian = FALSE,
  verbose = FALSE,
  confidence_level = 0.95,
  estimate_sigma = TRUE,
  compute_profile = FALSE,
  profile_grid_size = 50,
  n_bootstrap = 1000,
  parallel = FALSE,
  n_cores = NULL,
  sample_size = NULL,
  compute_percentiles = TRUE,
  ...
)

Arguments

x	Bioenergetic object with all model components
fit_to	Target type: "Weight", "Consumption", "p_value", "Ration", "Ration_prey"
fit_value	Target value for deterministic approach
observed_weights	Vector of observed final weights for MLE or bootstrap approaches (optional)
covariates	Optional covariate matrix or data frame
first_day	First simulation day, default 1
last_day	Last simulation day (auto-detected if NULL)
backend	Backend selection: "r" (pure R) or "tmb" (C++ via TMB, faster MLE)
strategy	Fitting strategy: "binary_search" (default), "direct", "optim", "mle" (maximum likelihood), or "bootstrap" (bootstrap estimation)
oxycal	Oxycalorific coefficient (J/g O2), default 13560
tolerance	Convergence tolerance for iterative fitting, default 0.001
max_iterations	Maximum iterations for binary search, default 25
optim_method	If using optim, which method: "Brent", "L-BFGS-B", etc.
lower	Lower bound for p_value search (proportion of Cmax), default 0.01
upper	Upper bound for p_value search (proportion of Cmax). Biologically, p = 1.0 is maximum ration; values > 1.0 are super-maximal. Default 1.0 for bootstrap, 5.0 for binary_search.
hessian	Whether to compute Hessian for standard errors, default FALSE
verbose	Whether to show progress messages, default FALSE
confidence_level	Confidence level for MLE/bootstrap intervals, default 0.95
estimate_sigma	Whether to estimate measurement error in MLE, default TRUE
compute_profile	Whether to compute likelihood profile for MLE, default FALSE
profile_grid_size	Number of points in profile grid for MLE, default 50
n_bootstrap	Number of bootstrap iterations, default 1000
parallel	Whether to use parallel processing for bootstrap, default FALSE
n_cores	Number of cores for parallel processing (NULL = auto-detect)
sample_size	Sample size for each bootstrap iteration (NULL = same as original)
compute_percentiles	Whether to compute additional percentiles for bootstrap, default TRUE
...	Additional arguments passed to strategy-specific functions (e.g., store_predicted_weights_boot for bootstrap)

Value

An object of class fb4_result, a named list with four elements:

summary

Named list with method, p_estimate, final_weight, total_consumption, and method-specific fields (p_mean, p_sd, confidence intervals for MLE and bootstrap, etc.).

daily_output

A data.frame with one row per simulation day containing Day, Weight, Consumption_energy, Respiration, Egestion, Excretion, SDA, Net_energy, Energy_density, and related columns.

method_data

Method-specific auxiliary data: bootstrap p-value distributions and percentiles, MLE likelihood profile, or hierarchical population parameters, depending on strategy.

bioenergetic_object

The original Bioenergetic object x supplied by the caller.

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)
result$summary$final_weight

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