[docs] Details to performance_roc()

NAMESPACE

@@ -26,6 +26,7 @@ S3method(as.data.frame,r2_bayes)
 S3method(as.data.frame,r2_loo)
 S3method(as.data.frame,r2_nakagawa)
 S3method(as.numeric,check_outliers)
+S3method(as.numeric,performance_roc)
 S3method(check_autocorrelation,default)
 S3method(check_collinearity,BFBayesFactor)
 S3method(check_collinearity,MixMod)

R/performance_roc.R

@@ -4,6 +4,15 @@
 #' @description This function calculates a simple ROC curves of x/y coordinates
 #' based on response and predictions of a binomial model.
 #'
+#' It returns the area under the curve (AUC) as a percentage, which corresponds
+#' to the probability that a randomly chosen observation of "condition 1" is correctly
+#' classified by the model as having a higher probability of being "condition 1" than
+#' a randomly chosen "condition 2" observation.
+#'
+#' Applying `as.data.frame()` to the output returns a data frame containing the following:
+#' - `Sensitivity` (that actually corresponds to `1 - Specificity`): It is the False Positive Rate.
+#' - `Sensitivity`: It is the True Positive Rate, which is the proportion of correctly classified "condition 1" observations.
+#'
 #' @param x A numeric vector, representing the outcome (0/1), or a model with
 #'   binomial outcome.
 #' @param predictions If `x` is numeric, a numeric vector of same length
@@ -33,6 +42,7 @@
 #'
 #' model <- glm(y ~ Sepal.Length + Sepal.Width, data = train_data, family = "binomial")
 #' as.data.frame(performance_roc(model, new_data = test_data))
+#' as.numeric(performance_roc(model))
 #'
 #' roc <- performance_roc(model, new_data = test_data)
 #' area_under_curve(roc$Specificity, roc$Sensitivity)
@@ -53,7 +63,7 @@
 
   object_names <- c(
     insight::safe_deparse_symbol(substitute(x)),
     sapply(match.call(expand.dots = FALSE)$`...`, insight::safe_deparse)
   )
 
   if (insight::is_model(x)) {
@@ -109,6 +119,21 @@
 }
 
 
+#' @export
+as.numeric.performance_roc <- function(x, ...) {
+  if (length(unique(x$Model)) == 1) {
+    auc <- bayestestR::area_under_curve(x$Specificity, x$Sensitivity)
+  } else {
+    dat <- split(x, f = x$Model)
+
+    auc <- c()
+    for (i in seq_along(dat)) {
+      auc <- c(auc, bayestestR::area_under_curve(dat[[i]]$Specificity, dat[[i]]$Sensitivity))
+    }
+  }
+  auc
+}
+
 
 # utilities ---------------------------