Nothing
#' @title Biweight Scale
#'
#' @description
#' This function computes the biweight scale, a robust measure of scale or dispersion
#' for a numeric vector. The biweight scale is less sensitive to outliers
#' than the sample standard deviation.
#'
#' @details
#' The biweight scale is the square root of the biweight midvariance:
#' \deqn{\zeta = \frac{\sqrt{n \sum_{|u_i|<1} (x_i - M)^2 (1 - u_i^2)^4}}
#' {\left| \sum_{|u_i|<1} (1 - u_i^2)(1 - 5u_i^2) \right|},
#' \quad u_i = \frac{x_i - M}{c \cdot \mathrm{MAD}}}
#' where \eqn{M} is the location (the median by default) and MAD is the
#' (unscaled) median absolute deviation. For normally distributed data the
#' biweight scale is a consistent estimator of the standard deviation.
#'
#' @param x A numeric vector.
#' @param loc The location about which the scale is computed (default: median of `x`).
#' @param c A numeric value specifying the tuning constant for the biweight estimator (`c = 9` by default).
#' @param reduced A logical value specifying whether the sample size, *n*, should be reduced to the number of non-rejected values. If `TRUE`, *n* is reduced to the number of observations that pass a rejection criteria (\eqn{|u_i| < 1}). If `FALSE` (default), *n* is equal to the length of `x` (the input data).
#' @param drop_na A logical value indicating whether to remove missing values (\code{NA}) from the calculations. If \code{TRUE}, missing values will be removed. If \code{FALSE} (the default), the result is \code{NA} when `x` contains missing values.
#' @param drop.na `r lifecycle::badge("deprecated")` Use `drop_na`.
#'
#' @return The biweight scale of `x`.
#'
#' @author Christian L. Goueguel
#'
#' @references
#' - Mosteller, F., and Tukey, J. W. (1977).
#' Data Analysis and Regression: A Second Course in Statistics.
#' Addison-Wesley, pp. 203-209.
#' - Beers, T.C., Flynn, K., Gebhardt, K., (1990).
#' Measures of location and scale for velocities in clusters of galaxies - A robust approach.
#' The Astronomical Journal, 100:32-46.
#'
#' @examples
#' data(forageLIBS)
#' # iron contents (mg/kg): a few samples are far above the others
#' fe <- forageLIBS$Fe[!is.na(forageLIBS$Fe)]
#' c(sd = stats::sd(fe), mad = stats::mad(fe), biweight = biweight_scale(fe))
#'
#' @export biweight_scale
#'
biweight_scale <- function(x, loc = NULL, c = 9, reduced = FALSE, drop_na = FALSE,
drop.na = deprecated()) {
drop_na <- renamed_arg(drop.na, drop_na, "biweight_scale", "drop.na", "drop_na")
if (missing(x)) {
stop("Input 'x' must be provided.")
}
check_numeric_vector(x, "biweight_scale")
if (!is.numeric(c)) {
stop("'c' must be numeric.")
}
if (!is.logical(reduced)) {
stop("'reduced' must be a logical value (TRUE or FALSE).")
}
check_flag(drop_na, "drop_na")
if (drop_na) {
x <- x[!is.na(x)]
} else if (anyNA(x)) {
return(NA_real_)
}
if (length(x) < 2) {
stop("'x' must have at least two elements.")
}
if (length(unique(x)) == 1) {
stop("'x' cannot be a constant vector.")
}
if (is.null(loc)) {
loc <- stats::median(x)
}
mad_x <- stats::mad(x, center = loc, constant = 1)
if (mad_x == 0) {
return(0)
}
u <- (x - loc) / (c * mad_x)
keep <- abs(u) < 1
u2 <- u[keep]^2
num <- sum((x[keep] - loc)^2 * (1 - u2)^4)
den <- sum((1 - u2) * (1 - 5 * u2))
n <- if (reduced) sum(keep) else length(x)
return(sqrt(n * num) / abs(den))
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.