diff --git a/DESCRIPTION b/DESCRIPTION index 38d99259..0ee8fe58 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -39,4 +39,4 @@ Config/testthat/edition: 3 Encoding: UTF-8 LazyLoad: yes Roxygen: list(markdown = TRUE, r6 = FALSE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.2 diff --git a/NAMESPACE b/NAMESPACE index 323e34ba..382b0205 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -117,6 +117,7 @@ export(label_date) export(label_date_short) export(label_dollar) export(label_log) +export(label_lut) export(label_math) export(label_number) export(label_number_auto) diff --git a/NEWS.md b/NEWS.md index 9646d4a5..4f29f801 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,7 @@ # scales (development version) +* New `label_lut()` for named lookup of labels (#458). + # scales 1.3.0 ## Better type support diff --git a/R/label-lut.R b/R/label-lut.R index a42382c7..08216b86 100644 --- a/R/label-lut.R +++ b/R/label-lut.R @@ -1,4 +1,35 @@ +#' Labels from lookup tables +#' +#' Use `label_lut()` for looking up succinct breaks in a named character vector +#' giving complete labels. +#' +#' @param lut 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 `lut`. +#' 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 +#' # Example lookup table +#' lut <- c( +#' "4" = "four wheel drive", +#' "r" = "rear wheel drive", +#' "f" = "front wheel drive" +#' ) +#' +#' # Typical usage +#' demo_discrete(c("4", "r", "f"), labels = label_lut(lut)) +#' # By default, extra values ('w') will remain as-is +#' demo_discrete(c("4", "r", "f", "w"), labels = label_lut(lut)) +#' # Alternatively, you can relabel extra values +#' demo_discrete( +#' c("4", "r", "f", "w"), +#' labels = label_lut(lut, nomatch = "unknown") +#' ) label_lut <- function(lut = character(), nomatch = NULL) { if (!is.character(lut)) { diff --git a/man/label_lut.Rd b/man/label_lut.Rd new file mode 100644 index 00000000..21fa34a5 --- /dev/null +++ b/man/label_lut.Rd @@ -0,0 +1,47 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/label-lut.R +\name{label_lut} +\alias{label_lut} +\title{Labels from lookup tables} +\usage{ +label_lut(lut = character(), nomatch = NULL) +} +\arguments{ +\item{lut}{A named character vector of labels. The names are expected to +match the breaks, and the values become the labels.} + +\item{nomatch}{A string to label breaks that do not match any name in \code{lut}. +When \code{NULL} (default), the breaks are not translated but are kept as-is.} +} +\value{ +A labeller function that takes a character vector of breaks and +returns a character vector of labels. +} +\description{ +Use \code{label_lut()} for looking up succinct breaks in a named character vector +giving complete labels. +} +\examples{ +# Example lookup table +lut <- c( + "4" = "four wheel drive", + "r" = "rear wheel drive", + "f" = "front wheel drive" +) + +# Typical usage +demo_discrete(c("4", "r", "f"), labels = label_lut(lut)) +# By default, extra values ('w') will remain as-is +demo_discrete(c("4", "r", "f", "w"), labels = label_lut(lut)) +# Alternatively, you can relabel extra values +demo_discrete( + c("4", "r", "f", "w"), + labels = label_lut(lut, nomatch = "unknown") +) +} +\seealso{ +Other labels for discrete scales: +\code{\link{label_parse}()}, +\code{\link{label_wrap}()} +} +\concept{labels for discrete scales} diff --git a/man/label_parse.Rd b/man/label_parse.Rd index 7dd7d29d..d9f1c6a1 100644 --- a/man/label_parse.Rd +++ b/man/label_parse.Rd @@ -56,6 +56,7 @@ Other labels for continuous scales: \code{\link{label_scientific}()} Other labels for discrete scales: +\code{\link{label_lut}()}, \code{\link{label_wrap}()} } \concept{labels for continuous scales} diff --git a/man/label_wrap.Rd b/man/label_wrap.Rd index 94862292..7e8c00f2 100644 --- a/man/label_wrap.Rd +++ b/man/label_wrap.Rd @@ -34,6 +34,7 @@ demo_discrete(x, labels = label_wrap(20)) } \seealso{ Other labels for discrete scales: +\code{\link{label_lut}()}, \code{\link{label_parse}()} } \concept{labels for discrete scales}