Deprecate guides (#179)

* mark functions as deprecated

* replace tests

* deprecate dendrograms

* remove tests

* redocument

* adapt vignettes

* adapt example

* adapt readme

* remove references to deleted vignette

* add news bullet

* add news bullet

NEWS.md

@@ -1,5 +1,19 @@
 # ggh4x (development version)
 
+* The following functions have been deprecated in favour of both base ggplot2 and
+  the legendry package. They are scheduled to be removed in the next non-hotfix
+  update.
+    * `scale_x_dendrogram()` and `scale_y_dendrogram()` in favour of 
+    `legendry::scale_x_dendro()` and `legendry::scale_y_dendro()`.
+    * `guide_dendro()` in favour of `legendry::guide_axis_dendro()`.
+    * `guide_axis_truncated()` in favour of `ggplot2::guide_axis(cap = TRUE)`.
+    * `guide_axis_colour()` in favour of `ggplot2::guide_axis(theme = ...)`.
+    * `guide_axis_minor()` in favour of 
+    `ggplot2::guide_axis(minor.ticks = TRUE)`.
+    * `guide_axis_logticks()` in favour of `ggplot2::guide_axis_logticks()`.
+    * `guide_axis_nested()` in favour of `legendry::guide_axis_nested()`.
+    * `guide_axis_manual()` in favour of `legendry::guide_axis_base(key = ...)`.
+    * `guide_axis_scalebar()` in favour of `legendry::primitive_bracket()`.
 * `guide_stringlegend()` has been modernised to use the ggplot2 3.5.0 guide
   system instead of the old S3 system.
 * Facets allow take the `strip` as strings and functions too.

R/coord_axes_inside.R

@@ -44,7 +44,7 @@ NULL
 #' p + coord_axes_inside(xintercept = -5, yintercept = Inf, clip = "off")
 #'
 #' # Can be combined with other non-default axes
-#' p + guides(x = "axis_minor") +
+#' p + guides(x = guide_axis(minor.ticks = TRUE)) +
 #'   coord_axes_inside()
 coord_axes_inside <- function(
   xlim = NULL, ylim = NULL,

R/guide_axis_logticks.R

@@ -1,14 +1,15 @@
 # User function -----------------------------------------------------------
 
+# nocov start
+
 #' Axis guide with ticks for logarithmic breaks
 #'
-#' `r lifecycle::badge("questioning")`
+#' `r lifecycle::badge("deprecated")`
 #' This axis guide is probably best described as
 #' [ggplot2::annotation_logticks()] but implemented as a guide instead
 #' of a geom. The tick marks probably best suit log10 transformations.
-#' The function is questioned due to
-#' a possible migration of guide functions after ggplot2 releases a new guide
-#' system.
+#' The function is deprecated because ggplot2 implemented a better log tick
+#' axis.
 #'
 #' @inheritParams guide_axis_minor
 #' @param prescaled A `logical` of length one, indicating whether the data
@@ -36,6 +37,7 @@
 #' @return An *axis_logticks* guide class object.
 #' @rawNamespace if (packageVersion("ggplot2") <= "3.5.0") export(guide_axis_logticks)
 #' @family axis-guides
+#' @keywords internal
 #'
 #' @examples
 #' # The guide works well out of the box with log10 scales
@@ -70,6 +72,11 @@ guide_axis_logticks <- function(
   color = NULL,
   base = waiver()
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "ggh4x::guide_axis_logticks()",
+    "ggplot2::guide_axis_logticks()"
+  )
   colour <- color %||% colour
   check_trunc_arg(trunc_lower, trunc_upper)
   structure(list(
@@ -213,3 +220,5 @@ make_logbreaks <- function(base = 10, ticks_per_base = base - 1,
 
   return(tickdf)
 }
+
+# nocov end

R/guide_axis_manual.R

@@ -1,17 +1,18 @@
 # Constructor -------------------------------------------------------------
 
+# nocov start
+
 #' Manual axis
 #'
-#' `r lifecycle::badge("questioning")`
+#' `r lifecycle::badge("deprecated")`
 #' This axis allows a greater degree of control than the default axes guides. In
 #' particular, this axis allows setting break positions and labels independently
 #' from the scale and is not bound by the same constraints as secondary axes.
 #' Additionally, label attributes may be set in parallel to the labels
 #' themselves, circumventing the unsupported vectorised input to
 #' `element_text()`.
-#' The function is questioned due to
-#' a possible migration of guide functions after ggplot2 releases a new guide
-#' system.
+#' The function is deprecated due to superior alternatives such as
+#' `legendry::guide_axis_base()`.
 #'
 #' @inheritParams guide_axis_truncated
 #' @param breaks One of the following ways to parametrise the tick and label
@@ -43,6 +44,7 @@
 #'   are taken from the theme.
 #'
 #' @return An *axis_manual* guide class object.
+#' @keywords internal
 #' @export
 #' @family axis-guides
 #' @md
@@ -86,6 +88,12 @@ guide_axis_manual <- function(
   trunc_upper = NULL,
   position = waiver()
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "guide_axis_manual()",
+    "legendry::guide_axis_base()"
+  )
+
   colour <- color %||% colour
   label_colour <- label_color %||% label_colour
   check_trunc_arg(trunc_lower, trunc_upper)
@@ -320,3 +328,5 @@ draw_axis_manual <- function(
     params = params
   )
 }
+
+# nocov end

R/guide_axis_minor.R

@@ -1,13 +1,14 @@
 # User function -----------------------------------------------------------
 
+# nocov start
+
 #' Axis guide with ticks for minor breaks
 #'
-#' `r lifecycle::badge("questioning")`
+#' `r lifecycle::badge("deprecated")`
 #' These are similar the the normal axis guides for position scales, but also
 #' place tickmarks at minor break positions.
-#' The function is questioned due to
-#' a possible migration of guide functions after ggplot2 releases a new guide
-#' system.
+#' The function is deprecated because it can be replaced with
+#' `ggplot2::guide_axis(minor.ticks = TRUE)`.
 #'
 #' @inheritParams guide_axis_truncated
 #'
@@ -23,6 +24,7 @@
 #'
 #' @return An *axis_minor* guide class object.
 #' @export
+#' @keywords internal
 #'
 #' @family axis-guides
 #'
@@ -51,6 +53,11 @@ guide_axis_minor <- function(
   trunc_upper = NULL,
   position = waiver()
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "guide_axis_minor()",
+    I("`ggplot2::guide_axis(minor.ticks = TRUE)`")
+  )
   colour <- color %||% colour
   check_trunc_arg(trunc_lower, trunc_upper)
   structure(
@@ -204,6 +211,7 @@ build_axis_ticks_minor <- function(element, length, position, params,
   do.call(element_grob, args)
 }
 
+# nocov end
 
 
 

R/guide_axis_nested.R

@@ -1,15 +1,16 @@
 # User function -----------------------------------------------------------
 
+# nocov start
+
 #' Nested axis guide
 #'
-#' `r lifecycle::badge("questioning")`
+#' `r lifecycle::badge("deprecated")`
 #' Discrete position scales containing interacting factors can be visualised
 #' more clearly with a nested axis guide. Nested axis guides separate labels
 #' based on a delimiter and groups identical later labels, indicating the
 #' grouping with a line spanning the earlier labels.
-#' The function is questioned due to
-#' a possible migration of guide functions after ggplot2 releases a new guide
-#' system.
+#' The function is deprecated due to superior alternatives such as
+#' `legendry::guide_axis_nested()`.
 #'
 #' @inheritParams guide_axis_truncated
 #' @param delim A `character` of length 1 to tell `strsplit` how
@@ -44,6 +45,7 @@
 #'   `interaction()`.
 #'
 #' @export
+#' @keywords internal
 #'
 #' @family axis-guides
 #'
@@ -84,6 +86,11 @@ guide_axis_nested <- function(
   color = NULL,
   extend = 0.5
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "guide_axis_nested()",
+    "legendry::guide_axis_nested()"
+  )
   colour <- color %||% colour
   check_trunc_arg(trunc_lower, trunc_upper)
   structure(
@@ -291,3 +298,5 @@ build_axis_labels_nested <- function(elements, labels, position, dodge = 1,
 
   c(first_labels, later_labels)
 }
+
+# nocov end

R/guide_axis_scalebar.R

@@ -1,13 +1,14 @@
 # User function -----------------------------------------------------------
 
+# nocov start
+
 #' Scale bar axis guide
 #'
-#' `r lifecycle::badge("questioning")`
+#' `r lifecycle::badge("deprecated")`
 #' This axis guides draws a scale bar to indicate a distance rather than
 #' mark absolute values.
-#' The function is questioned due to
-#' a possible migration of guide functions after ggplot2 releases a new guide
-#' system.
+#' The function is deprecated due to superior alternatives such as
+#' `legendry::primitive_bracket()`.
 #'
 #' @inheritParams guide_axis_truncated
 #' @param size A `numeric(1)` for a distance to indicate, in data units. If
@@ -43,6 +44,7 @@
 #'
 #' @return A `axis_scalebar` guide class object.
 #' @family axis-guides
+#' @keywords internal
 #' @export
 #'
 #' @examples
@@ -72,6 +74,11 @@ guide_axis_scalebar <- function(
   just     = 1,
   position = waiver()
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "guide_axis_scalebar()",
+    "legendry::primitive_bracket()"
+  )
   colour <- color %||% colour
   structure(
     list(
@@ -225,4 +232,5 @@ build_scalebar_bar <- function(
   do.call(element_grob, args)
 }
 
+# nocov end
 

R/guide_axis_truncated.R

@@ -1,16 +1,17 @@
 # User function -----------------------------------------------------------
 
+# nocov start
+
 #' Axis guide with truncated line
 #'
-#' `r lifecycle::badge("questioning")`
+#' `r lifecycle::badge("deprecated")`
 #' This axis guide is similar to the normal axis guides for position scales, but
 #' can shorten the axis line that is being drawn. The `guide_axis_colour()`
 #' function is the same but with different defaults for the truncation that do
 #' not truncate the axis. Axis truncation and recolouring is supported
 #' throughout axes in ggh4x.
-#' The function is questioned due to
-#' a possible migration of guide functions after ggplot2 releases a new guide
-#' system.
+#' The function is deprecated as `ggplot2::guide_axis(cap = TRUE)` has this
+#' functionality now.
 #'
 #' @inheritParams ggplot2::guide_axis
 #' @param trunc_lower,trunc_upper The lower and upper range of the truncated
@@ -28,6 +29,7 @@
 #' @return An *axis_ggh4x* guide class object.
 #' @export
 #' @family axis-guides
+#' @keywords internal
 #' @md
 #'
 #' @examples
@@ -71,6 +73,11 @@ guide_axis_truncated <- function(
   trunc_upper = max,
   position = waiver()
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "guide_axis_truncated()",
+    I("`ggplot2::guide_axis(cap = TRUE)`")
+  )
   colour <- color %||% colour
   check_trunc_arg(trunc_lower, trunc_upper)
   structure(
@@ -105,6 +112,11 @@ guide_axis_colour <- function(
   trunc_upper = NULL,
   position = waiver()
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "guide_axis_truncated()",
+    I("`ggplot2::guide_axis(cap = TRUE)`")
+  )
   colour <- color %||% colour
   check_trunc_arg(trunc_lower, trunc_upper)
   structure(
@@ -364,3 +376,4 @@ check_trunc_arg <- function(lower, upper) {
   }
 }
 
+# nocov end

R/guide_axis_utils.R

@@ -1,3 +1,5 @@
+# nocov start
+
 build_axis_elements <- function(
   axis_position = "b", angle = NULL, theme, colour = NULL
 ) {
@@ -182,3 +184,5 @@ setup_axis_params <- function(axis_position) {
        opposite_axis = axis_opposite,
        vertical = is_vertical)
 }
+
+# nocov end

R/guide_dendrogram.R

@@ -1,10 +1,14 @@
 # Constructor -------------------------------------------------------------
 
+# nocov start
+
 #' Dendrogram guide
 #'
+#' `r lifecycle::badge("deprecated")`
 #' Visual representation of a discrete variable with hierarchical relationships
 #' between members, like those detailed in
-#' [`scale_(x|y)_dendrogram)()`][scale_x_dendrogram].
+#' [`scale_(x|y)_dendrogram)()`][scale_x_dendrogram]. This function is
+#' deprecated in favour of `legendry::guide_axis_dendro()`.
 #'
 #' @inheritParams guide_axis_truncated
 #' @param label A `logical(1)`. If `TRUE`, labels are drawn at the
@@ -17,6 +21,7 @@
 #'   to 10 times the `axis.ticks.length` theme element.
 #'
 #' @export
+#' @keywords internal
 #'
 #' @return A *dendroguide* class object.
 #'
@@ -54,6 +59,11 @@ guide_dendro <- function(
   color = NULL,
   dendro = waiver()
 ) {
+  lifecycle::deprecate_warn(
+    "0.3.0",
+    "ggh4x::guide_dendro()",
+    "legendry::guide_axis_dendro()"
+  )
   colour <- color %||% colour
   check_trunc_arg(trunc_lower, trunc_upper)
   structure(
@@ -209,3 +219,5 @@ draw_dendroguide <- function(
     params = params
   )
 }
+
+# nocov end