% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/BayesianDEB-package.R
\docType{package}
\name{BayesianDEB-package}
\alias{BayesianDEB-package}
\alias{BayesianDEB}
\title{BayesianDEB: Bayesian Dynamic Energy Budget Modelling}
\description{
Provides a Bayesian framework for Dynamic Energy Budget (DEB) modelling via 'Stan'. Implements the standard DEB model of Kooijman (2010, \doi{10.1017/CBO9780511805400}) as a state-space model with Hamiltonian Monte Carlo inference (Carpenter et al., 2017, \doi{10.18637/jss.v076.i01}). Includes individual-level growth models, growth-reproduction models, hierarchical multi-individual models with partial pooling, and toxicokinetic-toxicodynamic (TKTD) models for ecotoxicology following the DEBtox framework (Jager et al., 2006, \doi{10.1007/s10646-006-0060-x}). Supports prior specification from biological knowledge, convergence diagnostics (Vehtari et al., 2021, \doi{10.1214/20-BA1221}), posterior predictive checks, derived quantity estimation, and visualisation via 'ggplot2'.

Embeds the standard Dynamic Energy Budget (DEB) model of Kooijman (2010)
within a Bayesian state-space framework, using Stan (Carpenter et al., 2017)
for Hamiltonian Monte Carlo inference.  The DEB ordinary differential
equation system describes how organisms allocate assimilated energy to
maintenance, growth, and reproduction according to the \eqn{\kappa}-rule.
This package wraps pre-compiled Stan programs with a declarative R
interface so that users can fit DEB models without writing Stan code.
}
\section{Models}{

Four model types are implemented, covering the most common DEB
applications in ecology and ecotoxicology:
\describe{
\item{\code{"individual"}}{Two-state model (reserve \eqn{E}, structure
\eqn{V}) for a single organism.  The ODE follows Eqs. 2.4 and 2.6
of Kooijman (2010, Ch. 2).}
\item{\code{"growth_repro"}}{Three-state model (\eqn{E}, \eqn{V},
reproduction buffer \eqn{E_R}) with negative-binomial observation
model for offspring counts.}
\item{\code{"hierarchical"}}{Two-state model with lognormal random effects
on the surface-area-specific assimilation rate \eqn{\{p_{Am}\}},
using the non-centred parameterisation of Betancourt & Girolami
(2015) to avoid pathological funnel geometry.}
\item{\code{"debtox"}}{Four-state TKTD model (\eqn{E}, \eqn{V},
\eqn{E_R}, scaled damage \eqn{D_w}) following the DEBtox framework
of Jager et al. (2006).  Stress on assimilation is currently
implemented; the damage dynamics follow
\eqn{dD_w/dt = k_d(\max(C_w - z_w, 0) - D_w)}.}
}
}

\section{Workflow}{

The recommended workflow follows the iterative Bayesian modelling cycle
described in Gelman et al. (2013, Ch. 6):
\enumerate{
\item Prepare data with \code{\link[=bdeb_data]{bdeb_data()}}.
\item Specify model and priors with \code{\link[=bdeb_model]{bdeb_model()}}.
\item Fit via MCMC with \code{\link[=bdeb_fit]{bdeb_fit()}}.
\item Check convergence with \code{\link[=bdeb_diagnose]{bdeb_diagnose()}}
(\eqn{\hat{R}}, ESS, divergences; Vehtari et al., 2021).
\item Perform posterior predictive checks with \code{\link[=bdeb_ppc]{bdeb_ppc()}}
(Gelman et al., 2013, Ch. 6).
\item Compute derived quantities with \code{\link[=bdeb_derived]{bdeb_derived()}}.
\item Compare models via \code{\link[=bdeb_loo]{bdeb_loo()}} (individual and
growth_repro models only).
\item Iterate: revise priors or model structure as needed.
}
}

\section{Key DEB equations}{

\deqn{\dot{p}_A = f \{p_{Am}\} L^2}
\deqn{\dot{p}_C = \frac{E \cdot v \cdot L}{E + [E_G] V}}
\deqn{dE/dt = \dot{p}_A - \dot{p}_C}
\deqn{dV/dt = (\kappa \dot{p}_C - [p_M] V) / [E_G]}
where \eqn{L = V^{1/3}} is structural length, \eqn{f} is the scaled
functional response, and all symbols follow the DEB notation of
Kooijman (2010, Table 1.1).
}

