greater use of waivers, for #220, and extensive doc cleanup

DESCRIPTION

@@ -99,6 +99,7 @@ Collate:
     "point_interval.R"
     "position_dodgejust.R"
     "pr.R"
+    "rd_density.R"
     "rd_dotsinterval.R"
     "rd_slabinterval.R"
     "rd_spike.R"

R/abstract_stat_slabinterval.R

@@ -20,7 +20,7 @@ AbstractStatSlabinterval = ggproto("AbstractStatSlabinterval", AbstractStat,
 
   default_params = defaults(list(
     limits = NULL,
-    n = 501,
+    n = waiver(),
 
     point_interval = NULL,
     .width = c(0.66, 0.95),
@@ -146,7 +146,9 @@ AbstractStatSlabinterval = ggproto("AbstractStatSlabinterval", AbstractStat,
 
     # figure out the points at which values the slab functions should be evaluated
     # we set up the grid in the transformed space
-    input = trans$inverse(seq(trans$transform(limits[[1]]), trans$transform(limits[[2]]), length.out = n))
+    input = trans$inverse(
+      seq(trans$transform(limits[[1]]), trans$transform(limits[[2]]), length.out = n %|W|% 501)
+    )
 
 
     # POINT/INTERVAL PRE-CALCULATIONS

R/auto_partial.R

@@ -228,6 +228,8 @@ print.ggdist_partial_function = function(x, ...) {
 }
 
 
+# waiver ------------------------------------------------------------------
+
 #' A waived argument
 #'
 #' A flag indicating that the default value of an argument should be used.
@@ -270,3 +272,10 @@ print.ggdist_partial_function = function(x, ...) {
 #' @importFrom ggplot2 waiver
 #' @export
 waiver = ggplot2::waiver
+
+#' waiver-coalescing operator
+#' @noRd
+`%|W|%` = function (x, y) {
+  if (inherits(x, "waiver")) y
+  else x
+}

R/density.R

@@ -20,12 +20,11 @@
 #'   - a function: a function taking `x` (the sample) and returning the bandwidth
 #'   - a string: the suffix of the name of a function starting with `"bandwidth_"` that
 #'     will be used to determine the bandwidth. See [bandwidth] for a list.
-#' @param adjust numeric: the bandwidth for the density estimator is multiplied
-#' by this value. See [stats::density()].
+#' @eval rd_param_density_adjust()
 #' @param kernel string: the smoothing kernel to be used. This must partially
 #' match one of `"gaussian"`, `"rectangular"`, `"triangular"`, `"epanechnikov"`,
 #' `"biweight"`, `"cosine"`, or `"optcosine"`. See [stats::density()].
-#' @param trim Should the density estimate be trimmed to the bounds of the data?
+#' @eval rd_param_density_trim()
 #' @param adapt (**very experimental**) The name and interpretation of this argument
 #' are subject to change without notice. Positive integer. If `adapt > 1`, uses
 #' an adaptive approach to calculate the density. First, uses the
@@ -77,7 +76,7 @@
 #' @export
 density_unbounded = auto_partial(name = "density_unbounded", function(
   x, weights = NULL,
-  n = 512, bandwidth = "dpi", adjust = 1, kernel = "gaussian",
+  n = 501, bandwidth = "dpi", adjust = 1, kernel = "gaussian",
   trim = TRUE,
   adapt = 1,
   na.rm = FALSE,
@@ -191,7 +190,7 @@ density_unbounded = auto_partial(name = "density_unbounded", function(
 #' @export
 density_bounded = auto_partial(name = "density_bounded", function(
   x, weights = NULL,
-  n = 512, bandwidth = "dpi", adjust = 1, kernel = "gaussian",
+  n = 501, bandwidth = "dpi", adjust = 1, kernel = "gaussian",
   trim = TRUE, bounds = c(NA, NA), bounder = "cdf",
   adapt = 1,
   na.rm = FALSE,
@@ -265,35 +264,8 @@ density_bounded = auto_partial(name = "density_bounded", function(
 #'
 #' @param x numeric vector containing a sample to compute a density estimate for.
 #' @param weights optional numeric vector of weights to apply to `x`.
-#' @param breaks Determines the breakpoints defining bins. Defaults to `"Scott"`.
-#' Similar to (but not exactly the same as) the `breaks` argument to [graphics::hist()].
-#' One of:
-#'   - A scalar (length-1) numeric giving the number of bins
-#'   - A vector numeric giving the breakpoints between histogram bins
-#'   - A function taking `x` and `weights` and returning either the
-#'     number of bins or a vector of breakpoints
-#'   - A string giving the suffix of a function that starts with
-#'     `"breaks_"`. \pkg{ggdist} provides weighted implementations of the
-#'     `"Sturges"`, `"Scott"`, and `"FD"` break-finding algorithms from
-#'     [graphics::hist()], as well as [breaks_fixed()] for manually setting
-#'     the bin width. See [breaks].
-#'
-#' For example, `breaks = "Sturges"` will use the [breaks_Sturges()] algorithm,
-#' `breaks = 9` will create 9 bins, and `breaks = breaks_fixed(width = 1)` will
-#' set the bin width to `1`.
-#' @param align Determines how to align the breakpoints defining bins. Default
-#' (`"none"`) performs no alignment. One of:
-#'   - A scalar (length-1) numeric giving an offset that is subtracted from the breaks.
-#'     The offset must be between `0` and the bin width.
-#'   - A function taking a sorted vector of `breaks` (bin edges) and returning
-#'     an offset to subtract from the breaks.
-#'   - A string giving the suffix of a function that starts with
-#'     `"align_"` used to determine the alignment, such as [align_none()],
-#'     [align_boundary()], or [align_center()].
-#'
-#' For example, `align = "none"` will provide no alignment, `align = align_center(at = 0)`
-#' will center a bin on `0`, and `align = align_boundary(at = 0)` will align a bin
-#' edge on `0`.
+#' @eval rd_param_density_breaks()
+#' @eval rd_param_density_align()
 #' @param outline_bars Should outlines in between the bars (i.e. density values of
 #' 0) be included?
 #' @param na.rm Should missing (`NA`) values in `x` be removed?
@@ -360,7 +332,7 @@ density_histogram = auto_partial(name = "density_histogram", function(
   # work as expected if 1 is a bin edge.
   eps = min(diff(h$breaks)/4, 2*.Machine$double.eps)
 
-  if (outline_bars) {
+  if (isTRUE(outline_bars)) {
     # have to return to 0 in between each bar so that bar outlines are drawn
     input = as.vector(rbind(input_1, input_1, input_1 + eps, input_, input_, input_2 - eps, input_2, input_2))
     pdf = as.vector(rbind(0, h$density, h$density, h$density, h$density, h$density, h$density, 0))
@@ -481,7 +453,7 @@ bandwidth_dpi = auto_partial(name = "bandwidth_dpi", function(x, ...) {
 #' @importFrom stats bw.nrd0 kmeans
 .density_adaptive = function(
   x, weights = NULL,
-  n = 512,
+  n = 501,
   bw = bw.nrd0(x),
   adapt = 1,
   kernel = "gaussian",

R/deprecated.R

@@ -25,7 +25,7 @@
 #'
 #' @section Deprecated arguments:
 #'
-#' Parameters for [stat_slabinterval()] and family deprecated as of ggdist 3.1 are:
+#' Deprecated parameters for [stat_slabinterval()] and family:
 #'
 #' - The `.prob` argument, which is a long-deprecated alias for `.width`, was
 #' removed in ggdist 3.1.
@@ -45,6 +45,11 @@
 #' - The `slab_args` argument: extra stat parameters are now passed through to
 #' the `...` arguments to `AbstractStatSlabInterval$compute_slab()`; use
 #' these instead.
+#' - The `slab_type` argument: instead of setting the slab type, either adjust
+#' the `density` argument (e.g. use `density = "histogram"` to replace
+#' `slab_type = "histogram"`) or use the `pdf` or `cdf` computed variables
+#' mapped onto an appropriate aesthetic (e.g. use `aes(thickness = after_stat(cdf))`
+#' to create a CDF).
 #' - The `interval_function` and `fun.data` arguments: these were parameters for determining the
 #' function to compute intervals in [stat_slabinterval()] and its
 #' derived stats. This function is really an internal function only needed by
@@ -54,7 +59,7 @@
 #' a `point_interval` replace the value of the `point_interval` argument with
 #' a simple wrapper; e.g. `stat_halfeye(point_interval = \(...) point_interval(..., extra_arg = XXX))`
 #'
-#' Parameters for [geom_slabinterval()] and family deprecated as of ggdist 3.1 are:
+#' Deprecated parameters for [geom_slabinterval()] and family:
 #'
 #' - The `size_domain` and `size_range` arguments, which are long-deprecated aliases
 #' for `interval_size_domain` and `interval_size_range`, were removed in ggdist 3.1.

R/rd_density.R

@@ -0,0 +1,95 @@
+# Documentation methods for the density functions
+#
+# Author: mjskay
+###############################################################################
+
+
+
+# shared parameter docs ---------------------------------------------------
+
+#' construct the first part of the `@param` docstring for a parameter of one of the
+#' functions in the density family (or, if `passed_to` is provided, construct
+#' the first part of the `@param` docstring for that parameter as documented in
+#' a `stat` that will pass that parameter to the `density` parameter, expecting
+#' a density-family function like the one named `passed_to`.
+#' @param description short description of the param
+#' @param default description of the default value
+#' @param passed_to `NULL`, or the name of an example function in the `density`
+#' family that would have this parameter.
+#' @noRd
+rd_param_density = function(description, default, passed_to = NULL) {
+  paste0(
+    if (!is.null(passed_to)) glue_doc("Passed to `density` (e.g. [<<passed_to>>()]): "),
+    description,
+    " Default ",
+    if (!is.null(passed_to)) "`waiver()` defers to the default of the density estimator, which is usually ",
+    default
+  )
+}
+
+rd_param_density_adjust = function(passed_to = NULL) {
+  short_description = rd_param_density(
+    description = 'Scalar numeric that the bandwidth of the density estimator is multiplied by.',
+    default = '`1`.',
+    passed_to = passed_to
+  )
+  glue_doc('@param adjust <<short_description>>')
+}
+
+rd_param_density_trim = function(passed_to = NULL) {
+  short_description = rd_param_density(
+    description = 'Should the density estimate be trimmed to the range of the data?',
+    default = '`TRUE`.',
+    passed_to = passed_to
+  )
+  glue_doc('@param trim <<short_description>>')
+}
+
+rd_param_density_align = function(passed_to = NULL) {
+  short_description = rd_param_density(
+    description = 'Determines how to align the breakpoints defining bins.',
+    default = '`"none"` (performs no alignment).',
+    passed_to = passed_to
+  )
+  glue_doc('
+    @param align <<short_description>> One of:
+    \\itemize{
+      \\item A scalar (length-1) numeric giving an offset that is subtracted
+        from the breaks. The offset must be between `0` and the bin width.
+      \\item A function taking a sorted vector of `breaks` (bin edges) and
+        returning an offset to subtract from the breaks.
+      \\item A string giving the suffix of a function that starts with
+        `"align_"` used to determine the alignment, such as [align_none()],
+        [align_boundary()], or [align_center()].
+    }
+    For example, `align = "none"` will provide no alignment,
+    `align = align_center(at = 0)` will center a bin on `0`, and
+    `align = align_boundary(at = 0)` will align a bin edge on `0`.
+    ')
+}
+
+rd_param_density_breaks = function(passed_to = NULL) {
+  short_description = rd_param_density(
+    description = 'Determines the breakpoints defining bins.',
+    default = '`"Scott"`.',
+    passed_to = passed_to
+  )
+  glue_doc('
+    @param breaks <<short_description>> Similar to (but not exactly the
+    same as) the `breaks` argument to [graphics::hist()]. One of:
+    \\itemize{
+      \\item A scalar (length-1) numeric giving the number of bins
+      \\item A vector numeric giving the breakpoints between histogram bins
+      \\item A function taking `x` and `weights` and returning either the
+        number of bins or a vector of breakpoints
+      \\item A string giving the suffix of a function that starts with
+        `"breaks_"`. \\pkg{ggdist} provides weighted implementations of the
+        `"Sturges"`, `"Scott"`, and `"FD"` break-finding algorithms from
+        [graphics::hist()], as well as [breaks_fixed()] for manually setting
+        the bin width. See [breaks].
+    }
+    For example, `breaks = "Sturges"` will use the [breaks_Sturges()] algorithm,
+    `breaks = 9` will create 9 bins, and `breaks = breaks_fixed(width = 1)` will
+    set the bin width to `1`.
+    ')
+}

R/smooth.R

@@ -20,6 +20,8 @@
 #'    [density_bounded()].
 #'  - A string giving the suffix of a function name that starts with `"density_"`;
 #'    e.g. `"bounded"` for `[density_bounded()]`.
+#' @param trim Passed to `density`: Should the density estimate be trimmed to the
+#' range of the data? Default `FALSE`.
 #' @param ... Arguments passed to the density estimator specified by `density`.
 #' @inheritParams density_bounded
 #'

R/stat_dotsinterval.R

@@ -83,7 +83,7 @@ StatDotsinterval = ggproto("StatDotsinterval", StatSlabinterval,
 
   hidden_params = union(c(
     "limits", "n",
-    "p_limits", "slab_type", "outline_bars",
+    "p_limits", "outline_bars",
     "density", "adjust", "trim", "expand", "breaks", "align"
   ), StatSlabinterval$hidden_params),
 
@@ -115,7 +115,6 @@ StatDots = ggproto("StatDots", StatDotsinterval,
   ), StatDotsinterval$layer_args),
 
   hidden_params = union(c(
-    "show_slab", "show_point", "show_interval",
     "point_interval", ".width"
   ), StatDotsinterval$hidden_params)
 )

R/stat_pointinterval.R

@@ -18,8 +18,7 @@ StatPointinterval = ggproto("StatPointinterval", StatSlabinterval,
   ), StatSlabinterval$default_params),
 
   hidden_params = union(c(
-    "slab_type", "density", "adjust", "trim", "expand", "breaks", "align", "outline_bars", "limits", "n", "p_limits",
-    "show_slab", "show_point", "show_interval"
+    "density", "adjust", "trim", "expand", "breaks", "align", "outline_bars", "limits", "n", "p_limits"
   ), StatSlabinterval$hidden_params)
 )