Run FB4 simulation on Bioenergetic object (REFACTORED) — 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 containing:

summary: Named list with method, p_estimate, final_weight, total_consumption, and method-specific fields (p_mean, p_sd, confidence intervals, etc.)
daily_output: Data frame with one row per simulation day: Day, Weight, Consumption_energy, Respiration, Egestion, Excretion, SDA, Net_energy, etc.
method_data: Method-specific data (bootstrap distributions, MLE likelihood profile, etc.)