% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/model_spec.R
\name{bdeb_model}
\alias{bdeb_model}
\title{Specify a BDEB Model}
\usage{
bdeb_model(
  data,
  type = c("individual", "growth_repro", "hierarchical", "debtox"),
  priors = list(),
  observation = list(),
  temperature = NULL
)
}
\arguments{
\item{data}{A \code{\link[=bdeb_data]{bdeb_data()}} object.}

\item{type}{Model type: \code{"individual"}, \code{"growth_repro"},
\code{"hierarchical"}, or \code{"debtox"}.}

\item{priors}{Named list of \code{bdeb_prior} objects (see \code{\link[=prior_lognormal]{prior_lognormal()}},
\code{\link[=prior_beta]{prior_beta()}}, etc.). Entries not supplied are filled from
\code{\link[=prior_default]{prior_default()}}.}

\item{observation}{Named list of observation model specs for each endpoint.
Default: \code{list(growth = obs_normal(), reproduction = obs_negbinom())}.}

\item{temperature}{Optional list with components \code{T_obs} (observation
temperature in Kelvin), \code{T_ref} (reference temperature in K), and
\code{T_A} (Arrhenius temperature in K).  If provided, the correction
factor \eqn{c_T = \exp(T_A/T_{\mathrm{ref}} - T_A/T_{\mathrm{obs}})}
(see \code{\link[=arrhenius]{arrhenius()}}) is applied \strong{inside the Stan ODE} to all rate
parameters: \eqn{\{p_{Am}\}}, \eqn{[p_M]}, \eqn{v}, \eqn{k_J}
(growth_repro), \eqn{k_d} (debtox).  Parameters that are \strong{not}
rates (\eqn{\kappa}, \eqn{[E_G]}, \eqn{z_w}, \eqn{b_w}) are not
corrected.  The posterior gives estimates at \eqn{T_{\mathrm{ref}}},
making results comparable across experiments at different
temperatures.  The correction is global (single temperature for the
entire experiment).  If \code{NULL} (default), no correction is applied
(\eqn{c_T = 1}).  The field was renamed from \code{T} to \code{T_obs} in
version 0.1.4 to avoid shadowing R's built-in \code{T} symbol.}
}
\value{
A \code{bdeb_model} object (S3 list).
}
\description{
Creates a model specification that binds together the prepared data, the
DEB process model (encoded as a pre-written Stan program), the prior
distributions, and the observation model.  Internally it calls the
appropriate \verb{build_stan_data_*()} function to assemble the list of
named values that Stan expects.  The Stan program is \emph{not} compiled at
this stage — compilation and sampling happen in \code{\link[=bdeb_fit]{bdeb_fit()}}.
}
\details{
The four model types correspond to increasingly complex DEB formulations:

\describe{
\item{\code{"individual"}}{Standard 2-state DEB (reserve \eqn{E}, structure
\eqn{V}), Kooijman (2010, Ch. 2).  The ODE is solved with Stan's
\code{ode_bdf} (stiff BDF solver) at tolerances \eqn{10^{-6}}.}
\item{\code{"growth_repro"}}{3-state model adding the reproduction buffer
\eqn{E_R}.  Offspring counts are modelled as
\eqn{R_i \sim \mathrm{NegBin}(k_R \Delta E_R, \phi)},
where \eqn{\Delta E_R = E_R(t_{\mathrm{end}}) - E_R(t_{\mathrm{start}})}.}
\item{\code{"hierarchical"}}{2-state model with a lognormal random effect on
\eqn{\{p_{Am}\}}: \eqn{\log p_{Am,j} = \mu + \sigma z_j},
\eqn{z_j \sim N(0,1)} (non-centred).  Shared parameters
\eqn{[p_M], \kappa, v, [E_G]} are estimated from all individuals
jointly (partial pooling; Gelman & Hill, 2006).  Initial
structural length \eqn{L_{0,j}} varies per individual; initial
reserve density \eqn{E_0} is shared (assumes organisms start with
the same reserve state, which is typical for lab-reared cohorts).}
\item{\code{"debtox"}}{4-state TKTD model following Jager et al. (2006).
Adds scaled damage \eqn{D_w} with
\eqn{dD_w/dt = k_d(\max(C_w - z_w, 0) - D_w)}.
The \eqn{\mathrm{EC}_{50}} is computed analytically as
\eqn{z_w + 0.5/b_w}.}
}
}
\examples{
df <- data.frame(id = 1, time = 0:5, length = seq(0.1, 0.6, by = 0.1))
dat <- bdeb_data(growth = df)
mod <- bdeb_model(dat, type = "individual")
print(mod)
summary(mod)
}
\references{
Kooijman, S.A.L.M. (2010). \emph{Dynamic Energy Budget Theory for Metabolic
Organisation}. 3rd edition. Cambridge University Press.
\doi{10.1017/CBO9780511805400}

Gelman, A. and Hill, J. (2006). \emph{Data Analysis Using Regression and
Multilevel/Hierarchical Models}. Cambridge University Press.

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