R/bcat_fmts.R

In Rbearcat: University of Cincinnati Themes and Utilities for Econometrics and Data Science

#' Label currencies
#'
#' A wrapper for \code{scales::label_dollar} to format a numeric vector to dollars and cents.
#'
#' @param x a numeric vector
#' @param accuracy Number to round to. If NULL, the default, values will be rounded to the nearest integer
#' @param scale A scaling factor: \code{x} will be multiplied by \code{scale} before formatting.
#' @param largest_with_cents largest numeric value for which cents will be displayed
#' @param style_negative Character. How to display negative values:
#'   \code{"hyphen"} (default) or \code{"parens"}.
#' @param ... other arguments passed on to \link[scales]{label_dollar}
#'
#' @return A character vector of formatted currency labels with the same length as
#'   \code{x}.
#'
#' @family formatting
#' @export
#'
#' @examples
#'
#' bcat_fmt_dollar(1:4)
#' bcat_fmt_dollar(c(-20, -10, 10, 20))
#' bcat_fmt_dollar(c(-20, -10, 10, 20), style_negative = "parens")
bcat_fmt_dollar <- function(x,
                            accuracy = NULL,
                            scale = 1,
                            largest_with_cents = 1e+05,
                            style_negative = c("hyphen", "parens"),
                            ...){

  style_negative <- match.arg(style_negative)

  scales::label_dollar(
    accuracy = accuracy,
    scale = scale,
    largest_with_cents = largest_with_cents,
    style_negative = style_negative,
    ...
  )(x)

}

#' Label percentages
#'
#' A wrapper for \code{scales::label_percent} to format a numeric vector to percentages.
#'
#' @param x a numeric vector
#' @param accuracy 	A number to round to. Use (e.g.) \code{0.01} to show 2 decimal
#' places of precision. If \code{NULL}, the default, uses a heuristic that should
#' ensure breaks have the minimum number of digits needed to show the difference
#' between adjacent values.
#' @param scale A scaling factor: \code{x} will be multiplied by \code{scale} before formatting.
#' @param ... other arguments passed to \link[scales]{label_percent}
#'
#' @return A character vector of formatted percentage labels with the same length
#'   as \code{x}.
#'
#' @family formatting
#' @export
#'
#' @examples
#'
#' bcat_fmt_percent(c(0.01, 0.05, 0.02))
#' bcat_fmt_percent(c(0.0151321, 0.090115, 0.022141))
#' bcat_fmt_percent(c(0.0151321, 0.090115, 0.022141), accuracy = 0.001)
#' bcat_fmt_percent(c(1.31, 2.44, 3.0), scale = 1)
bcat_fmt_percent <- function(x,
                             accuracy = NULL,
                             scale = 100,
                             ...){


  scales::label_percent(
    accuracy = accuracy,
    scale = scale,
    ...
  )(x)

}


#' Label numbers in decimal format
#'
#' A wrapper for \code{scales::label_comma} to format a numeric vector
#' to force decimal display of numbers with comma separators.
#'
#' @param x a numeric vector
#' @param accuracy 	A number to round to. Use (e.g.) \code{0.01} to show 2 decimal
#' places of precision. If \code{NULL}, the default, uses a heuristic that should
#' ensure breaks have the minimum number of digits needed to show the difference
#' between adjacent values.
#' @param scale A scaling factor: \code{x} will be multiplied by \code{scale} before formatting.
#' @param ... other arguments passed to \link[scales]{label_comma}
#'
#' @return A character vector of formatted decimal labels with the same length as
#'   \code{x}.
#'
#' @family formatting
#' @export
#'
#' @examples
#'
#' bcat_fmt_comma(c(5000, 10000, 8000))
#' bcat_fmt_comma(c(5000, 10000, 8000), scale = 10e-4, accuracy = 1, suffix = "K")
bcat_fmt_comma <- function(x,
                           accuracy = NULL,
                           scale = 1,
                           ...){

  scales::label_comma(
    accuracy = accuracy,
    scale = scale,
    ...
  )(x)

}

#' Label numbers with scientific notation
#'
#' A wrapper for \code{scales::label_scientific} to format a numeric
#' vector to scientific notation.
#'
#' @param x a numeric vector
#' @param digits number of digits to show before exponent.
#' @param scale A scaling factor: \code{x} will be multiplied by \code{scale} before formatting.
#' @param ... other arguments passed to \link[scales]{label_scientific}
#'
#' @return A character vector of scientific-notation labels with the same length
#'   as \code{x}.
#'
#' @family formatting
#' @export
#'
#' @examples
#'
#' bcat_fmt_scientific(c(1:10)*10e5)
#'
bcat_fmt_scientific <- function(x,
                                digits = 3,
                                scale = 1,
                                ...){

  scales::label_scientific(
    digits = digits,
    scale = scale,
    ...
  )(x)

}


#' Label dates/times
#'
#' A wrapper for \code{base::format} to convert character or date vector to specfied
#' date/time format.
#'
#' @param x a character or date/datetime vector
#' @param format a date/time format string using standard POSIX specification
#' @param ... other arguments passed to \link[base]{format}
#'
#' @return A character vector of formatted date or datetime labels with the same
#'   length as \code{x}.
#'
#' @family formatting
#' @export
#'
#' @examples
#'
#' bcat_fmt_date(Sys.Date())
#' bcat_fmt_date(c("2019-12-03", "2020-05-22"))
bcat_fmt_date <- function(x,
                          format = "%B %e, %Y",
                          ...){

  format(
    as.Date(x),
    format,
    ...
  )

}

#' Label p-values
#'
#' A wrapper for \code{scales::label_pvalue} to format a numeric vector to
#' p-values, using "<" and ">" for p-values close to 0 and 1.
#'
#' @param x a numeric vector
#' @param accuracy 	A number to round to. Use (e.g.) \code{0.01} to show 2 decimal
#' places of precision. If \code{NULL}, the default, uses a heuristic that should
#' ensure breaks have the minimum number of digits needed to show the difference
#' between adjacent values.
#' @param add_p logical. Add "p=" before the value?
#' @param ... other arguments passed to \link[scales]{label_pvalue}
#'
#' @return A character vector of formatted p-value labels with the same length as
#'   \code{x}.
#'
#' @family formatting
#' @export
#'
#' @examples
#'
#' bcat_fmt_pvalue(c(0.01, 0.05, 0.02))
#' bcat_fmt_pvalue(c(0.000001, 0.999115, 0.022141))
#' bcat_fmt_pvalue(c(0.000001, 0.999115, 0.022141), add_p = TRUE)
bcat_fmt_pvalue <- function(x,
                            accuracy = 0.001,
                            add_p = FALSE,
                            ...){

  scales::label_pvalue(
    accuracy = accuracy,
    add_p = add_p,
    ...
  )(x)

}