fb4package (version 2.0.0)

run_fb4.Bioenergetic: 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 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,
  ...
)

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.

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)

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)
)
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
# }