Run FB4 simulation on Bioenergetic object — run

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

# \donttest{
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)
)
#> Bioenergetic object created for: Oncorhynchus tshawytscha
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)
#> Validation warnings:
#> Missing optional parameters (will be calculated): CG1, CG2
#> Object is ready for simulation
#> Validation warnings:
#> Missing optional parameters (will be calculated): CG1, CG2
#> Object is ready for simulation
#> Processing species parameters...
#> Processing temporal data...
#> No indigestible fraction data provided, using default 0% for all prey (FB4 default)
#> Processing simulation settings...
#> Simulation data preparation complete. Ready for simulation.
result$summary$final_weight
#> [1] 134.0913
# }