Auto-detect flipped charts in theme_grattan

Add automatic detection of horizontal/flipped charts when theme_grattan() is added to a plot. Introduces ggplot_add.grattan_theme (R/detect_flipped.R) which inspects coord_flip() and mappings (discrete y + continuous/NULL x) and rebuilds the theme with flipped = TRUE when detected; a throttled message is shown (once per 8 hours). Change flipped default to NULL, store original args on the theme object for detection, and strip the custom class before delegating to ggplot2.

Author: mattdbowes

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(ggplot_add,grattan_theme)
 export(check_chart)
 export(check_chart_aspect_ratio)
 export(colour_text)
@@ -187,6 +188,7 @@ importFrom(dplyr,select)
 importFrom(dplyr,where)
 importFrom(ggplot2,.pt)
 importFrom(ggplot2,expand_scale)
+importFrom(ggplot2,ggplot_add)
 importFrom(ggplot2,last_plot)
 importFrom(ggplot2,scale_y_continuous)
 importFrom(ggplot2,update_geom_defaults)

NEWS.md

@@ -1,4 +1,5 @@
 # grattantheme 1.5
+* `theme_grattan()` now auto-detects horizontal/flipped charts and applies `flipped = TRUE` automatically. Detection triggers for `coord_flip()` and bar charts (discrete y + continuous x). A message is shown every 8 hours when auto-detection fires. Set `flipped = TRUE` explicitly to silence the message, or `flipped = FALSE` to opt out of auto-detection.
 * Renamed `check_chart_aspect_ratio()` to `check_chart()`.
 * Updated `grattan_point_filled` function signature for consistency with `geom_point`.
 * Updates `export_latex_code` for consistency with `grattan_save_overleaf`.

R/detect_flipped.R

@@ -0,0 +1,130 @@
+# Auto-detection of flipped/horizontal charts for theme_grattan()
+#
+# When theme_grattan() is added to a plot via `+`, the ggplot_add method
+# below inspects the plot to determine if it represents a horizontal/flipped
+# chart. If so, and the user hasn't explicitly set `flipped`, the theme is
+# rebuilt with flipped = TRUE and a throttled message is shown.
+
+
+#' @importFrom ggplot2 ggplot_add
+#' @export
+ggplot_add.grattan_theme <- function(object, plot, object_name) {
+  args <- attr(object, "grattan_args")
+
+  # Only run detection if flipped was left as NULL (the default)
+  # and chart_type is not "scatter" (scatter ignores flipped)
+  if (!is.null(args) &&
+      is.null(args$flipped) &&
+      args$chart_type != "scatter") {
+
+    if (.detect_flipped_chart(plot)) {
+      # Rebuild theme with flipped = TRUE
+      object <- theme_grattan_normal(
+        base_size = args$base_size,
+        base_family = args$base_family,
+        background = args$background,
+        legend = args$legend,
+        panel_borders = args$panel_borders,
+        flipped = TRUE
+      )
+
+      .notify_auto_flip()
+    }
+  }
+
+  # Strip custom class and attributes, delegate to standard theme adding
+  attr(object, "grattan_args") <- NULL
+  class(object) <- setdiff(class(object), "grattan_theme")
+
+  ggplot2::ggplot_add(object, plot, object_name)
+}
+
+
+# Detect if a plot represents a flipped/horizontal chart.
+# Returns TRUE only when confident; FALSE on any error or ambiguity.
+.detect_flipped_chart <- function(plot) {
+  tryCatch({
+    # 1. Check for coord_flip()
+    if (inherits(plot$coordinates, "CoordFlip")) {
+      return(TRUE)
+    }
+
+    # 2. Check plot-level mappings: discrete y + continuous x
+    if (.check_mappings_flipped(plot$mapping, plot$data)) {
+      return(TRUE)
+    }
+
+    # 3. Fallback: check first layer's mappings if plot-level is empty
+    if (length(plot$mapping) == 0 && length(plot$layers) > 0) {
+      layer <- plot$layers[[1]]
+      layer_data <- if (is.data.frame(layer$data)) layer$data else plot$data
+      if (is.data.frame(layer_data) && length(layer$mapping) > 0) {
+        if (.check_mappings_flipped(layer$mapping, layer_data)) {
+          return(TRUE)
+        }
+      }
+    }
+
+    FALSE
+  }, error = function(e) {
+    FALSE
+  })
+}
+
+
+# Check if a mapping + data combination indicates a flipped chart.
+# A chart is "flipped" when y maps to a discrete variable and x maps to
+# a continuous variable (or is absent/NULL).
+.check_mappings_flipped <- function(mapping, data) {
+  if (is.null(mapping) || length(mapping) == 0) return(FALSE)
+  if (!is.data.frame(data) || nrow(data) == 0) return(FALSE)
+
+  tryCatch({
+    y_val <- if (!is.null(mapping$y)) {
+      rlang::eval_tidy(mapping$y, data = data)
+    }
+
+    x_val <- if (!is.null(mapping$x)) {
+      rlang::eval_tidy(mapping$x, data = data)
+    }
+
+    y_is_discrete <- !is.null(y_val) &&
+      (is.factor(y_val) || is.character(y_val) || is.logical(y_val))
+
+    x_is_continuous_or_null <- is.null(x_val) || is.numeric(x_val)
+
+    y_is_discrete && x_is_continuous_or_null
+  }, error = function(e) {
+    FALSE
+  })
+}
+
+
+# Show a message when auto-flip is applied, throttled to once per 8 hours.
+# Uses an environment variable to track the last message time, following
+# the same pattern as overleaf_utils.R.
+.notify_auto_flip <- function() {
+  last_str <- Sys.getenv("GRATTANTHEME_FLIP_LAST_MESSAGE", unset = "")
+
+  should_message <- TRUE
+
+  if (last_str != "") {
+    tryCatch({
+      last_time <- as.POSIXct(last_str)
+      if (difftime(Sys.time(), last_time, units = "hours") < 8) {
+        should_message <- FALSE
+      }
+    }, error = function(e) {
+      # If timestamp can't be parsed, show the message
+    })
+  }
+
+  if (should_message) {
+    message(
+      "grattantheme: Auto-detected a horizontal/flipped chart and applied ",
+      "`flipped = TRUE`. Set `theme_grattan(flipped = TRUE)` explicitly to ",
+      "silence this message."
+    )
+    Sys.setenv(GRATTANTHEME_FLIP_LAST_MESSAGE = as.character(Sys.time()))
+  }
+}

