ROCCurveAtomic: Atomic ROC curve (internal)

In plotthis: High-Level Plotting Built Upon 'ggplot2' and Other Plotting Packages

Atomic ROC curve (internal)

Description

Core implementation for drawing a single Receiver Operating Characteristic (ROC) curve. This is the internal workhorse behind the exported ROCCurve function. It takes a single data frame (no split_by support) and returns a ggplot object.

Usage

ROCCurveAtomic(
  data,
  truth_by,
  score_by,
  pos_label = NULL,
  group_by = NULL,
  group_by_sep = "_",
  group_name = NULL,
  x_axis_reverse = FALSE,
  percent = FALSE,
  ci = NULL,
  n_cuts = 0,
  cutoffs_at = NULL,
  cutoffs_labels = NULL,
  cutoffs_accuracy = 0.01,
  cutoffs_pt_size = 5,
  cutoffs_pt_shape = 4,
  cutoffs_pt_stroke = 1,
  cutoffs_labal_fg = "black",
  cutoffs_label_size = 4,
  cutoffs_label_bg = "white",
  cutoffs_label_bg_r = 0.1,
  show_auc = c("auto", "none", "legend", "plot"),
  auc_accuracy = 0.01,
  auc_size = 4,
  increasing = TRUE,
  theme = "theme_this",
  theme_args = list(),
  palette = "Spectral",
  palcolor = NULL,
  palreverse = FALSE,
  alpha = 1,
  facet_by = NULL,
  facet_scales = "fixed",
  facet_ncol = NULL,
  facet_nrow = NULL,
  facet_byrow = TRUE,
  aspect.ratio = 1,
  legend.position = waiver(),
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = ifelse(x_axis_reverse, "Specificity", "1 - Specificity"),
  ylab = "Sensitivity",
  ...
)

Arguments

