R/round_to_fraction.R

In sfirke/janitor: Simple Tools for Examining and Cleaning Dirty Data

#' Round to the nearest fraction of a specified denominator.
#'
#' @description
#' Round a decimal to the precise decimal value of a specified
#' fractional denominator.  Common use cases include addressing floating point
#' imprecision and enforcing that data values fall into a certain set.
#'
#' E.g., if a decimal represents hours and values should be logged to the nearest
#' minute, `round_to_fraction(x, 60)` would enforce that distribution and 0.57
#' would be rounded to 0.566667, the equivalent of 34/60.  0.56 would also be rounded
#' to 34/60.
#'
#' Set `denominator = 1` to round to whole numbers.
#'
#' The `digits` argument allows for rounding of the subsequent result.
#'
#' @details
#' If `digits` is `Inf`, `x` is rounded to the fraction
#' and then kept at full precision.  If `digits` is `"auto"`, the
#' number of digits is automatically selected as
#' `ceiling(log10(denominator)) + 1`.
#'
#' @param x A numeric vector
#' @param denominator The denominator of the fraction for rounding (a scalar or
#'   vector positive integer).
#' @param digits Integer indicating the number of decimal places to be used
#'   after rounding to the fraction.  This is passed to `base::round()`).
#'   Negative values are allowed (see Details). (`Inf` indicates no
#'   subsequent rounding)
#' @return the input x rounded to a decimal value that has an integer numerator relative
#'   to `denominator` (possibly subsequently rounded to a number of decimal
#'   digits).
#' @examples
#' round_to_fraction(1.6, denominator = 2)
#' round_to_fraction(pi, denominator = 7) # 22/7
#' round_to_fraction(c(8.1, 9.2), denominator = c(7, 8))
#' round_to_fraction(c(8.1, 9.2), denominator = c(7, 8), digits = 3)
#' round_to_fraction(c(8.1, 9.2, 10.3), denominator = c(7, 8, 1001), digits = "auto")
#' @export
round_to_fraction <- function(x, denominator, digits = Inf) {
  stopifnot(is.numeric(x))
  stopifnot(length(denominator) %in% c(1, length(x)))
  stopifnot(is.numeric(denominator))
  stopifnot(denominator >= 1)
  if (!(identical(digits, "auto") ||
    (is.numeric(digits) & (length(digits) %in% c(1, length(x)))))) {
    stop('`digits` must be either "auto" or a number that is either a scalar (length = 1) or the same length as `x`.')
  }
  ret <- round(x * denominator, digits = 0) / denominator
  if (identical(digits, "auto")) {
    digits <- ceiling(log10(denominator)) + 1
  }
  mask_inf_digits <- is.infinite(digits)
  if (!all(mask_inf_digits)) {
    ret[!mask_inf_digits] <-
      round(ret[!mask_inf_digits], digits = digits[!mask_inf_digits])
  }
  ret
}