diff --git a/R/auto_partial.R b/R/auto_partial.R index 54264a89..a800c45d 100755 --- a/R/auto_partial.R +++ b/R/auto_partial.R @@ -51,7 +51,7 @@ #' These function families (except [point_interval()]) also support passing #' [waiver]s to their optional arguments: if [waiver()] is passed to any #' of these arguments, their default value (or the most -#' recently-partially-applied non-`waiver` value) is used instead. +#' recently-partially-applied non-[waiver] value) is used instead. #' #' Use the [auto_partial()] function to create new functions that support #' automatic partial application. @@ -227,5 +227,46 @@ print.ggdist_partial_function = function(x, ...) { invisible(x) } + +#' A waived argument +#' +#' A flag indicating that the default value of an argument should be used. +#' +#' @details +#' A [waiver()] is a flag passed to a function argument that indicates the +#' function should use the default value of that argument. It is used in two +#' cases: +#' +#' - \pkg{ggplot2} functions use it to distinguish between "nothing" (`NULL`) +#' and a default value calculated elsewhere ([waiver()]). +#' +#' - \pkg{ggdist} turns \pkg{ggplot2}'s convention into a standardized method of +#' argument-passing: any named argument with a default value in an +#' [automatically partially-applied function][auto_partial] can be passed +#' [waiver()] when calling the function. This will cause the default value +#' (or the most recently partially-applied value) of that argument to be used +#' instead. +#' +#' **Note:** due to historical limitations, [waiver()] cannot currently be +#' used on arguments to the [point_interval()] family of functions. +#' +#' @seealso [auto_partial()], [ggplot2::waiver()] +#' @examples +#' f = auto_partial(function(x, y = "b") { +#' c(x = x, y = y) +#' }) +#' +#' f("a") +#' +#' # uses the default value of `y` ("b") +#' f("a", y = waiver()) +#' +#' # partially apply `f` +#' g = f(y = "c") +#' g +#' +#' # uses the last partially-applied value of `y` ("c") +#' g("a", y = waiver()) +#' @importFrom ggplot2 waiver #' @export -ggplot2::waiver +waiver = ggplot2::waiver diff --git a/R/bounder.R b/R/bounder.R index 6785d3f3..359f6390 100755 --- a/R/bounder.R +++ b/R/bounder.R @@ -9,7 +9,7 @@ #' #' Estimate the bounds of the distribution a sample came from using the CDF of #' the order statistics of the sample. Use with the `bounder` argument to [density_bounded()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param x numeric vector containing a sample to estimate the bounds of. #' @param p scalar in \eqn{[0,1]}: percentile of the order statistic distribution to use @@ -90,7 +90,7 @@ bounder_cdf = auto_partial(name = "bounder_cdf", function(x, p = 0.01) { #' #' Estimate the bounds of the distribution a sample came from using Cooke's method. #' Use with the `bounder` argument to [density_bounded()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @inheritParams bounder_cdf #' @@ -158,7 +158,7 @@ bounder_cooke = auto_partial(name = "bounder_cooke", function(x) { #' #' Estimate the bounds of the distribution a sample came from using the range of the sample. #' Use with the `bounder` argument to [density_bounded()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @inheritParams bounder_cdf #' diff --git a/R/density.R b/R/density.R index 7e9f33cd..0283954d 100755 --- a/R/density.R +++ b/R/density.R @@ -10,7 +10,7 @@ #' Unbounded density estimator #' #' Unbounded density estimator using [stats::density()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param x numeric vector containing a sample to compute a density estimate for. #' @param weights optional numeric vector of weights to apply to `x`. @@ -122,7 +122,7 @@ density_unbounded = auto_partial(name = "density_unbounded", function( #' Bounded density estimator using the reflection method #' #' Bounded density estimator using the reflection method. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @inheritParams density_unbounded #' @param bounds length-2 vector of min and max bounds. If a bound is `NA`, then @@ -261,7 +261,7 @@ density_bounded = auto_partial(name = "density_bounded", function( #' Histogram density estimator #' #' Histogram density estimator. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param x numeric vector containing a sample to compute a density estimate for. #' @param weights optional numeric vector of weights to apply to `x`. @@ -413,7 +413,7 @@ plot.ggdist_density = function(x, ..., ylim = c(0, NA)) { #' #' Bandwidth estimators for densities, used in the `bandwidth` argument #' to density functions (e.g. [density_bounded()], [density_unbounded()]). -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @inheritDotParams stats::bw.SJ #' @param x A numeric vector giving a sample. diff --git a/R/geom_blur_dots.R b/R/geom_blur_dots.R index 8b3bbc74..820c2526 100755 --- a/R/geom_blur_dots.R +++ b/R/geom_blur_dots.R @@ -235,7 +235,7 @@ geom_blur_dots = make_geom(GeomBlurDots) #' @description #' Methods for constructing blurs, as used in the `blur` argument to #' [geom_blur_dots()] or [stat_mcse_dots()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' @param x numeric vector of positive distances from the center of the dot #' (assumed to be 0) to evaluate blur function at. #' @param r radius of the dot that is being blurred. diff --git a/R/point_interval.R b/R/point_interval.R index cba3c596..e6c0001a 100644 --- a/R/point_interval.R +++ b/R/point_interval.R @@ -13,7 +13,9 @@ globalVariables(c("y", "ymin", "ymax")) #' Translates draws from distributions in a (possibly grouped) data frame into point and #' interval summaries (or set of point and interval summaries, if there are #' multiple groups in a grouped data frame). +#' @template description-auto-partial #' +#' @details #' If `.data` is a data frame, then `...` is a list of bare names of #' columns (or expressions derived from columns) of `.data`, on which #' the point and interval summaries are derived. Column expressions are processed diff --git a/R/smooth.R b/R/smooth.R index 6ba442c4..1f92e254 100755 --- a/R/smooth.R +++ b/R/smooth.R @@ -9,7 +9,7 @@ #' Smooths `x` values using a density estimator, returning new `x` of the same #' length. Can be used with a dotplot (e.g. [`geom_dots`]`(smooth = ...)`) to create #' "density dotplots". -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param x a numeric vector #' @param density Density estimator to use for smoothing. One of: @@ -139,7 +139,7 @@ smooth_unbounded = auto_partial(name = "smooth_unbounded", function( #' dataset; `smooth_discrete()` uses a kernel density estimator and `smooth_bar()` #' places values in an evenly-spaced grid. Can be used with a dotplot #' (e.g. [`geom_dots`]`(smooth = ...)`) to create "bar dotplots". -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param x a numeric vector #' @param width approximate width of the bars as a fraction of data [resolution()]. @@ -240,7 +240,7 @@ smooth_bar = auto_partial(name = "smooth_bar", function(x, width = 0.7, ...) { #' Apply no smooth to a dotplot #' #' Default smooth for dotplots: no smooth. Simply returns the input values. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param x a numeric vector #' @param ... ignored diff --git a/R/subguide.R b/R/subguide.R index 2bf14156..1c63d328 100755 --- a/R/subguide.R +++ b/R/subguide.R @@ -3,7 +3,7 @@ #' This is a sub-guide intended for annotating the `thickness` aesthetic #' in \pkg{ggdist}. It can be used with the `subguide` parameter of #' [geom_slabinterval()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @inheritParams scale_thickness #' @param values Values used to construct the scale used for this guide. diff --git a/R/subscale.R b/R/subscale.R index 3a91846f..7b8f43ae 100755 --- a/R/subscale.R +++ b/R/subscale.R @@ -3,7 +3,7 @@ #' This is a sub-scale intended for adjusting the scaling of the `thickness` #' aesthetic at a geometry (or sub-geometry) level in \pkg{ggdist}. It can be #' used with the `subscale` parameter of [geom_slabinterval()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @inheritParams scale_thickness #' @param x a [numeric] vector to be rescaled. diff --git a/R/weighted_hist.R b/R/weighted_hist.R index 2e2f7a7a..967f20b7 100755 --- a/R/weighted_hist.R +++ b/R/weighted_hist.R @@ -56,7 +56,7 @@ weighted_hist = function( #' #' Methods for determining breaks (bins) in histograms, as used in the `breaks` #' argument to [density_histogram()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param x A numeric vector giving a sample. #' @param weights A numeric vector of `length(x)` giving sample weights. @@ -255,7 +255,7 @@ breaks_quantiles = auto_partial(name = "breaks_quantiles", function( #' #' Methods for aligning breaks (bins) in histograms, as used in the `align` #' argument to [density_histogram()]. -#' @template description-auto-partial +#' @template description-auto-partial-waivable #' #' @param breaks A sorted vector of breaks (bin edges). #' @param at A scalar numeric giving an alignment point. diff --git a/man-roxygen/description-auto-partial-waivable.R b/man-roxygen/description-auto-partial-waivable.R new file mode 100755 index 00000000..1974d656 --- /dev/null +++ b/man-roxygen/description-auto-partial-waivable.R @@ -0,0 +1,3 @@ +#' @description +#' Supports [automatic partial function application][auto_partial] with +#' [waived arguments][waiver]. diff --git a/man-roxygen/description-auto-partial.R b/man-roxygen/description-auto-partial.R index 7c839983..10862896 100755 --- a/man-roxygen/description-auto-partial.R +++ b/man-roxygen/description-auto-partial.R @@ -1,2 +1,2 @@ #' @description -#' Supports [automatic partial function application][automatic-partial-functions]. +#' Supports [automatic partial function application][auto_partial]. diff --git a/man/align.Rd b/man/align.Rd index 8bf33c13..bd3d0cf4 100755 --- a/man/align.Rd +++ b/man/align.Rd @@ -29,7 +29,8 @@ A scalar numeric returning an offset to be subtracted from \code{breaks}. Methods for aligning breaks (bins) in histograms, as used in the \code{align} argument to \code{\link[=density_histogram]{density_histogram()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ These functions take a sorted vector of equally-spaced \code{breaks} giving diff --git a/man/auto_partial.Rd b/man/auto_partial.Rd index b09fe3ca..eeeddfd8 100755 --- a/man/auto_partial.Rd +++ b/man/auto_partial.Rd @@ -61,7 +61,7 @@ Many other common arguments for \pkg{ggdist} functions work similarly; e.g. These function families (except \code{\link[=point_interval]{point_interval()}}) also support passing \link{waiver}s to their optional arguments: if \code{\link[=waiver]{waiver()}} is passed to any of these arguments, their default value (or the most -recently-partially-applied non-\code{waiver} value) is used instead. +recently-partially-applied non-\link{waiver} value) is used instead. Use the \code{\link[=auto_partial]{auto_partial()}} function to create new functions that support automatic partial application. diff --git a/man/bandwidth.Rd b/man/bandwidth.Rd index 86835c9b..7724f531 100755 --- a/man/bandwidth.Rd +++ b/man/bandwidth.Rd @@ -48,7 +48,8 @@ A single number giving the bandwidth Bandwidth estimators for densities, used in the \code{bandwidth} argument to density functions (e.g. \code{\link[=density_bounded]{density_bounded()}}, \code{\link[=density_unbounded]{density_unbounded()}}). -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ These are loose wrappers around the corresponding \code{bw.}-prefixed functions diff --git a/man/blur.Rd b/man/blur.Rd index bcba3238..8eaa5f6c 100755 --- a/man/blur.Rd +++ b/man/blur.Rd @@ -29,7 +29,8 @@ the dot at each \code{x} value. Methods for constructing blurs, as used in the \code{blur} argument to \code{\link[=geom_blur_dots]{geom_blur_dots()}} or \code{\link[=stat_mcse_dots]{stat_mcse_dots()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ These functions are passed \code{x}, \code{r}, and \code{sd} when \code{\link[=geom_blur_dots]{geom_blur_dots()}} diff --git a/man/bounder_cdf.Rd b/man/bounder_cdf.Rd index e12d0476..d9728f4c 100755 --- a/man/bounder_cdf.Rd +++ b/man/bounder_cdf.Rd @@ -22,7 +22,8 @@ of the distribution that \code{x} came from. Estimate the bounds of the distribution a sample came from using the CDF of the order statistics of the sample. Use with the \code{bounder} argument to \code{\link[=density_bounded]{density_bounded()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ \code{\link[=bounder_cdf]{bounder_cdf()}} uses the distribution of the order statistics of diff --git a/man/bounder_cooke.Rd b/man/bounder_cooke.Rd index 658b6193..70af4f8e 100755 --- a/man/bounder_cooke.Rd +++ b/man/bounder_cooke.Rd @@ -17,7 +17,8 @@ of the distribution that \code{x} came from. Estimate the bounds of the distribution a sample came from using Cooke's method. Use with the \code{bounder} argument to \code{\link[=density_bounded]{density_bounded()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ Estimate the bounds of a distribution using the method from Cooke (1979); diff --git a/man/bounder_range.Rd b/man/bounder_range.Rd index 432016c9..28fc82b4 100755 --- a/man/bounder_range.Rd +++ b/man/bounder_range.Rd @@ -17,7 +17,8 @@ of the distribution that \code{x} came from. Estimate the bounds of the distribution a sample came from using the range of the sample. Use with the \code{bounder} argument to \code{\link[=density_bounded]{density_bounded()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ Estimate the bounds of a distribution using \code{range(x)}. diff --git a/man/breaks.Rd b/man/breaks.Rd index b2d46377..2c28e318 100755 --- a/man/breaks.Rd +++ b/man/breaks.Rd @@ -48,7 +48,8 @@ giving the edges between bins. Methods for determining breaks (bins) in histograms, as used in the \code{breaks} argument to \code{\link[=density_histogram]{density_histogram()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ These functions take a sample and its weights and return a value suitable for diff --git a/man/density_bounded.Rd b/man/density_bounded.Rd index e8ca686b..325d1971 100755 --- a/man/density_bounded.Rd +++ b/man/density_bounded.Rd @@ -101,7 +101,8 @@ and the \code{\link[=smooth_density]{smooth_}} family of functions. \description{ Bounded density estimator using the reflection method. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \examples{ library(distributional) diff --git a/man/density_histogram.Rd b/man/density_histogram.Rd index 97c00352..13736c2c 100755 --- a/man/density_histogram.Rd +++ b/man/density_histogram.Rd @@ -90,7 +90,8 @@ and the \code{\link[=smooth_density]{smooth_}} family of functions. \description{ Histogram density estimator. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \examples{ library(distributional) diff --git a/man/density_unbounded.Rd b/man/density_unbounded.Rd index 71a6840f..a0c88906 100755 --- a/man/density_unbounded.Rd +++ b/man/density_unbounded.Rd @@ -83,7 +83,8 @@ and the \code{\link[=smooth_density]{smooth_}} family of functions. \description{ Unbounded density estimator using \code{\link[stats:density]{stats::density()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \examples{ library(distributional) diff --git a/man/point_interval.Rd b/man/point_interval.Rd index d790c3f6..9a80fe8e 100755 --- a/man/point_interval.Rd +++ b/man/point_interval.Rd @@ -215,6 +215,8 @@ width of the interval (\code{.width}), the type of point summary (\code{.point}) Translates draws from distributions in a (possibly grouped) data frame into point and interval summaries (or set of point and interval summaries, if there are multiple groups in a grouped data frame). + +Supports \link[=auto_partial]{automatic partial function application}. } \details{ If \code{.data} is a data frame, then \code{...} is a list of bare names of diff --git a/man/reexports.Rd b/man/reexports.Rd deleted file mode 100755 index b3c8242c..00000000 --- a/man/reexports.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/auto_partial.R -\docType{import} -\name{reexports} -\alias{reexports} -\alias{waiver} -\title{Objects exported from other packages} -\keyword{internal} -\description{ -These objects are imported from other packages. Follow the links -below to see their documentation. - -\describe{ - \item{ggplot2}{\code{\link[ggplot2]{waiver}}} -}} - diff --git a/man/smooth_density.Rd b/man/smooth_density.Rd index e6324cd2..814d2178 100755 --- a/man/smooth_density.Rd +++ b/man/smooth_density.Rd @@ -62,7 +62,8 @@ Smooths \code{x} values using a density estimator, returning new \code{x} of the length. Can be used with a dotplot (e.g. \code{\link{geom_dots}}\code{(smooth = ...)}) to create "density dotplots". -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ Applies a kernel density estimator (KDE) to \code{x}, then uses weighted quantiles diff --git a/man/smooth_discrete.Rd b/man/smooth_discrete.Rd index 02920cd6..0e536098 100755 --- a/man/smooth_discrete.Rd +++ b/man/smooth_discrete.Rd @@ -46,7 +46,8 @@ dataset; \code{smooth_discrete()} uses a kernel density estimator and \code{smoo places values in an evenly-spaced grid. Can be used with a dotplot (e.g. \code{\link{geom_dots}}\code{(smooth = ...)}) to create "bar dotplots". -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ \code{smooth_discrete()} applies a kernel density estimator (default: rectangular) diff --git a/man/smooth_none.Rd b/man/smooth_none.Rd index 06da174e..cb934b07 100755 --- a/man/smooth_none.Rd +++ b/man/smooth_none.Rd @@ -19,7 +19,8 @@ If \code{x} is missing, returns a partial application of itself. See \link{autom \description{ Default smooth for dotplots: no smooth. Simply returns the input values. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ This is the default value for the \code{smooth} argument of \code{geom_dotsinterval()}. diff --git a/man/subguide_axis.Rd b/man/subguide_axis.Rd index 27f3c421..559324d3 100755 --- a/man/subguide_axis.Rd +++ b/man/subguide_axis.Rd @@ -99,7 +99,8 @@ This is a sub-guide intended for annotating the \code{thickness} aesthetic in \pkg{ggdist}. It can be used with the \code{subguide} parameter of \code{\link[=geom_slabinterval]{geom_slabinterval()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \details{ \code{\link[=subguide_inside]{subguide_inside()}} is a shortcut for drawing labels inside of the chart diff --git a/man/subscale_thickness.Rd b/man/subscale_thickness.Rd index 790c82e9..0deb76bc 100755 --- a/man/subscale_thickness.Rd +++ b/man/subscale_thickness.Rd @@ -43,7 +43,8 @@ This is a sub-scale intended for adjusting the scaling of the \code{thickness} aesthetic at a geometry (or sub-geometry) level in \pkg{ggdist}. It can be used with the \code{subscale} parameter of \code{\link[=geom_slabinterval]{geom_slabinterval()}}. -Supports \link[=automatic-partial-functions]{automatic partial function application}. +Supports \link[=auto_partial]{automatic partial function application} with +\link[=waiver]{waived arguments}. } \examples{ library(ggplot2) diff --git a/man/waiver.Rd b/man/waiver.Rd new file mode 100755 index 00000000..04684645 --- /dev/null +++ b/man/waiver.Rd @@ -0,0 +1,49 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/auto_partial.R +\name{waiver} +\alias{waiver} +\title{A waived argument} +\usage{ +waiver() +} +\description{ +A flag indicating that the default value of an argument should be used. +} +\details{ +A \code{\link[=waiver]{waiver()}} is a flag passed to a function argument that indicates the +function should use the default value of that argument. It is used in two +cases: +\itemize{ +\item \pkg{ggplot2} functions use it to distinguish between "nothing" (\code{NULL}) +and a default value calculated elsewhere (\code{\link[=waiver]{waiver()}}). +\item \pkg{ggdist} turns \pkg{ggplot2}'s convention into a standardized method of +argument-passing: any named argument with a default value in an +\link[=auto_partial]{automatically partially-applied function} can be passed +\code{\link[=waiver]{waiver()}} when calling the function. This will cause the default value +(or the most recently partially-applied value) of that argument to be used +instead. + +\strong{Note:} due to historical limitations, \code{\link[=waiver]{waiver()}} cannot currently be +used on arguments to the \code{\link[=point_interval]{point_interval()}} family of functions. +} +} +\examples{ +f = auto_partial(function(x, y = "b") { + c(x = x, y = y) +}) + +f("a") + +# uses the default value of `y` ("b") +f("a", y = waiver()) + +# partially apply `f` +g = f(y = "c") +g + +# uses the last partially-applied value of `y` ("c") +g("a", y = waiver()) +} +\seealso{ +\code{\link[=auto_partial]{auto_partial()}}, \code{\link[ggplot2:waiver]{ggplot2::waiver()}} +}