Merge branch 'feature/documentation' into 'master'

improve documentation of all user-facing functions

Closes #2

See merge request !4

R/ec.R

@@ -2,30 +2,30 @@
 #'
 #' Estimate the concentration to reach a certain effect relative to the control.
 #'
-#' If the value occurs multiple times because of hormesis, which may happen for
-#' low values of \code{target_effect}, then the first occurrence corresponding
-#' to the smaller concentration is returned by default (i.e. the lowest
-#' concentration)..
+#' If the response level occurs multiple times because of hormesis, which may
+#' happen for low values of \code{target_effect}, then the occurrence with the
+#' smallest concentration is returned.
 #'
 #' @param model The object returned from \code{ecxsys()}.
 #' @param effect_name The name of the effect for which you want to calculate the
-#'   EC.
+#'   EC. Must be the name of a column in \code{model$curves}.
 #' @param target_effect The desired effect percentage between 0 and 100. For
 #'   example with the value 10 the function will return the EC10, i.e. the
-#'   concentration where the response falls below 90 % of the maximum possible
+#'   concentration where the response falls below 90 \% of the maximum possible
 #'   response.
 #'
-#' @return A list with the elements \code{concentration} and \code{effect}
-#'   giving the effect concentration and the corresponding effect.
+#' @return A list containing the effect concentration and the corresponding
+#'   effect.
 #'
-#' @examples result <- ecxsys(
+#' @examples model <- ecxsys(
 #'     concentration = c(0, 0.03, 0.3, 3, 10),
 #'     effect_tox_observed = c(85, 76, 94, 35, 0),
 #'     effect_tox_env_observed = c(24, 23, 32, 0, 0),
-#'     hormesis_index = 3
+#'     hormesis_concentration = 0.3
 #' )
