updated summary and print methods, including documentation

R/helpers.R

@@ -271,9 +271,21 @@ clean_mod_weights <- function(x) {
 }
 
 #' @noRd
-clean_nec_vals <- function(x) {
-  mat <- t(as.matrix(x$w_nec))
-  rownames(mat) <- "NEC"
+clean_nec_vals <- function(x, all_models, ecx_models) {
+  if (is_bayesnecfit(x)) {
+    mat <- t(as.matrix(x$nec))
+  } else if (is_bayesmanecfit(x)) {
+    mat <- t(as.matrix(x$w_nec))
+  } else {
+    stop("Wrong input class.")
+  }
+  neclab <- "NEC"
+  if (all(all_models %in% ecx_models)) {
+    neclab <- "NSEC"
+  } else if (!is.null(ecx_models)) {
+    neclab <- "N(S)EC"
+  }
+  rownames(mat) <- neclab
   mat
 }
 

R/manecsummary-class.R

@@ -33,6 +33,8 @@
 #' \code{bayesnec:::summary.bayesnecfit} help file for details). Different
 #' from the single-model case of class \code{\link{bayesnecfit}}, these ECx
 #' estimates will be based on the model weights.
+#' @slot bayesr2 A table containing the Bayesian R2 for all models, as
+#' calculated by \code{\link[brms]{bayes_R2}}.
 #' @slot rhat_issues A \code{\link[base]{list}} detailing whether each fitted
 #' model exhibited convergence issues based on the Rhat evaluation.
 #'
@@ -43,6 +45,19 @@
 #'   \code{\link{bayesmanecfit}},
 #'   \code{\link{necsummary}}
 #'
+#' @references
+#' Fisher R, Fox DR (2023). Introducing the no significant effect concentration 
+#' (NSEC).Environmental Toxicology and Chemistry, 42(9), 2019–2028. 
+#' doi: 10.1002/etc.5610.
+#'
+#' Fisher R, Fox DR, Negri AP, van Dam J, Flores F, Koppel D (2023). Methods for
+#' estimating no-effect toxicity concentrations in ecotoxicology. Integrated 
+#' Environmental Assessment and Management. doi:10.1002/ieam.4809.
+#' 
+#' Fox DR (2010). A Bayesian Approach for Determining the No Effect
+#' Concentration and Hazardous Concentration in Ecotoxicology. Ecotoxicology
+#' and Environmental Safety, 73(2), 123–131. doi: 10.1016/j.ecoenv.2009.09.012.
+#'
 NULL
 
 #' Checks if argument is a \code{manecsummary} object

R/necsummary-class.R

@@ -22,9 +22,13 @@
 #' the fitted non-linear model.
 #' @slot is_ecx A \code{\link[base]{logical}} indicating whether \code{model}
 #' is an ECx-type model.
+#' @slot nec_vals The NEC values. Note that if model is an ECx-type model,
+#' this estimate will be a NSEC proxy.
 #' @slot ecs A \code{\link[base]{list}} containing the ECx values
 #' should the user decide to calculate them (see the non-exported
 #' \code{bayesnec:::summary.bayesnecfit} help file for details).
+#' @slot bayesr2 The model Bayesian R2 as calculated by
+#' \code{\link[brms]{bayes_R2}}.
 #'
 #' @seealso
 #'   \code{\link{bayesnec}},
@@ -33,6 +37,19 @@
 #'   \code{\link{bayesmanecfit}},
 #'   \code{\link{manecsummary}}
 #'
+#' @references
+#' Fisher R, Fox DR (2023). Introducing the no significant effect concentration 
+#' (NSEC).Environmental Toxicology and Chemistry, 42(9), 2019–2028. 
+#' doi: 10.1002/etc.5610.
+#'
+#' Fisher R, Fox DR, Negri AP, van Dam J, Flores F, Koppel D (2023). Methods for
+#' estimating no-effect toxicity concentrations in ecotoxicology. Integrated 
+#' Environmental Assessment and Management. doi:10.1002/ieam.4809.
+#' 
+#' Fox DR (2010). A Bayesian Approach for Determining the No Effect
+#' Concentration and Hazardous Concentration in Ecotoxicology. Ecotoxicology
+#' and Environmental Safety, 73(2), 123–131. doi: 10.1016/j.ecoenv.2009.09.012.
+#'
 NULL
 
 #' Checks if argument is a \code{necsummary} object

R/print.R

@@ -59,13 +59,15 @@ print.bayesmanecfit <- function(x, ...) {
 #' @export
 #' @noRd
 print.necsummary <- function(x, ...) {
-  cat("Object of class bayesnecfit containing the following",
-      " non-linear model: ", x$model, "\n\n", sep = "")
+  cat("Object of class bayesnecfit containing the", x$model,
+      "model\n\n", sep = " ")
   print(x$brmssummary)
+  cat("\n\n")
   if (x$is_ecx) {
-    cat("\nNB: Model ", x$model, " is an ECX model and so ",
-        "the NEC estimate is an NSEC surrogate.\n", sep = "")
+    cat("NB: Model", x$model, "is an ECx model, thus",
+        "the NEC estimate is an\n", "   NSEC surrogate.\n", sep = " ")
   }
+  print_mat(x$nec_vals)
   if (!is.null(x$ecs)) {
     cat("\n\n")
     for (i in seq_along(x$ecs)) {
@@ -102,19 +104,21 @@ print.manecsummary <- function(x, ...) {
   cat("Model weights (Method: ", x$mod_weights_method, "):\n", sep = "")
   print_mat(x$mod_weights)
   cat("\n\n")
-  cat("Summary of weighted NEC posterior estimates:\n")
-  if (!is.null(x$ecx_mods)) {
-    cat("NB: Model set contains the ECX models: ",
-        paste0(x$ecx_mods, collapse = ";"),
-        "; weighted NEC estimates include NSEC surrogates for NEC\n", sep = "")
+  neclab <- rownames(x$nec_vals)
+  cat("Summary of weighted", neclab, "posterior estimates:\n", sep = " ")
+  if (neclab == "N(S)EC") {
+    cat("NB: Model set contains a combination of ECx and NEC\n",
+        "    models, and is therefore a model averaged\n",
+        "    combination of NEC and NSEC estimates.\n", sep = "")
   }
   print_mat(x$nec_vals)
   cat("\n\n")
   if (!is.null(x$ecs)) {
     for (i in seq_along(x$ecs)) {
       nice_ecx_out(x$ecs[[i]], names(x$ecs)[i])
-      "\n\n"
+      cat("\n")
     }
+    cat("\n")
   }
   cat("Bayesian R2 estimates:\n")
   print_mat(x$bayesr2)

R/summary.R

@@ -16,9 +16,33 @@
 #' contents of a \code{\link[brms]{brmsfit}} object with the addition of
 #' an R2. In the case of a \code{\link{bayesmanecfit}} object, summary
 #' displays the family distribution information, model weights and averaging
-#' method, the estimated model-averaged NEC, and R2 estimates for each
-#' individual model. Warning messages are also printed to screen in case
+#' method, and Bayesian R2 estimates for each individual model.
+#' Warning messages are also printed to screen in case
 #' model fits are not satisfactory with regards to their Rhats.
+#' 
+#' @details The summary method for both \code{\link{bayesnecfit}} and 
+#' \code{\link{bayesmanecfit}} also returns a no-effect toxicity
+#' estimate. Where the fitted model(s) are NEC models (threshold models,
+#' containing a step function) the no-effect estimate is a true 
+#' no-effect-concentration (NEC, see Fox 2010). Where the fitted model(s) are 
+#' smooth ECx models with no step function, the no-effect estimate is a 
+#' no-significant-effect-concentration (NSEC, see Fisher and Fox 2023). In the 
+#' case of a \code{\link{bayesmanecfit}} that contains a mixture of both NEC and
+#' ECx models, the no-effect estimate is a model averaged combination of the NEC
+#' and NSEC estimates, and is reported as the N(S)EC (see Fisher et al. 2023).
+#' 
+#' @references
+#' Fisher R, Fox DR (2023). Introducing the no significant effect concentration 
+#' (NSEC).Environmental Toxicology and Chemistry, 42(9), 2019–2028. 
+#' doi: 10.1002/etc.5610.
+#'
+#' Fisher R, Fox DR, Negri AP, van Dam J, Flores F, Koppel D (2023). Methods for
+#' estimating no-effect toxicity concentrations in ecotoxicology. Integrated 
+#' Environmental Assessment and Management. doi:10.1002/ieam.4809.
+#' 
+#' Fox DR (2010). A Bayesian Approach for Determining the No Effect
+#' Concentration and Hazardous Concentration in Ecotoxicology. Ecotoxicology
+#' and Environmental Safety, 73(2), 123–131. doi: 10.1016/j.ecoenv.2009.09.012.
 #'
 #' @examples
 #' \donttest{
@@ -39,7 +63,7 @@ NULL
 #'
 #' @method summary bayesnecfit
 #'
-#' @inherit summary description return examples
+#' @inherit summary description return details examples
 #'
 #' @importFrom brms bayes_R2
 #' @importFrom chk chk_numeric chk_lgl
@@ -48,21 +72,27 @@ NULL
 summary.bayesnecfit <- function(object, ..., ecx = FALSE,
                                 ecx_vals = c(10, 50, 90)) {
   chk_lgl(ecx)
-  chk_numeric(ecx_vals)    
+  chk_numeric(ecx_vals)
   x <- object
   ecs <- NULL
   if (ecx) {
-    message("ECX calculation takes a few seconds per model, calculating...\n")
+    message("ECx calculation takes a few seconds per model, calculating...\n")
     ecs <- list()
     for (i in seq_along(ecx_vals)) {
       ecs[[i]] <- ecx(x, ecx_val = ecx_vals[i])
     }
     names(ecs) <- paste0("ECx (", ecx_vals, "%) estimate:")
   }
+  is_ecx <- x$model %in% mod_groups$ecx
+  ecx_mod <- NULL
+  if (is_ecx) {
+    ecx_mod <- x$model
+  }
   out <- list(
     brmssummary = cleaned_brms_summary(x$fit),
     model = x$model,
-    is_ecx = x$model %in% mod_groups$ecx,
+    is_ecx = is_ecx,
+    nec_vals = clean_nec_vals(x, x$model, ecx_mod),
     ecs = ecs,
     bayesr2 = bayes_R2(x$fit)
   )
@@ -74,7 +104,7 @@ summary.bayesnecfit <- function(object, ..., ecx = FALSE,
 #'
 #' @method summary bayesmanecfit
 #'
-#' @inherit summary description return examples
+#' @inherit summary description return details examples
 #'
 #' @importFrom purrr map
 #' @importFrom brms bayes_R2
@@ -88,7 +118,7 @@ summary.bayesmanecfit <- function(object, ..., ecx = FALSE,
   x <- object
   ecs <- NULL
   if (ecx) {
-    message("ECX calculation takes a few seconds per model, calculating...\n")
+    message("ECx calculation takes a few seconds per model, calculating...\n")
     ecs <- list()
     for (i in seq_along(ecx_vals)) {
       ecs[[i]] <- ecx(x, ecx_val = ecx_vals[i])
@@ -106,7 +136,7 @@ summary.bayesmanecfit <- function(object, ..., ecx = FALSE,
     mod_weights = clean_mod_weights(x),
     mod_weights_method = class(x$mod_stats$wi),
     ecx_mods = ecx_mods,
-    nec_vals = clean_nec_vals(x),
+    nec_vals = clean_nec_vals(x, x$success_models, ecx_mods),
     ecs = ecs,
     bayesr2 = x$mod_fits |>
       lapply(function(y)bayes_R2(y$fit)) |>

tests/testthat/test-bayesnec_methods.R

@@ -22,8 +22,8 @@ test_that("plot returns null, is invisible, and is silent", {
 test_that("summary behaves as expected", {
   summary_p <- suppressWarnings(summary(nec4param))
   expect_equal(class(summary_p), "necsummary")
-  expect_equal(names(summary_p), c("brmssummary", "model", "is_ecx", "ecs",
-                                   "bayesr2"))
+  expect_equal(names(summary_p), c("brmssummary", "model", "is_ecx", "nec_vals",
+                                   "ecs", "bayesr2"))
 })
 
 test_that("formula/model.frame behaves as expected", {