Mixture

Adds predict_mixture() to predict the effects of a mixture of two toxicants.

Closes #23 (closed).

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