\section{Numerical layers}{

The package uses two distinct numerical engines:
\describe{
\item{Stan inference (exact)}{\code{bdeb_fit()}, \code{bdeb_diagnose()},
\code{summary()} on a \code{bdeb_fit}, \code{bdeb_ec50()}, \code{bdeb_loo()}, \code{bdeb_ppc()}
for individual/growth_repro.  These use Stan's BDF stiff ODE
solver with adaptive step size and tolerances \eqn{10^{-6}}.
Posteriors, derived quantities, and log-likelihoods from this
layer are publication-grade.}
\item{R-side simulation}{\code{bdeb_prior_predictive()},
\code{bdeb_predict(newdata=...)},
\code{plot(fit, type="trajectory")} for hierarchical/debtox,
\code{plot_dose_response()}.  These use the LSODA solver from
\pkg{deSolve} (adaptive step size, tolerances \eqn{10^{-6}}),
matching Stan's BDF solver.  They are \strong{visualisation and
exploration tools}, not exact inference.  For quantitative
results, use the Stan-based functions.}
}
}

\section{Lifecycle}{

\describe{
\item{Stable}{\code{bdeb_data()}, \code{bdeb_model()}, \code{bdeb_fit()},
\code{bdeb_diagnose()}, \code{bdeb_derived()},
\code{bdeb_ppc()}, \code{bdeb_predict()}, \code{bdeb_loo()}, \code{bdeb_ec50()},
\code{bdeb_tox()}, \code{bdeb_prior_predictive()}, \code{plot_dose_response()},
\code{summary()}, \code{coef()}, \code{confint()}, \code{fitted()}, \code{residuals()},
\code{nobs()}, \code{vcov()}, \code{logLik()}, all prior and observation model
constructors, \code{arrhenius()}, \code{deb_fluxes()},
\code{repro_to_intervals()}, \code{bdeb_session_info()}.}
\item{Deprecated}{\code{bdeb_summary()} (use \code{summary()} on a
\code{bdeb_fit} object instead).}
\item{Stable models}{\code{"individual"}, \code{"growth_repro"},
\code{"hierarchical"}.}
\item{Beta models}{\code{"debtox"} (group-level, 1 ODE per concentration;
hierarchical individual-level DEBtox is planned).}
\item{Planned}{Survival endpoint, per-observation temperature,
DEBtox stress on maintenance/growth cost, hierarchical DEBtox
(individual-level TKTD), weight endpoint with shape coefficient
estimation, wider maturity dynamics, real-data benchmark dataset.}
}
}

\references{
Kooijman, S.A.L.M. (2010). \emph{Dynamic Energy Budget Theory for Metabolic
Organisation}. 3rd edition. Cambridge University Press.
\doi{10.1017/CBO9780511805400}

Carpenter, B., Gelman, A., Hoffman, M.D., Lee, D., Goodrich, B.,
Betancourt, M., Brubaker, M.A., Guo, J., Li, P. and Riddell, A.
(2017). Stan: A probabilistic programming language. \emph{Journal of
Statistical Software}, 76(1), 1--32. \doi{10.18637/jss.v076.i01}

Gelman, A., Carlin, J.B., Stern, H.S., Dunson, D.B., Vehtari, A.
and Rubin, D.B. (2013). \emph{Bayesian Data Analysis}. 3rd edition.
Chapman & Hall/CRC.

Jager, T., Heugens, E.H.W. and Kooijman, S.A.L.M. (2006). Making
sense of ecotoxicological test results: towards application of
process-based models. \emph{Ecotoxicology}, 15(3), 305--314.
\doi{10.1007/s10646-006-0060-x}

Betancourt, M. and Girolami, M. (2015). Hamiltonian Monte Carlo for
hierarchical models. In: Upadhyay, S.K. et al. (eds) \emph{Current Trends
in Bayesian Methodology with Applications}. CRC Press, pp. 79--101.

Vehtari, A., Gelman, A., Simpson, D., Carpenter, B. and
Bürkner, P.-C. (2021). Rank-normalization, folding, and localization:
an improved \eqn{\hat{R}} for assessing convergence of MCMC.
\emph{Bayesian Analysis}, 16(2), 667--718. \doi{10.1214/20-BA1221}
}
\seealso{
Useful links:
\itemize{
  \item \url{https://github.com/sciom/BayesianDEB}
  \item Report bugs at \url{https://github.com/sciom/BayesianDEB/issues}
}

}
\author{
\strong{Maintainer}: Branimir K. Hackenberger \email{branimir@sciom.hr}

Authors:
\itemize{
  \item Tamara Djerdj
  \item Domagoj K. Hackenberger
}

}
\keyword{internal}
