diff --git a/DESCRIPTION b/DESCRIPTION
index ff3def4338af703ffda55cd527818ea844937aa5..8d8bddc5fbdf71d11234d5add275b004f45532fc 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,7 +1,7 @@
Package: stressaddition
Type: Package
Title: Modeling Tri-Phasic Concentration-Response Relationships
-Version: 2.0.0
+Version: 2.0.0.9000
Date: 2020-02-17
Authors@R: person("Sebastian", "Henz", role = c("aut", "cre"),
email = "sebastian.henz@ufz.de",
diff --git a/NEWS.md b/NEWS.md
index 76e2ec2ef128af6718962136f839c8ac760bcf9c..22c5af0c2f0954f1d37c7daa13eaea418127bf86 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,3 +1,7 @@
+# stressaddition (development version)
+
+* Fix documentation of `ecxsys()` and `predict_ecxsys`.
+
# stressaddition 2.0.0
* Changed the order of arguments in `ecxsys()`.
diff --git a/R/ecxsys.R b/R/ecxsys.R
index 591912098baf039efdcc9aab4b868e7ff707c784..8c1b74bf0cb7b8531c61d378b17531b12ccb3db0 100644
--- a/R/ecxsys.R
+++ b/R/ecxsys.R
@@ -8,8 +8,8 @@
#' ECx-SyS
#'
-#' The ECx-SyS model for modeling concentration-effect relationships which
-#' indicate signs of hormesis.
+#' The ECx-SyS model for modeling concentration-effect relationships whith
+#' hormesis.
#'
#' It is advised to complete the curve down to zero for optimal prediction.
#' Therefore \code{effect_tox_observed} in the highest concentration should be
@@ -20,9 +20,8 @@
#' \code{effect_tox_env_observed} (if provided) must be of equal length and
#' sorted by increasing concentration.
#'
-#' @param concentration A vector of concentrations, one of which must be 0 to
-#' indicate the control. Should be sorted in ascending order, otherwise it
-#' will be sorted automatically.
+#' @param concentration A vector of concentrations. Must be sorted in ascending
+#' order and the first element must be 0 to indicate the control.
#' @param hormesis_concentration The concentration where the hormesis occurs.
#' This is usually the concentration of the highest effect after the control.
#' @param effect_tox_observed A vector of effect values observed at the given
@@ -34,10 +33,31 @@
#' survival data in percent this should be 100 (the default).
#' @param p,q The shape parameters of the beta distribution. Default is 3.2.
#'
-#' @return A list (of class ecxsys) containing many different objects with the
-#' most important being \code{curves}, a data frame containing effect and
-#' stress values at different concentrations. See \code{\link{predict_ecxsys}}
-#' for details.
+#' @return A list (of class ecxsys) containing many different objects of which
+#' the most important are listed below. The effect and stress vectors
+#' correspond to the provided concentrations.
+#' \describe{
+#' \item{effect_tox}{Modeled effect resulting from toxicant stress.}
+#' \item{effect_tox_sys}{Modeled effect resulting from toxicant and system
+#' stress.}
+#' \item{effect_tox_env}{Modeled effect resulting from toxicant and
+#' environmental stress.}
+#' \item{effect_tox_env_sys}{Modeled effect resulting from toxicant,
+#' environmental and system stress.}
+#' \item{effect_tox_LL5}{The effect predicted by the five-parameter
+#' log-logistic model derived from the observations under toxicant stress
+#' but without environmental stress.}
+#' \item{effect_tox_env_LL5}{The effect predicted by the five-parameter
+#' log-logistic model derived from the observations under toxicant stress
+#' with environmental stress.}
+#' \item{curves}{A data frame containing effect and stress values as
+#' returned by \code{\link{predict_ecxsys}}. The concentrations are
+#' regularly spaced on a logarithmic scale in the given concentration range.
+#' The control is approximated by the lowest non-control concentration times
+#' 1e-7. The additional column \code{use_for_plotting} is used by the
+#' plotting functions of this package to approximate the control and
+#' generate a break in the concentration axis.}
+#' }
#'
#' @examples model <- ecxsys(
#' concentration = c(0, 0.03, 0.3, 3, 10),
@@ -46,7 +66,7 @@
#' effect_tox_env_observed = c(24, 23, 32, 0, 0)
#' )
#'
-#' # Use effect_max if for example the effect is given as the number of
+#' # Use effect_max if for example the effect is given as the average number of
#' # surviving animals and the initial number of animals is 20:
#' model <- ecxsys(
#' concentration = c(0, 0.03, 0.3, 3, 10),
@@ -111,8 +131,7 @@ ecxsys <- function(concentration,
if (any(is.na(c(all_observations, concentration)))) {
stop("Values containing NA are not supported.")
}
- if (any(all_observations > effect_max) ||
- any(all_observations < 0)) {
+ if (any(all_observations > effect_max) || any(all_observations < 0)) {
stop("Observed effect must be between 0 and effect_max.")
}
conc_shift <- 2 # Powers of ten to shift the control downwards from the
diff --git a/R/predict_ecxsys.R b/R/predict_ecxsys.R
index 604dce43729b25ca640cd239027df06e92c6167b..007c975307fcdb313b3bba6f67af946050ca5999 100644
--- a/R/predict_ecxsys.R
+++ b/R/predict_ecxsys.R
@@ -1,19 +1,19 @@
-#' Predict ECxSyS at various concentrations
+#' Predict effects and stresses
#'
-#' @param model The output of a call to \code{\link{ecxsys}}.
+#' Calculate the effects and stresses of an ECx-SyS model at arbitrary
+#' concentrations.
+#'
+#' @param model An ECx-SyS model as returned by \code{\link{ecxsys}}.
#' @param concentration A numeric vector of concentrations.
#'
#' @return A data frame (of class "ecxsys_predicted") with the following
#' columns:
#' \describe{
-#' \item{concentration}{Concentrations regularly spaced on a logarithmic
-#' scale in the given concentration range. The control is approximated by
-#' the lowest non-control concentration times 1e-7.}
-#' \item{effect_tox_LL5}{The five-parameter log-logistic model of the
-#' effect derived from the observations under toxicant stress but without
-#' environmental stress.}
-#' \item{effect_tox}{Modeled effect resulting from toxicant and system
-#' stress.}
+#' \item{concentration}{The supplied concentrations.}
+#' \item{effect_tox_LL5}{The effect predicted by the five-parameter
+#' log-logistic model derived from the observations under toxicant stress
+#' but without environmental stress.}
+#' \item{effect_tox}{Modeled effect resulting from toxicant stress.}
#' \item{effect_tox_sys}{Modeled effect resulting from toxicant and system
#' stress.}
#' \item{stress_tox}{The toxicant stress.}
@@ -21,9 +21,9 @@
#' without environmental stress.}
#' \item{stress_tox_sys}{The sum of \code{stress_tox} and
#' \code{sys_tox}.}
-#' \item{effect_tox_env_LL5}{The five-parameter log-logistic model of the
-#' effect derived from the observations under toxicant stress with
-#' environmental stress.}
+#' \item{effect_tox_env_LL5}{The effect predicted by the five-parameter
+#' log-logistic model derived from the observations under toxicant stress
+#' with environmental stress.}
#' \item{effect_tox_env}{Modeled effect resulting from toxicant and
#' environmental stress.}
#' \item{effect_tox_env_sys}{Modeled effect resulting from toxicant,
@@ -39,7 +39,8 @@
#' @examples model <- ecxsys(
#' concentration = c(0, 0.03, 0.3, 3, 10),
#' hormesis_concentration = 0.3,
-#' effect_tox_observed = c(85, 76, 94, 35, 0)
+#' effect_tox_observed = c(85, 76, 94, 35, 0),
+#' effect_tox_env_observed = c(24, 23, 32, 0, 0)
#' )
#' p <- predict_ecxsys(model, c(0.001, 0.01, 0.1, 1, 10))
#'
diff --git a/man/ecxsys.Rd b/man/ecxsys.Rd
index ca2cabc4ec802efb1ca64fa7e8d25a6530c0d351..e85daaaec156b87df86dddd51087d7f6af11836b 100644
--- a/man/ecxsys.Rd
+++ b/man/ecxsys.Rd
@@ -15,9 +15,8 @@ ecxsys(
)
}
\arguments{
-\item{concentration}{A vector of concentrations, one of which must be 0 to
-indicate the control. Should be sorted in ascending order, otherwise it
-will be sorted automatically.}
+\item{concentration}{A vector of concentrations. Must be sorted in ascending
+order and the first element must be 0 to indicate the control.}
\item{hormesis_concentration}{The concentration where the hormesis occurs.
This is usually the concentration of the highest effect after the control.}
@@ -35,14 +34,35 @@ survival data in percent this should be 100 (the default).}
\item{p, q}{The shape parameters of the beta distribution. Default is 3.2.}
}
\value{
-A list (of class ecxsys) containing many different objects with the
- most important being \code{curves}, a data frame containing effect and
- stress values at different concentrations. See \code{\link{predict_ecxsys}}
- for details.
+A list (of class ecxsys) containing many different objects of which
+ the most important are listed below. The effect and stress vectors
+ correspond to the provided concentrations.
+ \describe{
+ \item{effect_tox}{Modeled effect resulting from toxicant stress.}
+ \item{effect_tox_sys}{Modeled effect resulting from toxicant and system
+ stress.}
+ \item{effect_tox_env}{Modeled effect resulting from toxicant and
+ environmental stress.}
+ \item{effect_tox_env_sys}{Modeled effect resulting from toxicant,
+ environmental and system stress.}
+ \item{effect_tox_LL5}{The effect predicted by the five-parameter
+ log-logistic model derived from the observations under toxicant stress
+ but without environmental stress.}
+ \item{effect_tox_env_LL5}{The effect predicted by the five-parameter
+ log-logistic model derived from the observations under toxicant stress
+ with environmental stress.}
+ \item{curves}{A data frame containing effect and stress values as
+ returned by \code{\link{predict_ecxsys}}. The concentrations are
+ regularly spaced on a logarithmic scale in the given concentration range.
+ The control is approximated by the lowest non-control concentration times
+ 1e-7. The additional column \code{use_for_plotting} is used by the
+ plotting functions of this package to approximate the control and
+ generate a break in the concentration axis.}
+ }
}
\description{
-The ECx-SyS model for modeling concentration-effect relationships which
-indicate signs of hormesis.
+The ECx-SyS model for modeling concentration-effect relationships whith
+hormesis.
}
\details{
It is advised to complete the curve down to zero for optimal prediction.
@@ -62,7 +82,7 @@ model <- ecxsys(
effect_tox_env_observed = c(24, 23, 32, 0, 0)
)
-# Use effect_max if for example the effect is given as the number of
+# Use effect_max if for example the effect is given as the average number of
# surviving animals and the initial number of animals is 20:
model <- ecxsys(
concentration = c(0, 0.03, 0.3, 3, 10),
diff --git a/man/predict_ecxsys.Rd b/man/predict_ecxsys.Rd
index 194496d1710b8c30498a83f92e7690adec1dcc6b..904bc9f3eefaf0eb0e170e292e3ede2953529d35 100644
--- a/man/predict_ecxsys.Rd
+++ b/man/predict_ecxsys.Rd
@@ -2,12 +2,12 @@
% Please edit documentation in R/predict_ecxsys.R
\name{predict_ecxsys}
\alias{predict_ecxsys}
-\title{Predict ECxSyS at various concentrations}
+\title{Predict effects and stresses}
\usage{
predict_ecxsys(model, concentration)
}
\arguments{
-\item{model}{The output of a call to \code{\link{ecxsys}}.}
+\item{model}{An ECx-SyS model as returned by \code{\link{ecxsys}}.}
\item{concentration}{A numeric vector of concentrations.}
}
@@ -15,14 +15,11 @@ predict_ecxsys(model, concentration)
A data frame (of class "ecxsys_predicted") with the following
columns:
\describe{
- \item{concentration}{Concentrations regularly spaced on a logarithmic
- scale in the given concentration range. The control is approximated by
- the lowest non-control concentration times 1e-7.}
- \item{effect_tox_LL5}{The five-parameter log-logistic model of the
- effect derived from the observations under toxicant stress but without
- environmental stress.}
- \item{effect_tox}{Modeled effect resulting from toxicant and system
- stress.}
+ \item{concentration}{The supplied concentrations.}
+ \item{effect_tox_LL5}{The effect predicted by the five-parameter
+ log-logistic model derived from the observations under toxicant stress
+ but without environmental stress.}
+ \item{effect_tox}{Modeled effect resulting from toxicant stress.}
\item{effect_tox_sys}{Modeled effect resulting from toxicant and system
stress.}
\item{stress_tox}{The toxicant stress.}
@@ -30,9 +27,9 @@ A data frame (of class "ecxsys_predicted") with the following
without environmental stress.}
\item{stress_tox_sys}{The sum of \code{stress_tox} and
\code{sys_tox}.}
- \item{effect_tox_env_LL5}{The five-parameter log-logistic model of the
- effect derived from the observations under toxicant stress with
- environmental stress.}
+ \item{effect_tox_env_LL5}{The effect predicted by the five-parameter
+ log-logistic model derived from the observations under toxicant stress
+ with environmental stress.}
\item{effect_tox_env}{Modeled effect resulting from toxicant and
environmental stress.}
\item{effect_tox_env_sys}{Modeled effect resulting from toxicant,
@@ -46,13 +43,15 @@ A data frame (of class "ecxsys_predicted") with the following
}
}
\description{
-Predict ECxSyS at various concentrations
+Calculate the effects and stresses of an ECx-SyS model at arbitrary
+concentrations.
}
\examples{
model <- ecxsys(
concentration = c(0, 0.03, 0.3, 3, 10),
hormesis_concentration = 0.3,
- effect_tox_observed = c(85, 76, 94, 35, 0)
+ effect_tox_observed = c(85, 76, 94, 35, 0),
+ effect_tox_env_observed = c(24, 23, 32, 0, 0)
)
p <- predict_ecxsys(model, c(0.001, 0.01, 0.1, 1, 10))