data	A data frame with the truth and score columns. See https://CRAN.R-project.org/package=plotROC for the expected format.
truth_by	A character string naming the column that contains the true class labels (binary outcome, 0/1 or TRUE/FALSE).
score_by	A character vector of column names containing the predicted scores (classifier output values). When multiple columns are provided, each column becomes a separate ROC curve grouped by a .group identifier. When multiple columns are used, group_by must be NULL.
pos_label	A character string specifying the positive class label in truth_by. When NULL (default), the labels are handled by the plotROC package: if truth_by is a factor, the last level is used; otherwise it is coerced to a factor with a warning.
group_by	A character vector of column names to group the ROC curve by. Each unique combination of group values renders a separate ROC curve. When score_by contains multiple columns, group_by must be NULL because the score columns themselves define the groups. Multiple group_by columns are concatenated with group_by_sep.
group_by_sep	A character string used to separate concatenated group_by columns. Default: "_".
group_name	A character string to use as the legend title for the ROC curve groups. When NULL (default), the group_by column name is used.
x_axis_reverse	A logical value. If TRUE, the x-axis is reversed (from 1 to 0), displaying specificity instead of 1 - specificity. The x-axis label automatically changes to "Specificity". Default: FALSE.
percent	A logical value. If TRUE, the x and y axes are displayed as percentages (0 to 100). Default: FALSE.
ci	A list of arguments passed to plotROC::geom_rocci() to add confidence intervals to the ROC curve. When NULL (default), no confidence intervals are drawn. Example: ci = list(sig.level = 0.05).
n_cuts	An integer specifying the number of evenly-spaced quantile-based cutoff points to annotate on the ROC curve. Quantiles are computed from the score_by distribution. Default: 0 (no quantile cutoffs). Ignored when cutoffs_at is non-NULL.
cutoffs_at	A vector of user-supplied cutoff values to annotate as points on the ROC curve. When non-NULL, overrides n_cuts. Accepts raw numeric score thresholds and/or named method strings from the optimal.cutpoints package for automatic optimal cutoff identification. Both cutoffs_at and cutoffs.labels are passed to plotROC::geom_roc(). Supported method values are: "CB" (cost-benefit method); "MCT" (minimises Misclassification Cost Term); "MinValueSp" (a minimum value set for Specificity); "MinValueSe" (a minimum value set for Sensitivity); "ValueSe" (a value set for Sensitivity); "MinValueSpSe" (a minimum value set for Specificity and Sensitivity); "MaxSp" (maximises Specificity); "MaxSe" (maximises Sensitivity); "MaxSpSe" (maximises Sensitivity and Specificity simultaneously); "MaxProdSpSe" (maximises the product of Sensitivity and Specificity); "ROC01" (minimises distance between ROC plot and point (0,1)); "SpEqualSe" (Sensitivity = Specificity); "Youden" (Youden Index); "MaxEfficiency" (maximises Efficiency/Accuracy); "Minimax" (minimises the most frequent error); "MaxDOR" (maximises Diagnostic Odds Ratio); "MaxKappa" (maximises Kappa Index); "MinValueNPV" (a minimum value set for Negative Predictive Value); "MinValuePPV" (a minimum value set for Positive Predictive Value); "ValueNPV" (a value set for Negative Predictive Value); "ValuePPV" (a value set for Positive Predictive Value); "MinValueNPVPPV" (a minimum value set for Predictive Values); "PROC01" (minimises distance between PROC plot and point (0,1)); "NPVEqualPPV" (Negative Predictive Value = Positive Predictive Value); "MaxNPVPPV" (maximises Positive and Negative Predictive Values simultaneously); "MaxSumNPVPPV" (maximises the sum of the Predictive Values); "MaxProdNPVPPV" (maximises the product of Predictive Values); "ValueDLR.Negative" (a value set for Negative Diagnostic Likelihood Ratio); "ValueDLR.Positive" (a value set for Positive Diagnostic Likelihood Ratio); "MinPvalue" (minimises p-value of the Chi-squared test); "ObservedPrev" (closest value to observed prevalence); "MeanPrev" (closest value to the mean of the test values); "PrevalenceMatching" (predicted prevalence equals observed prevalence).
cutoffs_labels	A character vector of user-supplied labels for the cutoff points. Must be the same length as cutoffs_at. When NULL, labels are generated automatically (score value or method name).
cutoffs_accuracy	A numeric value controlling the rounding precision of automatically generated cutoff labels. Default: 0.01.
cutoffs_pt_size	A numeric value specifying the size of the cutoff point markers. Default: 5.
cutoffs_pt_shape	A numeric value specifying the shape of the cutoff point markers. Default: 4 (cross).
cutoffs_pt_stroke	A numeric value specifying the stroke width of the cutoff point markers. Default: 1.
cutoffs_labal_fg	A character string specifying the text colour of the cutoff labels. Default: "black".
cutoffs_label_size	A numeric value specifying the font size of the cutoff labels. Default: 4.
cutoffs_label_bg	A character string specifying the background colour of the cutoff labels. Default: "white".
cutoffs_label_bg_r	A numeric value specifying the background radius of the cutoff labels (passed to ggrepel::geom_text_repel()). Default: 0.1.
show_auc	A character string specifying the display mode for AUC values: "auto" (default): Automatically determine the position. When there is a single group or facet_by is provided, AUC is placed on the plot; otherwise AUC is placed in the legend. "none": Do not display AUC values. "legend": Display AUC values in the legend labels. "plot": Display AUC values as text on the plot.
auc_accuracy	A numeric value controlling the rounding precision of AUC values in labels. Default: 0.01.
auc_size	A numeric value specifying the font size of AUC labels when displayed on the plot. Default: 4.
increasing	A logical value. If TRUE (default), higher scores indicate the positive class; if FALSE, lower scores indicate the positive class. Controls the direction of comparison in the ROC analysis.
theme	A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use. Default is "theme_this".
theme_args	A list of arguments to pass to the theme function.
palette	A character string specifying the palette to use. A named list or vector can be used to specify the palettes for different split_by values.
palcolor	A character string specifying the color to use in the palette. A named list can be used to specify the colors for different split_by values. If some values are missing, the values from the palette will be used (palcolor will be NULL for those values).
palreverse	A logical value indicating whether to reverse the palette. Default is FALSE.
alpha	A numeric value specifying the transparency of the plot.
facet_by	A character string specifying the column name of the data frame to facet the plot. Otherwise, the data will be split by split_by and generate multiple plots and combine them into one using patchwork::wrap_plots
facet_scales	Whether to scale the axes of facets. Default is "fixed" Other options are "free", "free_x", "free_y". See ggplot2::facet_wrap
facet_ncol	A numeric value specifying the number of columns in the facet. When facet_by is a single column and facet_wrap is used.
facet_nrow	A numeric value specifying the number of rows in the facet. When facet_by is a single column and facet_wrap is used.
facet_byrow	A logical value indicating whether to fill the plots by row. Default is TRUE.
aspect.ratio	A numeric value specifying the aspect ratio of the plot.
legend.position	A character string specifying the position of the legend. if waiver(), for single groups, the legend will be "none", otherwise "right".
legend.direction	A character string specifying the direction of the legend.
title	A character string specifying the title of the plot. A function can be used to generate the title based on the default title. This is useful when split_by is used and the title needs to be dynamic.
subtitle	A character string specifying the subtitle of the plot.
xlab	A character string specifying the x-axis label.
ylab	A character string specifying the y-axis label.
...	Additional arguments.