-#' # Calculate the EC_10
-#' EC_10 <- ec(result, "effect_tox_sys", 10)
+#' # Calculate the EC_10, the concentration where the effect falls
+#' # below 90 % of the effect in the control:
+#' ec_10 <- ec(model, "effect_tox_sys", 10)
 #'
 #' @export
 ec <- function(model, effect_name, target_effect) {

R/ecxsys.R

 #' ECx-SyS
 #'
-#' The ECx-SyS model.
+#' The ECx-SyS model for modeling concentration-effect relationships which
+#' indicate signs of hormesis.
 #'
-#' TODO: improve this help text
+#' It is advised to complete the curve down to zero for optimal prediction.
+#' Therefore \code{effect_tox_observed} in the highest concentration should be
+#' at or close to zero. If the model does not fit properly try adding an effect
+#' of 0 at ten times the maximum observed concentration.
+#'
+#' The vectors \code{concentration}, \code{effect_tox_observed} and
+#' \code{effect_tox_env_observed} must be of equal length and should be sorted
+#' by increasing concentration.
 #'
 #' @param concentration A vector of concentrations, one of which must be 0 to
-#'   indicate the control.
+#'   indicate the control. Should be sorted in ascending order, otherwise it
+#'   will be sorted automatically.
 #' @param effect_tox_observed A vector of effect values observed at the given
 #'   concentrations and in absence of environmental stress. Values must be
 #'   between 0 and \code{effect_max}.
-#' @param effect_tox_env_observed Effect values observed at the given
-#'   concentrations and in the presence of environmental stress. Values must be
-#'   between 0 and \code{effect_max}. This argument is optional and can be left
-#'   out to model without environmental stress.
-#' @param hormesis_concentration The concentration where the hormesis is.
-#' @param hormesis_index A single integer specifying the index of the hormesis
-#'   concentration in the concentration vector. This argument exists for
-#'   compatibility with older versions of this function. Use one of the the
-#'   hormesis arguments but not both.
+#' @param effect_tox_env_observed Effect values observed in the presence of
+#'   environmental stress. This argument is optional and can be left out to
+#'   model without environmental stress. Values must be between 0 and
+#'   \code{effect_max}.
+#' @param hormesis_concentration The concentration where the hormesis occurs.
+#'   This is usually the concentration of the highest effect after the control.
+#' @param hormesis_index \strong{Deprecated, will be removed soon.} A single
+#'   integer specifying the index of the hormesis concentration in the
+#'   concentration vector. This argument exists for compatibility with older
+#'   versions of this function.
 #' @param effect_max The maximum value the effect could possibly reach. For
 #'   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 TODO: explain output list, especially the function fn
+#' @return The result is a list containing many different objects with the most
+#'   important being \code{curves} and \code{fn}. You can use \code{fn()} to
+#'   calculate the curves at your concentrations of choice, see examples.
+#'   \code{curves} is a data frame 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_simple}{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{effect_tox_sys}{Modeled effect resulting from toxicant and system
+#'     stress.}
+#'     \item{stress_tox}{The toxicant stress.}
+#'     \item{sys_stress_tox}{System stress under toxicant stress conditions
+#'     without environmental stress.}
+#'     \item{stress_tox_sys}{The sum of \code{stress_tox} and
+#'     \code{sys_stress_tox}.}
+#'     \item{effect_tox_env_simple}{The five-parameter log-logistic model of the
+#'     effect 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,
+#'     environmental and system stress.}
+#'     \item{stress_env}{Environmental stress.}
+#'     \item{stress_tox_env}{The sum of toxicant and environmental stress.}
+#'     \item{sys_stress_tox_env}{System stress under toxicant and
+#'     environmental stress conditions.}
+#'     \item{stress_tox_env_sys}{The sum of \code{stress_tox_env} and
+#'     \code{sys_stress_tox_env}.}
+#'     \item{use_for_plotting}{A boolean vector which is used in the plotting
+#'     functions. It controls which parts of the curves are removed for the
+#'     broken concentration axis.}
+#'   }
 #'
-#' @examples result <- ecxsys(
+#' @examples model <- ecxsys(
 #'     concentration = c(0, 0.03, 0.3, 3, 10),
 #'     effect_tox_observed = c(85, 76, 94, 35, 0),
 #'     effect_tox_env_observed = c(24, 23, 32, 0, 0),
-#'     hormesis_index = 3
+#'     hormesis_concentration = 0.3
 #' )
 #'
+#' # Use effect_max if for example the effect is given as the number of
+#' # surviving animals and the initial number of animals is 20:
+#' model <- ecxsys(
+#'     concentration = c(0, 0.03, 0.3, 3, 10),
+#'     effect_tox_observed = c(17, 15.2, 18.8, 7, 0),
+#'     effect_tox_env_observed = c(4.8, 4.6, 6.4, 0, 0),
+#'     hormesis_concentration = 0.3,
+#'     effect_max = 20
+#' )
+#'
+#' # The returned object contains a function which is useful for calculating
+#' # effect and stress values at specific concentrations:
+#' model$fn(c(0, 0.01, 0.1, 1))
+#'
 #' @export
 ecxsys <- function(concentration,
                    effect_tox_observed,

R/plot_ecxsys.R

-# This file contains the shared documentation for the plotting functions and
-# some helper functions.
+# This is the shared documentation for the plotting functions
 
 
-#' Plot the result of the ECx-SyS model
+#' Plot the results of the ECx-SyS model
 #'
 #' Convenience functions to plot the observed and modeled effect and the
 #' system stress with and without environmental stress.
@@ -10,20 +9,20 @@
 #' @name plot_ecxsys
 #'
 #' @param model The list returned from ecxsys().
-#' @param show_simple_model TODO: explain what this does and how it does it.
-#' @param show_legend A logical specifying if a legend should be included.
-#'   Defaults to FALSE because it may cover some points or lines
-#'   depending on the plot size.
+#' @param show_simple_model Should the log-logistic models be plotted for
+#'   comparison? Defaults to \code{FALSE}.
+#' @param show_legend Should the plot include a legend? Defaults to FALSE
+#'   because it may cover some points or lines depending on the plot size.
 #' @param xlab,ylab Axis labels.
 #'
-#' @examples mod <- ecxsys(
+#' @examples model <- ecxsys(
 #'     effect_tox_observed = c(85, 76, 94, 35, 0),
 #'     effect_tox_env_observed = c(24, 23, 32, 0, 0),
 #'     concentration = c(0, 0.03, 0.3, 3, 10),
-#'     hormesis_index = 3
+#'     hormesis_concentration = 0.3
 #' )
-#' plot_effect(mod)
-#' plot_system_stress(mod)
+#' plot_effect(model)
+#' plot_system_stress(model)
 NULL
 
 

R/stress_effect_conversion.R

-# FIXME: Make it absolutely clear what is meant with "effect" here. Mortality or
-# survival? It's survival. "Effect" is what's on the y axis. Low stress -> high
-# survival.
-
-
 #' Convert Between Stress and Effect
 #'
 #' Functions to convert effect to general stress or vice versa using the beta
@@ -15,11 +10,14 @@
 #' effect to the interval [0, 1] and then returns
 #' \code{qbeta(1 - effect, p, q)}.
 #'
+#' "Effect" is a response which is negatively correlated with stress. For
+#' example increasing toxicant concentration (stress) reduces survival (effect).
+#'
 #' @name Stressconversion
 #'
 #' @param effect One or more effect values to convert to general stress.
-#'   Should be a value between 0 and 1. Values outside that interval are clipped
-#'   to the interval edges.
+#'   Should be a value between 0 and 1. Smaller or bigger values are treated as
+#'   0 or 1 respectively.
 #' @param stress One or more stress values to convert to effect.
 #' @param p,q The shape parameters of the beta distribution. Default is 3.2.
 #'

man/Stressconversion.Rd

@@ -12,8 +12,8 @@ stress_to_effect(stress, p = 3.2, q = 3.2)
 }
 \arguments{
 \item{effect}{One or more effect values to convert to general stress.
-Should be a value between 0 and 1. Values outside that interval are clipped
-to the interval edges.}
+Should be a value between 0 and 1. Smaller or bigger values are treated as
+0 or 1 respectively.}
 
 \item{p, q}{The shape parameters of the beta distribution. Default is 3.2.}
 
@@ -30,6 +30,9 @@ These are simple wrappers around the beta distribution function
 \code{1 - pbeta(stress, p, q)}. \code{effect_to_stress} first clips the
 effect to the interval [0, 1] and then returns
 \code{qbeta(1 - effect, p, q)}.
+
+"Effect" is a response which is negatively correlated with stress. For
+example increasing toxicant concentration (stress) reduces survival (effect).
 }
 \examples{
 stress <- 0.3

man/ec.Rd

@@ -10,34 +10,34 @@ ec(model, effect_name, target_effect)
 \item{model}{The object returned from \code{ecxsys()}.}
 
 \item{effect_name}{The name of the effect for which you want to calculate the
-EC.}
+EC. Must be the name of a column in \code{model$curves}.}
 
 \item{target_effect}{The desired effect percentage between 0 and 100. For
 example with the value 10 the function will return the EC10, i.e. the
-concentration where the response falls below 90 % of the maximum possible
+concentration where the response falls below 90 \% of the maximum possible
 response.}
 }
 \value{
-A list with the elements \code{concentration} and \code{effect}
-  giving the effect concentration and the corresponding effect.
+A list containing the effect concentration and the corresponding
+  effect.
 }
 \description{
 Estimate the concentration to reach a certain effect relative to the control.
 }
 \details{
-If the value occurs multiple times because of hormesis, which may happen for
-low values of \code{target_effect}, then the first occurrence corresponding
-to the smaller concentration is returned by default (i.e. the lowest
-concentration)..
+If the response level occurs multiple times because of hormesis, which may
+happen for low values of \code{target_effect}, then the occurrence with the
+smallest concentration is returned.
 }
 \examples{
-result <- ecxsys(
+model <- ecxsys(
     concentration = c(0, 0.03, 0.3, 3, 10),
     effect_tox_observed = c(85, 76, 94, 35, 0),
     effect_tox_env_observed = c(24, 23, 32, 0, 0),
-    hormesis_index = 3
+    hormesis_concentration = 0.3
 )
-# Calculate the EC_10
-EC_10 <- ec(result, "effect_tox_sys", 10)
+# Calculate the EC_10, the concentration where the effect falls
+# below 90 \% of the effect in the control:
+ec_10 <- ec(model, "effect_tox_sys", 10)
 
 }

man/ecxsys.Rd

@@ -17,23 +17,25 @@ ecxsys(
 }
 \arguments{
 \item{concentration}{A vector of concentrations, one of which must be 0 to
-indicate the control.}
+indicate the control. Should be sorted in ascending order, otherwise it
+will be sorted automatically.}
 
 \item{effect_tox_observed}{A vector of effect values observed at the given
 concentrations and in absence of environmental stress. Values must be
 between 0 and \code{effect_max}.}
 
-\item{effect_tox_env_observed}{Effect values observed at the given
-concentrations and in the presence of environmental stress. Values must be
-between 0 and \code{effect_max}. This argument is optional and can be left
-out to model without environmental stress.}
+\item{effect_tox_env_observed}{Effect values observed in the presence of
+environmental stress. This argument is optional and can be left out to
+model without environmental stress. Values must be between 0 and
+\code{effect_max}.}
 
-\item{hormesis_concentration}{The concentration where the hormesis is.}
+\item{hormesis_concentration}{The concentration where the hormesis occurs.
+This is usually the concentration of the highest effect after the control.}
 
-\item{hormesis_index}{A single integer specifying the index of the hormesis
-concentration in the concentration vector. This argument exists for
-compatibility with older versions of this function. Use one of the the
-hormesis arguments but not both.}
+\item{hormesis_index}{\strong{Deprecated, will be removed soon.} A single
+integer specifying the index of the hormesis concentration in the
+concentration vector. This argument exists for compatibility with older
+versions of this function.}
 
 \item{effect_max}{The maximum value the effect could possibly reach. For
 survival data in percent this should be 100 (the default).}
@@ -41,20 +43,78 @@ 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{
-TODO: explain output list, especially the function fn
+The result is a list containing many different objects with the most
+  important being \code{curves} and \code{fn}. You can use \code{fn()} to
+  calculate the curves at your concentrations of choice, see examples.
+  \code{curves} is a data frame 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_simple}{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{effect_tox_sys}{Modeled effect resulting from toxicant and system
+    stress.}
+    \item{stress_tox}{The toxicant stress.}
+    \item{sys_stress_tox}{System stress under toxicant stress conditions
+    without environmental stress.}
+    \item{stress_tox_sys}{The sum of \code{stress_tox} and
+    \code{sys_stress_tox}.}
+    \item{effect_tox_env_simple}{The five-parameter log-logistic model of the
+    effect 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,
+    environmental and system stress.}
+    \item{stress_env}{Environmental stress.}
+    \item{stress_tox_env}{The sum of toxicant and environmental stress.}
+    \item{sys_stress_tox_env}{System stress under toxicant and
+    environmental stress conditions.}
+    \item{stress_tox_env_sys}{The sum of \code{stress_tox_env} and
+    \code{sys_stress_tox_env}.}
+    \item{use_for_plotting}{A boolean vector which is used in the plotting
+    functions. It controls which parts of the curves are removed for the
+    broken concentration axis.}
+  }
 }
 \description{
-The ECx-SyS model.
+The ECx-SyS model for modeling concentration-effect relationships which
+indicate signs of hormesis.
 }
 \details{
-TODO: improve this help text
+It is advised to complete the curve down to zero for optimal prediction.
+Therefore \code{effect_tox_observed} in the highest concentration should be
+at or close to zero. If the model does not fit properly try adding an effect
+of 0 at ten times the maximum observed concentration.
+
+The vectors \code{concentration}, \code{effect_tox_observed} and
+\code{effect_tox_env_observed} must be of equal length and should be sorted
+by increasing concentration.
 }
 \examples{
-result <- ecxsys(
+model <- ecxsys(
     concentration = c(0, 0.03, 0.3, 3, 10),
     effect_tox_observed = c(85, 76, 94, 35, 0),
     effect_tox_env_observed = c(24, 23, 32, 0, 0),
-    hormesis_index = 3
+    hormesis_concentration = 0.3
 )
 
+# Use effect_max if for example the effect is given as the number of
+# surviving animals and the initial number of animals is 20:
+model <- ecxsys(
+    concentration = c(0, 0.03, 0.3, 3, 10),
+    effect_tox_observed = c(17, 15.2, 18.8, 7, 0),
+    effect_tox_env_observed = c(4.8, 4.6, 6.4, 0, 0),
+    hormesis_concentration = 0.3,
+    effect_max = 20
+)
+
+# The returned object contains a function which is useful for calculating
+# effect and stress values at specific concentrations:
+model$fn(c(0, 0.01, 0.1, 1))
+
 }

man/plot_ecxsys.Rd

@@ -5,7 +5,7 @@
 \alias{plot_ecxsys}
 \alias{plot_effect}
 \alias{plot_system_stress}
-\title{Plot the result of the ECx-SyS model}
+\title{Plot the results of the ECx-SyS model}
 \usage{
 plot_effect(
   model,
@@ -20,11 +20,11 @@ plot_system_stress(model, show_legend = FALSE)
 \arguments{
 \item{model}{The list returned from ecxsys().}
 
-\item{show_simple_model}{TODO: explain what this does and how it does it.}
+\item{show_simple_model}{Should the log-logistic models be plotted for
+comparison? Defaults to \code{FALSE}.}
 
-\item{show_legend}{A logical specifying if a legend should be included.
-Defaults to FALSE because it may cover some points or lines
-depending on the plot size.}
+\item{show_legend}{Should the plot include a legend? Defaults to FALSE
+because it may cover some points or lines depending on the plot size.}
 
 \item{xlab, ylab}{Axis labels.}
 }
@@ -33,12 +33,12 @@ Convenience functions to plot the observed and modeled effect and the
 system stress with and without environmental stress.
 }
 \examples{
-mod <- ecxsys(
+model <- ecxsys(
     effect_tox_observed = c(85, 76, 94, 35, 0),
     effect_tox_env_observed = c(24, 23, 32, 0, 0),
     concentration = c(0, 0.03, 0.3, 3, 10),
-    hormesis_index = 3
+    hormesis_concentration = 0.3
 )
-plot_effect(mod)
-plot_system_stress(mod)
+plot_effect(model)
+plot_system_stress(model)
 }