R/theme_grattan.R

@@ -4,9 +4,12 @@
 #'   style guide.
 #' @param base_family Font family for text elements. Defaults to "sans".
 #' @param chart_type "normal" by detault. Set to "scatter" for scatter plots.
-#' @param flipped FALSE by default. Set to TRUE if using coord_flip(). If set to
-#'   TRUE, the theme will show a vertical axis line, ticks & panel grid, while
-#'   hiding the horizontals. Ignored for type = "scatter".
+#' @param flipped NULL by default. Set to TRUE if using coord_flip() or creating
+#'   horizontal bar charts. If set to TRUE, the theme will show a vertical axis
+#'   line, ticks & panel grid, while hiding the horizontals. Ignored for
+#'   type = "scatter". When NULL (the default), flipped formatting is
+#'   auto-detected when the theme is added to a plot. Set to FALSE explicitly
+#'   to override auto-detection.
 #' @param background "white" by default. Set to "orange" or "box" if you're
 #'   making a chart to go in a Grattan report box.
 #' @param legend "off" by default. Set to "bottom", "left", "right" or "top" as
@@ -109,7 +112,7 @@
 theme_grattan <- function(base_size = 18,
                           base_family = "sans",
                           chart_type = "normal",
-                          flipped = FALSE,
+                          flipped = NULL,
                           background = "white",
                           legend = "none",
                           panel_borders = FALSE) {
@@ -120,13 +123,17 @@ theme_grattan <- function(base_size = 18,
     chart_type <- "normal"
   }
 
+  # Resolve NULL → FALSE for building the theme; auto-detection
+  # happens later in ggplot_add.grattan_theme() when flipped is NULL
+  flipped_resolved <- isTRUE(flipped)
+
   if (chart_type == "normal") {
     ret <- theme_grattan_normal(base_size = base_size,
                                 base_family = base_family,
                                 background = background,
                                 legend = legend,
                                 panel_borders = panel_borders,
-                                flipped = flipped)
+                                flipped = flipped_resolved)
   }
 
   if (chart_type == "scatter") {
@@ -135,13 +142,26 @@ theme_grattan <- function(base_size = 18,
                                  background = background,
                                  legend = legend,
                                  panel_borders = panel_borders)
-    if (flipped) message("Note that the 'flipped' argument is ignored for scatter plots.")
+    if (isTRUE(flipped)) {
+      message("Note that the 'flipped' argument is ignored for scatter plots.")
+    }
   }
 
   # Call a function that modifies various geom defaults
   grattanify_geom_defaults()
 
-  # Return
+  # Store original arguments (including NULL flipped) for auto-detection
+  attr(ret, "grattan_args") <- list(
+    base_size = base_size,
+    base_family = base_family,
+    chart_type = chart_type,
+    flipped = flipped,
+    background = background,
+    legend = legend,
+    panel_borders = panel_borders
+  )
+  class(ret) <- c("grattan_theme", class(ret))
+
   return(ret)
 
 }