Details

The function produces an ROC curve using plotROC::geom_roc(), with the following capabilities:

• Multiple classifiers — score_by accepts multiple column names, automatically pivoting them into a grouped format so several prediction scores can be compared on a single plot.

• AUC calculation — area under the curve is computed via plotROC::calc_auc() and displayed either on the plot or in the legend, controlled by show_auc.

• Cutoff annotation — user-specified cutoffs (numeric score thresholds or named optimal-cutoff methods from the OptimalCutpoints package) are rendered as markers with labels, using ggrepel::geom_text_repel() for label placement.

• Confidence intervals — optional ROC confidence bands via plotROC::geom_rocci().

• Axis flexibility — supports reversed x-axis (displaying specificity) and percent-scaled axes.

Value

A ggplot object with height and width attributes (in inches) attached, plus attr(p, "auc") and attr(p, "cutoffs") data frames.

Architecture

1. show_auc resolution — match.arg() resolves show_auc to one of "auto", "none", "legend", or "plot".

2. Column validation — check_columns() validates truth_by (single column), score_by (multiple allowed), and group_by (factor, multi-column concatenated). An error is raised if group_by is provided alongside multiple score_by columns.

3. Positive label encoding — Converts truth_by to binary numeric (0/1) with three paths:

   • pos_label provided: re-factor with pos_label as the last level, then convert.

   • truth_by is a factor: warn that the last level is treated as positive, then convert.

   • Non-numeric, non-factor: coerce to factor, warn, then convert.

4. Multi-score_by expansion — When score_by contains multiple columns, tidyr::pivot_longer() reshapes into a single .score column with a .group identifier, which becomes the group_by variable.

5. ggplot dispatch — Selects gglogger::ggplot or ggplot2::ggplot based on getOption("plotthis.gglogger.enabled").

6. Dummy group insertion — When group_by = NULL, creates a synthetic ..group column (constant "") so the curve still renders. The legend is suppressed ("none").

7. Auto AUC placement — When show_auc = "auto", single-group or faceted plots place AUC on the plot; multi-group plots place it in the legend.

8. Base ROC geometry — plotROC::geom_roc() with aes(d = truth, m = score, color = group), controlling direction via the increasing parameter.

9. AUC calculation — Temporarily facets via facet_plot(), then computes per-group (and per-facet) AUC values via plotROC::calc_auc().

10. Cutoff computation — get_cutoffs_data() combines group_by and facet_by columns into a .cat identifier and computes per-category cutoff data, supporting both numeric thresholds and named OptimalCutpoints methods.

11. Cutoff rendering — When cutoff data is non-NULL, splits the .cat column back into group/facet columns and adds geom_point() (markers) and geom_text_repel() (labels) with configurable size, shape, stroke, colour, and background styling.

12. Confidence intervals — When ci is non-NULL, plotROC::geom_rocci() is added with the provided arguments.

13. AUC display — Three modes:

    • "plot": geom_text() places AUC labels at a corner position determined by increasing and x_axis_reverse.

    • "legend": AUC values are appended to the scale_color_manual() labels (with per-facet prefixes when faceting is active).

    • "none": group level names are used as-is.

14. Diagonal reference — geom_abline() draws the no-discrimination line (y = x, or y = -x when x-axis is reversed) as a dashed grey line.

15. Color scale — scale_color_manual() assigns palette-derived colours via palette_this(), with AUC-augmented labels when show_auc = "legend".

16. Axis formatting — Percent labels on y-axis (and x-axis) when percent = TRUE. X-axis reversed (1 to 0) when x_axis_reverse = TRUE, changing the axis label to "Specificity".

17. Labels and theme — labs() sets title, subtitle, x, and y labels. The theme, aspect ratio, legend position/direction, and dashed grid lines are applied.

18. Dimension calculation — calculate_plot_dimensions() computes height and width attributes from base_height = 4.5, aspect ratio, and legend metrics.

19. Attribute storage — auc and cutoffs data frames are stored as attr(p, "auc") and attr(p, "cutoffs") for retrieval by the exported wrapper.

20. Faceting — facet_plot() wraps the plot with facet_wrap / facet_grid if facet_by is provided.

plotthis documentation built on July 9, 2026, 5:07 p.m.