% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/model-lemna_schmitt.R
\name{Lemna_Schmitt}
\alias{Lemna_Schmitt}
\alias{LemnaSchmitt-class}
\alias{LemnaSchmittScenario-class}
\alias{Lemna_SchmittThold}
\title{Lemna model (Schmitt et al. 2013)}
\usage{
Lemna_Schmitt(param, init)

Lemna_SchmittThold(param, init)
}
\arguments{
\item{param}{optional named \code{list} or \code{vector} of model parameters}

\item{init}{optional named numeric \code{vector} of initial state values}
}
\value{
an S4 object of type \linkS4class{LemnaSchmitt}
}
\description{
The model is a mechanistic combined toxicokinetic-toxicodynamic (TK/TD) and
growth model for the aquatic macrophytes \emph{Lemna spp.}
The model simulates the development of \emph{Lemna} biomass under laboratory and
environmental conditions and was developed by Schmitt \emph{et al.} (2013). Growth
of the \emph{Lemna} population is simulated on basis of photosynthesis and respiration
rates which are functions of environmental conditions.
The toxicodynamic sub-model describes the effects of growth-inhibiting
substances by a respective reduction in the photosynthesis rate based on
internal concentrations. This is the historical version of the Lemna model.
For current uses, we recommend the Lemna (SETAC) model, which is a more recent
version of the Schmitt model.
}
\details{
Constructors to ease creation of scenarios based on the \emph{Lemna} model by
Schmitt \emph{et al.} (2013).
A variant of this \emph{Lemna} model, \code{Lemna_SchmittThold()}, provides an additional
cumulative exposure threshold parameter. The Lemna biomass stops growing
if the integral of exposure over time exceeds the threshold. The integral
of exposure is internally accounted for by an additional state variable
\code{AUC} (Area Under Curve).
}
\section{Functions}{
\itemize{
\item \code{Lemna_SchmittThold()}: model variant with cumulative exposure threshold

}}
\section{State variables}{

The following list describes the default names and standard units of the model's
state variables:
\itemize{
\item BM, g_dw/m2, dry weight biomass per square meter
\item E, -, effect [0,1]
\item M_int, ug, internal toxicant mass
\item AUC, ug/L, cumulative exposure (\strong{only} for \code{LemnaThreshold} model)
}

Biomass (BM) and internal toxicant mass (M_int) are initialized to zero by
default. See \code{\link[=set_init]{set_init()}} on how to set the initial states.
}

\section{Model parameters}{

The following model parameters are required:
\itemize{
\item Fate and biomass
\itemize{
\item \code{k_phot_fix}, logical, TRUE then k_phot_max is not changed by environmental factors, else FALSE
\item \code{k_phot_max}, 1/d, maximum photosynthesis rate
\item \code{k_resp}, 1/d, respiration rate
\item \code{k_loss}, 1/d, rate of loss (e.g. flow rate)
\item \code{mass_per_frond}, g_dw/frond, dry weight per frond
\item \code{BMw2BMd}, g_fw/g_dw, Fresh weight/dry weight
}
\item Effect
\itemize{
\item \code{Emax}, -, maximum effect [0,1]
\item \code{EC50}, ug/L, midpoint of effect curve
\item \code{b}, -, slope of effect curve
}
\item Toxicokinetics
\itemize{
\item \code{P_up}, cm/d, Permeability for uptake
\item \code{AperBM}, cm2/g_dw, A_leaf / d_leaf = 1/d_leaf (for circular disc, d=0.05 cm)
\item \code{Kbm}, -, Biomass(fw) : water partition coefficient
\item \code{P_Temp}, logical, TRUE to enable temperature dependence of cuticle permeability, else FALSE
\item \code{MolWeight}, g/mol, Molmass of molecule (determines Q10_permeability)
}
\item Temperature dependence
\itemize{
\item \code{Tmin}, deg C, minimum temperature for growth
\item \code{Tmax}, deg C, maximum temperature for growth
\item \code{Topt}, deg C, optimal temperature for growth
\item \code{t_ref}, deg C, reference temperature for respiration rate
\item \code{Q10}, -, temperature dependence factor for respiration rate
}
\item Light dependence
\itemize{
\item \code{k_0}, 1/d, light dependence: intercept of linear part
\item \code{a_k}, (1/d)/(kJ/m2.d), light dependence: slope of linear part
}
\item Phosphorus dependence (Hill like dep.)
\itemize{
\item \code{C_P}, mg/L, phosphorus concentration in water
\item \code{CP50}, mg/L, phosphorus conc. where growth rate is halfed
\item \code{a_p}, -, Hill coefficient
\item \code{KiP}, mg/L, p-inhibition constant for very high p-conc.
}
\item Nitrogen dependence (Hill like dep.)
\itemize{
\item \code{C_N}, mg/L, nitrogen concentration in water
\item \code{CN50}, mg/L, n-conc. where growth rate is halfed
\item \code{a_N}, -, Hill coefficient
\item \code{KiN}, mg/L, n-inhibition constant for very high p-conc.
}
\item Density dependence
\itemize{
\item \code{BM50}, g_dw/m2, cut off BM
}
}

The \code{Lemna_SchmittThold} model requires the following additional parameter:
\itemize{
\item \code{threshold}, ug/L, cumulative exposure threshold
}
}

\section{Forcings}{

Besides exposure, the model requires four environmental properties as
time-series input:
\itemize{
\item \code{temp}, temperature (°C)
\item \code{rad}, global irradiation (kJ m-2 d-1)
}

The following constant default values are used for these properties:
\itemize{
\item \code{temp} = 12 °C
\item \code{rad} = 15,000 kJ m-2 d-1
}

Forcings time-series are represented by \code{data.frame} objects consisting of two
columns. The first for time and the second for the environmental factor in question.

Entries of the \code{data.frame} need to be ordered chronologically. A time-series
can consist of only a single row; in this case it will represent constant
environmental conditions. See \link{scenarios} for more details.
}

