Merge branch 'bugfix/documentation' into 'develop'

Fix documentation of ecxsys and predict_ecxsys

See merge request !17

DESCRIPTION

 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", 

NEWS.md

+# stressaddition (development version)
+
+* Fix documentation of `ecxsys()` and `predict_ecxsys`.
+
 # stressaddition 2.0.0
 
 * Changed the order of arguments in `ecxsys()`.

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

R/predict_ecxsys.R

-#' 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))
 #'

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),

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