% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diagnostics.R
\name{bdeb_derived}
\alias{bdeb_derived}
\alias{bdeb_derived.default}
\alias{bdeb_derived.bdeb_fit}
\title{Compute Derived Biological Quantities from the Posterior}
\usage{
bdeb_derived(object, ...)

\method{bdeb_derived}{default}(object, ...)

\method{bdeb_derived}{bdeb_fit}(object, quantities = c("L_inf", "k_M", "growth_rate"), f = 1, ...)
}
\arguments{
\item{object}{A \code{\link[=bdeb_fit]{bdeb_fit()}} object.}

\item{...}{Additional arguments passed to methods.}

\item{quantities}{Character vector of quantities to compute.  One or
more of \code{"L_m"}, \code{"L_inf"}, \code{"k_M"}, \code{"growth_rate"}, \code{"g"}.}

\item{f}{Scaled functional response \eqn{f \in (0,1]} for computing
food-dependent quantities (\code{"L_inf"}, \code{"growth_rate"}).
Default 1 (ad libitum).}
}
\value{
A \link[posterior:draws_df]{posterior::draws_df} with one column per requested quantity
and one row per posterior draw.
}
\description{
Transforms the raw DEB parameter draws into biologically interpretable
quantities, automatically propagating parameter uncertainty.  All
formulas follow Kooijman (2010, Ch. 3, Table 3.1) strictly.
}
\section{DEB length terminology}{

DEB theory distinguishes several length measures.  This function
returns \strong{structural length} \eqn{L = V^{1/3}}, which is the cube
root of structural volume.  Structural length is \emph{not} the same as
\strong{physical (observed) length} \eqn{L_w}, which relates to \eqn{L}
via the shape coefficient: \eqn{L_w = L / \delta_M}.  The shape
coefficient \eqn{\delta_M} is species-specific (typically 0.1--0.5)
and is not estimated by this package.  If your data are physical
lengths, you should either (a) convert to structural length before
fitting, or (b) divide \code{L_inf} by your species' \eqn{\delta_M} to
obtain the physical asymptotic length.
}

\section{Available quantities}{

\describe{
\item{\code{"L_m"}}{Maximum structural length at \eqn{f = 1}
(Kooijman, 2010, Table 3.1):
\deqn{L_m = \kappa \, \{p_{Am}\} / [p_M]}
This is a \strong{species-level constant} independent of food.
Units: cm.}
\item{\code{"L_inf"}}{Ultimate structural length at food level \eqn{f}
(Kooijman, 2010, Eq. 3.4):
\deqn{L_i = f \cdot L_m = f \, \kappa \, \{p_{Am}\} / [p_M]}
The asymptotic length when \eqn{dV/dt = 0} at constant food.
Depends on \eqn{f}.
Units: cm.  Dimensional check:
\eqn{(-)(-)(\text{J d}^{-1}\text{cm}^{-2}) /
    (\text{J d}^{-1}\text{cm}^{-3}) = \text{cm}}.}
\item{\code{"k_M"}}{Somatic maintenance rate constant:
\deqn{k_M = [p_M] / [E_G]}
Units: d\eqn{^{-1}}.}
\item{\code{"growth_rate"}}{Von Bertalanffy growth rate
(Kooijman, 2010, Eq. 3.23):
\deqn{\dot{r}_B = \frac{k_M \, g}{3\,(f + g)}}
where \eqn{g = [E_G] \, v / (\kappa \, \{p_{Am}\})} is the energy
investment ratio.  Depends on \eqn{f}.  Units: d\eqn{^{-1}}.}
\item{\code{"g"}}{Energy investment ratio (Kooijman, 2010, Table 3.1):
\deqn{g = [E_G] \, v / (\kappa \, \{p_{Am}\})}
Dimensionless.  Large \eqn{g} means growth is expensive relative
to reserve turnover.}
}
}

\section{Reference example}{

For \emph{Eisenia fetida} with AmP parameters \eqn{\{p_{Am}\} = 5.0},
\eqn{[p_M] = 0.5}, \eqn{\kappa = 0.75}:
\eqn{L_m = 0.75 \times 5.0 / 0.5 = 7.5} cm (structural).
With \eqn{\delta_M \approx 0.24}, the physical maximum length would
be \eqn{L_m / \delta_M \approx 31} mm, consistent with observations.
}

\examples{
\donttest{
if (requireNamespace("cmdstanr", quietly = TRUE) &&
    nzchar(tryCatch(cmdstanr::cmdstan_path(), error = function(e) ""))) {
  data(eisenia_growth)
  dat <- bdeb_data(growth = eisenia_growth[eisenia_growth$id == 1, ])
  fit <- bdeb_fit(bdeb_model(dat, type = "individual"),
                  chains = 2, iter_warmup = 200, iter_sampling = 200,
                  refresh = 0)
  bdeb_derived(fit, quantities = c("L_inf", "k_M"))
}
}
}
\references{
Kooijman, S.A.L.M. (2010). \emph{Dynamic Energy Budget Theory for Metabolic
Organisation}. 3rd edition. Cambridge University Press.
\doi{10.1017/CBO9780511805400}

Marques, G.M., Augustine, S., Lika, K., Pecquerie, L., Domingos, T.
and Kooijman, S.A.L.M. (2018). The AmP project: comparing species on
the basis of dynamic energy budget parameters. \emph{PLOS Computational
Biology}, 14(5), e1006100. \doi{10.1371/journal.pcbi.1006100}
}