\section{Effects}{

Supported effect endpoints include \emph{BM} (biomass) and \emph{r} (average
growth rate during simulation). The effect on biomass is calculated from
the last state of a simulation. Be aware that endpoint \emph{r} is incompatible
with frond transfers.
}

\section{Parameter boundaries}{

Default values for parameter boundaries are set for all parameters by expert
judgement, for calibration purposes. Values can be access from the object, and
defaults overwritten.
}

\section{Simulation output}{

Simulation results will contain two additional columns besides state variables:
\itemize{
\item \code{C_int}, ug/L, internal concentration of toxicant
\item \code{FrondNo}, -, number of fronds
}

It is possible to amend the output of \code{\link[=simulate]{simulate()}} with additional model
quantities that are not state variables, for e.g. debugging purposes or to
analyze model behavior. To enable or disable additional outputs, use the
optional argument \code{nout} of \code{\link[=simulate]{simulate()}}, see examples below. \code{nout=1}
enables reporting of internal concentration (C_int), \code{nout=14} enables all
additional outputs, and \code{nout=0} will disable additional outputs.

The available output levels are as follows:
\itemize{
\item \code{nout >= 1}: \code{C_int}, internal concentration (ug/L)
\item \code{nout >= 2}: \code{FrondNo}, number of fronds (-)
\item \code{nout >= 3}: \code{C_int_u}, unbound internal concentration (ug/l)
\item Growth and TK/TD
\itemize{
\item \code{nout >= 4}: \code{BM_fresh}, fresh weight biomass (g_fw/m2)
\item \code{nout >= 5}: \code{k_photo_eff}, current photosynthesis rate (1/d)
\item \code{nout >= 6}: \code{k_resp_eff}, current respiration rate (1/d)
\item \code{nout >= 7}: \code{f_Eff}, toxic effect factor (-)
\item \code{nout >= 8}: \code{P_up_eff}, current permeability for uptake (cm/d)
}
\item Environmental variables
\itemize{
\item \code{nout >= 9}: \code{actConc}, current toxicant concentration in surrounding medium (ug/L)
\item \code{nout >= 10}: \code{actTemp}, current environmental temperature (deg C)
\item \code{nout >= 11}: \code{actRad}, current environmental radiation (kJ/m2.d)
}
\item Derivatives
\itemize{
\item \code{nout >= 12}: \verb{d BM/dt}, current change in state variable BM
\item \code{nout >= 13}: \verb{d E/dt}, current change in effect
\item \code{nout >= 14}: \verb{d M_int/dt}, current change in internal toxicant mass
}
}
}

\section{Solver settings}{

The arguments to ODE solver \code{\link[deSolve:ode]{deSolve::ode()}} control how model equations
are numerically integrated. The settings influence stability of the numerical
integration scheme as well as numerical precision of model outputs. Generally, the
default settings as defined by \emph{deSolve} are used, but all \emph{deSolve} settings
can be modified in \emph{cvasi} workflows by the user, if needed. Please refer
to e.g. \code{\link[=simulate]{simulate()}} on how to pass arguments to \emph{deSolve} in \emph{cvasi}
workflows.

Some default settings of \emph{deSolve} were adapted for this model by expert
judgement to enable precise, but also computationally efficient, simulations
for most model parameters. These settings can be modified by the user,
if needed:
\itemize{
\item \code{hmax = 0.1}\if{html}{\out{<br>}}
Maximum step length in time suitable for most simulations.
}
}

\section{Biomass transfer}{

Models supporting biomass transfer can be instructed to move a fixed amount
of biomass to a new medium after a period of time. This feature replicates
a procedure occurring in e.g. \emph{Lemna} effect studies and may be necessary to
recreate study results.

The biomass transfer feature assumes that always a fixed amount of
biomass is transferred. Transfers can occur at any fixed point in time or
in regular intervals. During a transfer, the biomass is reset to the
transferred amount and additional compartments can be scaled 1:1 accordingly,
to e.g. reflect the change in internal toxicant mass when biomass is modified.
Transfer settings can be modified using \code{\link[=set_transfer]{set_transfer()}}.

If a transfer occurs, simulation results of that time point will report the model state
\strong{before} the transfer. Be aware that if transfers are defined using the
\code{interval} argument, the transfers will always occur relative to time point
zero (\code{t = 0}). As an example, setting a regular transfer of seven days,
\code{interval =  7}, will result at transfers occurring at time points which are
integer multiplicates of seven, such as \code{t=0}, \code{t=7}, \code{t=14} and so forth.
The starting and end times of a scenario do not influece \strong{when} a regular
transfer occurs, only \strong{if} it occurs.
}

\references{
Schmitt W., Bruns E., Dollinger M., and Sowig P., 2013:
\emph{Mechanistic TK/TD-model simulating the effect of growth inhibitors on
Lemna populations}. Ecol Model 255, pp. 1-10. \doi{10.1016/j.ecolmodel.2013.01.017}
}
\seealso{
\link{Lemna-models}, \link{Macrophyte-models}, \link{Transferable}, \link{Scenarios}

Other Lemna models: 
\code{\link{Lemna-models}},
\code{\link{Lemna_SETAC}()}

Other macrophyte models: 
\code{\link{Lemna_SETAC}()},
\code{\link{Macrophyte-models}},
\code{\link{Magma}}
}
\concept{Lemna models}
\concept{macrophyte models}
