# fb4package 2.1.0 (2026-06-06)

### New features

* **Nutrient sub-model now active** — `Bioenergetic()` accepts `nutrient_data`
  (N and P concentrations, assimilation efficiencies). When supplied, `run_fb4()`
  computes daily nitrogen and phosphorus fluxes (consumed, growth, excretion,
  egestion, N:P ratios) and appends them to `daily_output`.

* **Contaminant sub-model now active** — `Bioenergetic()` accepts
  `contaminant_data`. All three CONTEQ equations (pure accumulation, T/W-dependent
  elimination, Arnot & Gobas 2004) are now computed within the daily loop and
  returned as `Contaminant_*` columns in `daily_output`.

* **Expanded `daily_output`** — three columns added:
  `Starting_Weight` (body weight at the start of each day),
  `Mean_Prey_Energy_J_g` (energy-weighted mean prey energy density),
  and per-prey consumption columns (`Cons_<prey>_g`) for each diet item.

* **Validation vignette** — new article *"Validation against FB4-Shiny"*
  (`vignettes/fb4-shiny-validation.Rmd`) verifies numerical equivalence with
  FB4-Shiny v1.1.7 across all five simulation modes and the nutrient and
  contaminant sub-models.

### Bug fixes

* `strategy = "direct"` now correctly infers the concrete sub-strategy from
  `fit_to`: `"Ration_prey"` routes to `direct_ration_grams` and `"Ration"`
  routes to `direct_ration_percent`, instead of always defaulting to
  `direct_p_value` (#strategy-interface).

* TMB C++ engine (`src/fb4_main.cpp`): total consumption, respiration, and
  waste fluxes are now accumulated using start-of-day weight, consistent with
  the R simulation engine.

* `extract_hierarchical_parameters()`: `betas_se` is no longer overwritten if
  already populated; uses `NA_real_` instead of bare `NA`.

---

# fb4package 2.0.0 (2026-03-28)

This is a major rewrite. The entire codebase was reorganised from a monolithic
structure (7 files) into a modular, strategy-based architecture (33 files),
and an optional TMB/C++ backend was added for statistical estimation methods.

### New features

#### TMB backend
* Added optional **TMB (Template Model Builder)** backend for maximum likelihood
  and hierarchical estimation, providing 10–50× speedup over the pure-R
  implementation (`src/fb4_main.cpp`).
* New C++ headers for consumption, respiration, egestion/excretion, body
  composition, and validation (`src/includes/`).
* Added `Rcpp`, `TMB (>= 1.7.0)`, `RcppEigen` as dependencies.
  `R (>= 4.0.0)` is now required (was `>= 3.5.0`).

#### New estimation strategies via `run_fb4(strategy = ...)`
* `"optim"` — gradient-based fitting with `stats::optim()`.
* `"mle"` — maximum likelihood estimation of *p*-value with SE and 95% CI,
  using observed final weights (`observed_weights`).
* `"bootstrap"` — non-parametric uncertainty quantification via resampling
  of observed final weights. Supports parallel execution (`future`/`furrr`).
* `"hierarchical"` — population-level mixed-effects model estimating mean and
  SD of *p* across individuals (TMB required).

#### Architecture
* Simulation engine extracted into `R/12-simulation-engine.R`.
* Fitting algorithms split into individual strategy files
  (`14.2.1` through `14.2.6`), a shared commons layer
  (`14.0.1-strategy-commons.R`), and a strategy interface (`14.1`).
* Validation split into four specialised modules
  (`11.0-core`, `11.1-basic`, `11.2-parameter`, `11.3-data`, `11.4-main`).
* `Bioenergetic` class and methods separated into
  `13.0-bioenergetic-classes.R` and `13.1-bioenergetic-methods.R`.
* Analysis layer split into five focused modules (`15.0`–`15.4`).
* Plot layer split into four modules (`16.1`–`16.4`) covering core helpers,
  daily output plots, analysis plots, and bioenergetic-object plots.
* Result builders centralised in `14.3-result-builders.R` with consistent
  field names (`p_value`, `total_consumption_g`, `converged`) across all
  strategies.

#### New analysis functions
`analyze_growth_patterns()`, `analyze_feeding_performance()`,
`analyze_energy_budget()`, `analyze_growth_temperature_sensitivity()`,
`analyze_population_variation()`, `comprehensive_nutritional_analysis()`.

#### New plot types
`plot.fb4_result(type = "growth" | "consumption" | "temperature" | "energy" |
"uncertainty" | "dashboard")` and
`plot.Bioenergetic(type = "temperature" | "diet" | "energy_density" |
"sensitivity")`.

### Internal changes
* `R/00-utils.R` (v0.1.0) replaced by `R/utils.R` with additional helpers
  (`z_score()`, `safe_exp()`, `safe_sqrt()`, `clamp()`, `%||%`).
* `R/09-fitting-algorithms.R` replaced by the strategy layer (`14.x`).
* `R/10-main-growth-model.R` and `R/12-fb4-main.R` replaced by
  `R/12-simulation-engine.R` and `R/14.0-run-fb4-orchestrator.R`.
* `R/13-visualization-analysis.R` split into `15.x` (analysis) and `16.x`
  (plots).
* `R/14-bioenergetic-classes.R` split into `13.0` and `13.1`.

---

# fb4package 0.1.0

* Initial release. Pure-R implementation of Fish Bioenergetics 4.0
  (Deslauriers et al. 2017).
* Binary search fitting (`strategy = "binary_search"`) and direct *p*-value
  simulation (`strategy = "direct"`).
* `Bioenergetic` S3 class with `print()`, `summary()`, `plot()`, and
  `run_fb4()` methods.
* Species parameter database for 105 models (73 species).
* No compiled code; depends only on base R packages.
