% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/class-EffectScenario.R
\name{Scenarios}
\alias{Scenarios}
\alias{scenario}
\alias{scenarios}
\alias{EffectScenario-class}
\title{Effect scenario classes}
\description{
The \code{EffectScenario} class is the base for all of the basic scenario
types and models. It contains slots for data and settings that are
required by most models such as a vector of model parameters and a vector
of initial states. For each particular model, the class's slots are
filled with certain default or fixed values. Some models derive from this
class and add slots to store additional data.
}
\details{
Certain behaviors that are required to model complex processes cannot be
represented by a single EffectScenario. As an example, the parameters of a scenario
are generally fixed during the simulated time period. In order to represent a
change in parameter values, the original scenario would
need to split into two scenarios \emph{A} and \emph{B} which differ by parameter values
and simulated time period. By combining these scenarios to a \emph{scenario sequence},
the sequence would be treated as a single, complex scenario. See
\code{\link[=sequence]{sequence()}} for more information.
\subsection{Parameters}{

Most parameters are represented by numerical types but other types
are possible depending on model. Please refer to the model description
which parameters are required and in which unit. Some or all parameters may
be required to start a simulation. If required parameters are missing,
simulation will fail with an error message.
}

\subsection{Initial state}{

The \emph{initial state} represents the starting values of state variables when
starting a simulation. A scenario's default initial state may be insufficient
to get sensible results. It is advisable to set an initial state explicitly
when creating a new scenario, see \code{\link[=set_init]{set_init()}}.

In theory, a scenario's state variables can be renamed by modifying the names
of the initial state vector. However, this is strongly
discouraged as this will affect other routines such as \code{\link[=effect]{effect()}} and \code{\link[=epx]{epx()}}
and may render results useless.
}

\subsection{Exposure}{

\emph{Exposure} refers to the concentration of toxicant an organism is exposed to.
In case of aquatic organisms, this would commonly be the concentration of a
toxicant in water. Other interpretations are possible depending on model
assumptions.

Exposure time-series are generally represented by a \code{data.frame} containing two
columns. The first column representing time, the second representing the
exposure level. The ordering of columns is mandatory. The column names
are essentially irrelevant but sensible names may help documenting the
scenario and its data. The rows must be ordered chronologically. A time-series
can consist of only a single row; in this case it will represent constant
exposure. Exposure time-series are set to a scenario using \code{\link[=set_exposure]{set_exposure()}}.

Handling time-series is a costly task for the ODE solver due to consistency
checks and interpolation between time steps. How the solver interpolates
the time-series can be controlled by certain arguments to functions
such as \code{\link[=simulate]{simulate()}} and \code{\link[=effect]{effect()}}. Please refer to \code{\link[=simulate]{simulate()}} for a brief
overview and \link[deSolve:forcings]{deSolve::forcings} for a detailed description.

Exposure time-series should be kept as short as possible and as complex as
needed for optimal computational efficiency.
}

\subsection{Environmental forcings}{

\emph{Forcings} generally refer to model parameters that change over time as part
of an external function such as environmental temperature and exposure levels.
Due to the importance of exposure in regulatory assessments, this R package
explicitly distinguishes between environmental forcings and exposure. However,
the same restrictions and features apply to both of them.

Forcing time-series are handled the same way as exposure time-series, i.e.
they are represented by a \code{data.frame} containing two columns. The first column
representing time, the second representing the parameter that is a function of
time. The ordering of columns is mandatory. The rows must be ordered
chronologically. Forcings time-series are set using \code{\link[=set_forcings]{set_forcings()}}.
Please refer to the \emph{Exposure} section for more information on how time-series
are handled.
}

\subsection{Output times}{

A scenario's simulated time period is defined by its minimum and maximum output
time. Simulation results will only be returned for the defined output times
even though the ODE solver may use smaller time steps between output times.
Output times can be explicitly set using \code{\link[=set_times]{set_times()}}. The number and
distance of output times may have influence on the precision of simulation
results and numerical stability, cf. \code{\link[=simulate]{simulate()}}.

Be aware that \code{\link[=set_exposure]{set_exposure()}} will overwrite previously defined output times
if not requested otherwise.
}

\subsection{Effects}{

Generally, all state variables can be used as effect endpoints but models may
provide additional endpoints. Use \code{\link[=set_endpoints]{set_endpoints()}} to enable or disable
endpoints for a scenario.

Some scenarios or models require control runs to calculate effects under
exposure. Generally, control simulations will run automatically
where needed.
}

\subsection{Moving exposure windows}{

The time frame relevant for effects may be much shorter than the assessed
exposure time-series for certain organisms. This fact can be represented
by moving exposure windows which divide a long time period in a number of
consecutive windows of the same length. Each window is simulated individually and effects are
calculated. By default, methods such as \code{\link[=effect]{effect()}} will only return the
maximum effect of all considered windows but detailed results can be presented
on demand.

To use moving exposure windows, the exposure time-series must be regular,
i.e. must have an equidistant step length in time. The length of the window
is defined as the number of time steps of the exposure time-series. As an
example, assume the time-series has daily granularity and a moving window
of seven days length is required. In this case, the moving window must have
a length of seven (7) time steps. If the exposure time-series had hourly granularity,
the same window would need to have a length of 168 (=7*24) time steps. Please
refer to \code{\link[=set_window]{set_window()}} for details.
}
}
\section{Slots}{

\describe{
\item{\code{name}}{\code{character}, unique model name}

\item{\code{tag}}{\code{character}, an optional identifier}

\item{\code{param}}{\code{list} of parameter key-value pairs}

\item{\code{param.bounds}}{named \code{list} of parameter boundaries}

\item{\code{param.req}}{\code{character} vector of required parameters}

\item{\code{forcings}}{\code{list} of \code{data.frame}s representing forcing time-series}

\item{\code{forcings.req}}{\code{character} vector or required model forcings data, e.g. temperature}

\item{\code{init}}{\code{list} of initial model states}

\item{\code{times}}{\code{numeric} vector of output times, beginning and end also define
the simulated period}

\item{\code{endpoints}}{\code{character} vector of endpoints to calculate results for}

\item{\code{exposure}}{\code{data.frame} with two columns representing an exposure time-series}

\item{\code{control}}{\code{list} of named numerical vectors, contains the control values
for all relevant moving windows}

\item{\code{control.req}}{\code{logical}, if \code{TRUE} then control values are required to
calculate effects}

\item{\code{window.length}}{\code{numeric}, maximum length of the simulated period, if
\code{window.length} is shorter than the exposure pattern, then all possible
exposure sub-patterns are evaluated for effect calculation. This is also
referred to as a moving window approach.}

\item{\code{window.interval}}{\code{numeric}, interval determining distance between moving
windows during effect calculation. First window starts at first time point
in exposure pattern.}
}}

\seealso{
Other scenario-related: 
\code{\link{Transferable}}
}
\concept{scenario-related}
