diff --git a/R/breaks-log.R b/R/breaks-log.R index cbfe7cfc..168dd2b0 100644 --- a/R/breaks-log.R +++ b/R/breaks-log.R @@ -25,6 +25,9 @@ #' breaks, `>= n-2`, are returned or all candidates have been used. #' @param n desired number of breaks #' @param base base of logarithm to use +#' +#' @inherit breaks_width return +#' #' @export #' @examples #' demo_log10(c(1, 1e5)) @@ -93,6 +96,7 @@ log_breaks <- breaks_log #' negative numbers. #' #' @return A function to generate minor ticks. +#' #' @export #' #' @examples diff --git a/R/breaks.R b/R/breaks.R index adf194d2..09cf1381 100644 --- a/R/breaks.R +++ b/R/breaks.R @@ -16,6 +16,13 @@ #' offset by three months and five days, which is useful for the UK tax year. #' Note that due to way that dates are rounded, there's no guarantee that #' `offset = c(x, y)` will give the same result as `offset = c(y, x)`. +#' +#' @return +#' All `breaks_()` functions return a function for generating breaks. These +#' functions takes, as their first argument a vector of values that represent +#' the data range to provide breaks for. Some will optionally take a second +#' argument that allows you to specify the number of breaks to recieve. +#' #' @export #' @examples #' demo_continuous(c(0, 100)) @@ -71,6 +78,9 @@ breaks_width <- function(width, offset = 0) { #' @param n Desired number of breaks. You may get slightly more or fewer #' breaks that requested. #' @param ... other arguments passed on to [labeling::extended()] +#' +#' @inherit breaks_width return +#' #' @references Talbot, J., Lin, S., Hanrahan, P. (2010) An Extension of #' Wilkinson's Algorithm for Positioning Tick Labels on Axes, InfoVis #' 2010 . @@ -105,6 +115,9 @@ extended_breaks <- breaks_extended #' #' @inheritParams breaks_extended #' @param ... other arguments passed on to [pretty()] +#' +#' @inherit breaks_width return +#' #' @export #' @examples #' one_month <- as.POSIXct(c("2020-05-01", "2020-06-01")) @@ -151,6 +164,9 @@ pretty_breaks <- breaks_pretty #' determines the base used for calculating breaks #' #' @param unit The unit used to interpret numeric data input +#' +#' @inherit breaks_width return +#' #' @inheritParams breaks_extended #' @export #' @examples @@ -193,6 +209,9 @@ breaks_timespan <- function(unit = c("secs", "mins", "hours", "days", "weeks"), #' uses [`breaks_extended()`]. #' #' @inheritParams breaks_extended +#' +#' @inherit breaks_width return +#' #' @export #' @examples #' # Small range diff --git a/R/label-bytes.R b/R/label-bytes.R index 1eb90ef4..f142bac7 100644 --- a/R/label-bytes.R +++ b/R/label-bytes.R @@ -5,6 +5,7 @@ #' [Units of Information](https://en.wikipedia.org/wiki/Units_of_information) #' on Wikipedia for more details. #' +#' @inherit label_number return #' @param units Unit to use. Should either one of: #' * "kB", "MB", "GB", "TB", "PB", "EB", "ZB", and "YB" for #' SI units (base 1000). @@ -14,8 +15,7 @@ #' unit for each value. #' @inheritParams number_format #' @inheritDotParams number -#' @return A labeller function that takes a numeric vector of breaks and -#' returns a character vector of labels. +#' #' @export #' @family labels for continuous scales #' @family labels for log scales diff --git a/R/label-compose.R b/R/label-compose.R index d324c069..953aa2b9 100644 --- a/R/label-compose.R +++ b/R/label-compose.R @@ -3,14 +3,12 @@ #' This labeller provides a general mechanism for composing two or more #' labellers together. #' +#' @inherit label_number return #' @param ... One or more labelling functions. These will be applied to breaks #' consecutively. #' [Lambda syntax][rlang::as_function] is allowed. #' @param call A call to display in error messages. #' -#' @return A labelling function that applies the provided -#' functions to breaks to return labels. -#' #' @export #' #' @examples diff --git a/R/label-currency.R b/R/label-currency.R index 98d18e3d..7496a82f 100644 --- a/R/label-currency.R +++ b/R/label-currency.R @@ -10,6 +10,7 @@ #' the largest value is less than `largest_with_fractional` which by default #' is 100,000. #' @param prefix,suffix Symbols to display before and after value. +#' #' @inheritDotParams number #' @export #' @family labels for continuous scales diff --git a/R/label-date.R b/R/label-date.R index 0cf47a41..31188521 100644 --- a/R/label-date.R +++ b/R/label-date.R @@ -24,6 +24,7 @@ #' [stringi::stri_locale_list()]. #' @param leading A string to replace leading zeroes with. Can be `""` to #' disable leading characters or `"\u2007"` for figure-spaces. +#' #' @export #' @examples #' date_range <- function(start, days) { diff --git a/R/label-dictionary.R b/R/label-dictionary.R index 15dd12e1..bd5a787e 100644 --- a/R/label-dictionary.R +++ b/R/label-dictionary.R @@ -4,14 +4,13 @@ #' Use `label_dictionary()` for looking up succinct breaks in a named character #' vector giving complete labels. #' +#' @inherit label_number return #' @param dictionary A named character vector of labels. The names are expected #' to match the breaks, and the values become the labels. #' @param nomatch A string to label breaks that do not match any name in #' `dictionary`. When `NULL` (default), the breaks are not translated but are #' kept as-is. #' -#' @return A labeller function that takes a character vector of breaks and -#' returns a character vector of labels. #' @export #' @family labels for discrete scales #' @examples diff --git a/R/label-glue.R b/R/label-glue.R index 156d4be9..f1764eba 100644 --- a/R/label-glue.R +++ b/R/label-glue.R @@ -3,14 +3,12 @@ #' Use `label_glue()` to perform string interpolation using the \pkg{glue} #' package. Enclosed expressions will be evaluated as R code. #' +#' @inherit label_number return #' @param pattern A glue string used for formatting. The `x` variable holds the #' breaks, so that `"{x}"` (default) returns the breaks as-is. #' @param ... Arguments passed on to [`glue::glue()`]. #' @param parse Whether to return labels as expressions. #' @inheritParams glue::glue -#' -#' @return A labeller function that takes a vector of breaks and returns a -#' character vector of labels. #' @export #' @family labels for continuous scales #' @family labels for discrete scales diff --git a/R/label-log.R b/R/label-log.R index e31e2bb8..1607f440 100644 --- a/R/label-log.R +++ b/R/label-log.R @@ -4,7 +4,7 @@ #' superscript formatting. `label_log()` returns expressions suitable for #' labelling in scales, whereas `format_log()` returns deparsed text. #' -#' +#' @inherit label_number return #' @param x A numeric vector to format #' @param base Base of logarithm to use #' @param digits Number of significant digits to show for the exponent. Argument @@ -13,7 +13,7 @@ #' default, `NULL`, displays signs if there are zeroes or negative numbers #' present. #' @param ... Passed on to `format()`. -#' @inherit label_number return +#' #' @seealso [breaks_log()] for the related breaks algorithm. #' @export #' @family labels for log scales diff --git a/R/label-number-auto.R b/R/label-number-auto.R index d8b47ea9..a3f19dd8 100644 --- a/R/label-number-auto.R +++ b/R/label-number-auto.R @@ -4,6 +4,8 @@ #' heuristics designed to automatically generate useful labels across a wide #' range of inputs #' +#' @inherit label_number return +#' #' @export #' @family labels for continuous scales #' @examples diff --git a/man/breaks_exp.Rd b/man/breaks_exp.Rd index 536b4412..f90a9fd4 100644 --- a/man/breaks_exp.Rd +++ b/man/breaks_exp.Rd @@ -12,6 +12,12 @@ breaks that requested.} \item{...}{other arguments passed on to \code{\link[labeling:extended]{labeling::extended()}}} } +\value{ +All \code{breaks_()} functions return a function for generating breaks. These +functions takes, as their first argument a vector of values that represent +the data range to provide breaks for. Some will optionally take a second +argument that allows you to specify the number of breaks to recieve. +} \description{ This breaks function typically labels zero and the last \code{n - 1} integers of a range if that range is large enough (currently: 3). For smaller ranges, it diff --git a/man/breaks_extended.Rd b/man/breaks_extended.Rd index 6e268749..15bcb68b 100644 --- a/man/breaks_extended.Rd +++ b/man/breaks_extended.Rd @@ -13,6 +13,12 @@ breaks that requested.} \item{...}{other arguments passed on to \code{\link[labeling:extended]{labeling::extended()}}} } +\value{ +All \code{breaks_()} functions return a function for generating breaks. These +functions takes, as their first argument a vector of values that represent +the data range to provide breaks for. Some will optionally take a second +argument that allows you to specify the number of breaks to recieve. +} \description{ Uses Wilkinson's extended breaks algorithm as implemented in the \pkg{labeling} package. diff --git a/man/breaks_log.Rd b/man/breaks_log.Rd index 940f5a25..ea28d2f9 100644 --- a/man/breaks_log.Rd +++ b/man/breaks_log.Rd @@ -12,6 +12,12 @@ breaks_log(n = 5, base = 10) \item{base}{base of logarithm to use} } +\value{ +All \code{breaks_()} functions return a function for generating breaks. These +functions takes, as their first argument a vector of values that represent +the data range to provide breaks for. Some will optionally take a second +argument that allows you to specify the number of breaks to recieve. +} \description{ This algorithm starts by looking for integer powers of \code{base}. If that doesn't provide enough breaks, it then looks for additional intermediate diff --git a/man/breaks_pretty.Rd b/man/breaks_pretty.Rd index 0f4a5c6e..c1b46802 100644 --- a/man/breaks_pretty.Rd +++ b/man/breaks_pretty.Rd @@ -12,6 +12,12 @@ breaks that requested.} \item{...}{other arguments passed on to \code{\link[=pretty]{pretty()}}} } +\value{ +All \code{breaks_()} functions return a function for generating breaks. These +functions takes, as their first argument a vector of values that represent +the data range to provide breaks for. Some will optionally take a second +argument that allows you to specify the number of breaks to recieve. +} \description{ Uses default R break algorithm as implemented in \code{\link[=pretty]{pretty()}}. This is primarily useful for date/times, as \code{\link[=extended_breaks]{extended_breaks()}} should do a slightly diff --git a/man/breaks_timespan.Rd b/man/breaks_timespan.Rd index dc750729..8ca4b61c 100644 --- a/man/breaks_timespan.Rd +++ b/man/breaks_timespan.Rd @@ -12,6 +12,12 @@ breaks_timespan(unit = c("secs", "mins", "hours", "days", "weeks"), n = 5) \item{n}{Desired number of breaks. You may get slightly more or fewer breaks that requested.} } +\value{ +All \code{breaks_()} functions return a function for generating breaks. These +functions takes, as their first argument a vector of values that represent +the data range to provide breaks for. Some will optionally take a second +argument that allows you to specify the number of breaks to recieve. +} \description{ As timespan units span a variety of bases (1000 below seconds, 60 for second and minutes, 24 for hours, and 7 for days), the range of the input data diff --git a/man/breaks_width.Rd b/man/breaks_width.Rd index 362df4b0..880d04f6 100644 --- a/man/breaks_width.Rd +++ b/man/breaks_width.Rd @@ -23,6 +23,12 @@ offset by three months and five days, which is useful for the UK tax year. Note that due to way that dates are rounded, there's no guarantee that \code{offset = c(x, y)} will give the same result as \code{offset = c(y, x)}.} } +\value{ +All \code{breaks_()} functions return a function for generating breaks. These +functions takes, as their first argument a vector of values that represent +the data range to provide breaks for. Some will optionally take a second +argument that allows you to specify the number of breaks to recieve. +} \description{ Useful for numeric, date, and date-time scales. } diff --git a/man/compose_label.Rd b/man/compose_label.Rd index a9950860..956d755f 100644 --- a/man/compose_label.Rd +++ b/man/compose_label.Rd @@ -14,8 +14,14 @@ consecutively. \item{call}{A call to display in error messages.} } \value{ -A labelling function that applies the provided -functions to breaks to return labels. +All \code{label_()} functions return a "labelling" function, i.e. a function that +takes a vector \code{x} and returns a character vector of \code{length(x)} giving a +label for each input value. + +Labelling functions are designed to be used with the \code{labels} argument of +ggplot2 scales. The examples demonstrate their use with x scales, but +they work similarly for all scales, including those that generate legends +rather than axes. } \description{ This labeller provides a general mechanism for composing two or more diff --git a/man/label_bytes.Rd b/man/label_bytes.Rd index 25514532..4e0b77da 100644 --- a/man/label_bytes.Rd +++ b/man/label_bytes.Rd @@ -84,8 +84,14 @@ width (see \code{\link[base:format]{base::format()}}).} }} } \value{ -A labeller function that takes a numeric vector of breaks and -returns a character vector of labels. +All \code{label_()} functions return a "labelling" function, i.e. a function that +takes a vector \code{x} and returns a character vector of \code{length(x)} giving a +label for each input value. + +Labelling functions are designed to be used with the \code{labels} argument of +ggplot2 scales. The examples demonstrate their use with x scales, but +they work similarly for all scales, including those that generate legends +rather than axes. } \description{ Scale bytes into human friendly units. Can use either SI units (e.g. diff --git a/man/label_dictionary.Rd b/man/label_dictionary.Rd index 7731c13a..49c59053 100644 --- a/man/label_dictionary.Rd +++ b/man/label_dictionary.Rd @@ -15,8 +15,14 @@ to match the breaks, and the values become the labels.} kept as-is.} } \value{ -A labeller function that takes a character vector of breaks and -returns a character vector of labels. +All \code{label_()} functions return a "labelling" function, i.e. a function that +takes a vector \code{x} and returns a character vector of \code{length(x)} giving a +label for each input value. + +Labelling functions are designed to be used with the \code{labels} argument of +ggplot2 scales. The examples demonstrate their use with x scales, but +they work similarly for all scales, including those that generate legends +rather than axes. } \description{ Use \code{label_dictionary()} for looking up succinct breaks in a named character diff --git a/man/label_glue.Rd b/man/label_glue.Rd index f4001974..3ead7735 100644 --- a/man/label_glue.Rd +++ b/man/label_glue.Rd @@ -19,8 +19,14 @@ evaluated from left to right. If \code{.x} is an environment, the expressions ar evaluated in that environment and \code{.envir} is ignored. If \code{NULL} is passed, it is equivalent to \code{\link[=emptyenv]{emptyenv()}}.} } \value{ -A labeller function that takes a vector of breaks and returns a -character vector of labels. +All \code{label_()} functions return a "labelling" function, i.e. a function that +takes a vector \code{x} and returns a character vector of \code{length(x)} giving a +label for each input value. + +Labelling functions are designed to be used with the \code{labels} argument of +ggplot2 scales. The examples demonstrate their use with x scales, but +they work similarly for all scales, including those that generate legends +rather than axes. } \description{ Use \code{label_glue()} to perform string interpolation using the \pkg{glue} diff --git a/man/label_number_auto.Rd b/man/label_number_auto.Rd index 401c72dc..0aeac3a1 100644 --- a/man/label_number_auto.Rd +++ b/man/label_number_auto.Rd @@ -6,6 +6,16 @@ \usage{ label_number_auto() } +\value{ +All \code{label_()} functions return a "labelling" function, i.e. a function that +takes a vector \code{x} and returns a character vector of \code{length(x)} giving a +label for each input value. + +Labelling functions are designed to be used with the \code{labels} argument of +ggplot2 scales. The examples demonstrate their use with x scales, but +they work similarly for all scales, including those that generate legends +rather than axes. +} \description{ Switches between \code{\link[=number_format]{number_format()}} and \code{\link[=scientific_format]{scientific_format()}} based on a set of heuristics designed to automatically generate useful labels across a wide