Convert proportion_ca to sa_contribution, part of #39

NEWS.md

 # stressaddition 3.0.0
 
-* Rename all instances of "effect" to "survival".
-* Rename all instances of "ec" to "lc".
-* Rename `predict_mixture()` to `multi_tox()`.
+* Renamed all instances of "effect" to "survival".
+* Renamed all instances of "ec" to "lc".
+* Renamed `predict_mixture()` to `multi_tox()`.
+* The argument `proportion_ca` in the mixture model `multi_tox` was renamed and its value reversed. It is now called `sa_contribution` and specifies the proportion of stress addition in the calculation of toxicant stress. To convert your code from the old version use this equation: sa_contribution = 1 - proportion_ca.
 
 # stressaddition 2.7.0
 

R/multi_tox.R

@@ -34,8 +34,9 @@
 #'   the mixture. Both vectors must either be the same length or the longer
 #'   length must be a multiple of the shorter length. That's because the shorter
 #'   concentration vector gets recycled to the length of the longer one.
-#' @param proportion_ca The proportion of concentration addition in the
-#'   calculation of the toxicant stress of the mixture. Must be between 0 and 1.
+#' @param sa_contribution The proportion of stress addition contributing to the
+#'   calculation of the toxicant stress in the mixture. Must be between 0 and 1
+#'   where 1 stands for 100 \% stress addition.
 #' @param survival_max Controls the scaling of the result. This represents the
 #'   maximum value the survival could possibly reach. For survival data in
 #'   percent this should be 100 (the default).
@@ -64,9 +65,9 @@
 #' # Example of symmetric prediction:
 #' conc_a <- c(0, 0.03, 0.3, 3)
 #' conc_b <- 5.5
-#' prop_ca <- 0.75
-#' mix_a <- multi_tox(toxicant_a , toxicant_b , conc_a, conc_b, prop_ca)
-#' mix_b <- multi_tox(toxicant_b , toxicant_a , conc_b, conc_a, prop_ca)
+#' sa_contrib <- 0.75
+#' mix_a <- multi_tox(toxicant_a , toxicant_b , conc_a, conc_b, sa_contrib)
+#' mix_b <- multi_tox(toxicant_b , toxicant_a , conc_b, conc_a, sa_contrib)
 #' identical(mix_a$survival, mix_b$survival)
 #'
 #' @export
@@ -74,7 +75,7 @@ multi_tox <- function(model_a,
                       model_b,
                       concentration_a,
                       concentration_b,
-                      proportion_ca = 0.5,
+                      sa_contribution = 0.5,
                       survival_max = 100) {
     stopifnot(
         inherits(model_a, "ecxsys"),
@@ -85,8 +86,8 @@ multi_tox <- function(model_a,
         length(concentration_b) > 0,
         all(!is.na(concentration_a)),
         all(!is.na(concentration_b)),
-        proportion_ca >= 0,
-        proportion_ca <= 1,
+        sa_contribution >= 0,
+        sa_contribution <= 1,
         model_a$args$p == model_b$args$p,
         model_a$args$q == model_b$args$q
     )
@@ -127,8 +128,8 @@ multi_tox <- function(model_a,
     sys_total <- (sys_a + sys_b) / 2
 
     # combined stress and result ------------------------------------------
-    proportion_sam <- 1 - proportion_ca
-    stress_tox_total <- stress_tox_ca * proportion_ca + stress_tox_sam * proportion_sam
+    ca_contribution <- 1 - sa_contribution
+    stress_tox_total <- stress_tox_sam * sa_contribution + stress_tox_ca * ca_contribution
     stress_total <- stress_tox_total + sys_total
     survival <- stress_to_survival(stress_total) * survival_max
 

man/multi_tox.Rd

 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/predict_mixture.R
+% Please edit documentation in R/multi_tox.R
 \name{multi_tox}
 \alias{multi_tox}
 \title{Predict the survival of a mixture of two toxicants}
@@ -9,7 +9,7 @@ multi_tox(
   model_b,
   concentration_a,
   concentration_b,
-  proportion_ca = 0.5,
+  sa_contribution = 0.5,
   survival_max = 100
 )
 }
@@ -21,8 +21,9 @@ the mixture. Both vectors must either be the same length or the longer
 length must be a multiple of the shorter length. That's because the shorter
 concentration vector gets recycled to the length of the longer one.}
 
-\item{proportion_ca}{The proportion of concentration addition in the
-calculation of the toxicant stress of the mixture. Must be between 0 and 1.}
+\item{sa_contribution}{The proportion of stress addition contributing to the
+calculation of the toxicant stress in the mixture. Must be between 0 and 1
+where 1 stands for 100 \% stress addition.}
 
 \item{survival_max}{Controls the scaling of the result. This represents the
 maximum value the survival could possibly reach. For survival data in
@@ -66,9 +67,9 @@ multi_tox(
 # Example of symmetric prediction:
 conc_a <- c(0, 0.03, 0.3, 3)
 conc_b <- 5.5
-prop_ca <- 0.75
-mix_a <- multi_tox(toxicant_a , toxicant_b , conc_a, conc_b, prop_ca)
-mix_b <- multi_tox(toxicant_b , toxicant_a , conc_b, conc_a, prop_ca)
+sa_contrib <- 0.75
+mix_a <- multi_tox(toxicant_a , toxicant_b , conc_a, conc_b, sa_contrib)
+mix_b <- multi_tox(toxicant_b , toxicant_a , conc_b, conc_a, sa_contrib)
 identical(mix_a$survival, mix_b$survival)
 
 }

tests/testthat/test-multi_tox.R

@@ -39,7 +39,7 @@ test_that("results have not changed", {
         model_b,
         c(0, 0.01, 0.1, 1, 7, 15),
         5,
-        0.3
+        0.7
     )
     reference <- data.frame(
         concentration_a = c(0, 0.01, 0.1, 1, 7, 15),
@@ -59,7 +59,7 @@ test_that("results have not changed", {
         model_b,
         c(0, 0.01, 0.1, 1, 7, 15),
         c(0, 0.02, 0.2, 2, 14, 30),
-        0.3
+        0.7
     )
     reference <- data.frame(
         concentration_a = c(0, 0.01, 0.1, 1, 7, 15),
@@ -79,7 +79,7 @@ test_that("results have not changed", {
         model_b,
         c(0, 0.01, 0.1, 1, 7, 15),
         c(0, 0.02, 0.2, 2, 14, 30),
-        0.3,
+        0.7,
         42
     )
     reference <- data.frame(
@@ -99,9 +99,9 @@ test_that("results have not changed", {
 test_that("predictions are symmetric", {
     conc_a <- c(0, 10^seq(log10(0.001), log10(40), length.out = 50))
     conc_b <- 3.5
-    prop_ca <- 0.8
-    survival_12 <- multi_tox(model_a, model_b, conc_a, conc_b, prop_ca)$survival
-    survival_21 <- multi_tox(model_b, model_a, conc_b, conc_a, prop_ca)$survival
+    sa_contrib <- 0.8
+    survival_12 <- multi_tox(model_a, model_b, conc_a, conc_b, sa_contrib)$survival
+    survival_21 <- multi_tox(model_b, model_a, conc_b, conc_a, sa_contrib)$survival
     expect_equal(survival_12, survival_21)
 })