R/capValues.R

In nwfsc-assess/PacFIN.Utilities: Generate fishery composition data from PacFIN data for the NWFSC

##########################################################################
#'
#' Decrease all values greater than a maximum specified value.
#'
#' \code{capValues} takes a numeric vector and returns a vector in which all
#' values greater than a specified maximum are reset to that maximum
#' value.
#'
#'
#' @export
#'
#' @details The maximum may be specified either as a
#' quantile or as a number.
#'
#' If \code{maxVal} is less than one, it is
#' interpreted as a quantile, otherwise it is interpreted as the maximum
#' value to return.
#'
#' The default value is \code{0.95}, which caps all
#' values in the input at the 95 percent quantile.
#'
#'
#' @param DataCol A vector of numeric values.
#' @param maxVal A numeric value specifying the maximum value or quantile
#'   at which to cap all data.
#' @return A vector of numeric values where no value is greater than the
#'   maximum specified by \code{maxVal}.
#'
#' @section Example:
#'
#' x = seq(1,10)
#' y <- capValues(x, 0.75)
#' z <- capValues(x, 5)
#' rbind(x, y, z)
#'
#' @author Andi Stephens
#'
###########################################################################

capValues <- function(DataCol,
                      maxVal = 0.95) {
  if (maxVal > 1) {
    max.val <- maxVal
    cat("\nMaximum value capped at", max.val, "\n\n")
  } else {
    max.val <- stats::quantile(DataCol, maxVal, na.rm = T)
    cat("\nMaximum expansion capped at", maxVal, "quantile:", max.val, "\n\n")
  } # End if-else

  DataCol[DataCol > max.val] <- max.val

  return(DataCol)
} # End function capValues