Nothing
#' @title Unbiased Median Absolute Deviation
#'
#' @author Christian L. Goueguel
#'
#' @description
#' This function calculates the Median Absolute Deviation (MAD) scale
#' estimator for a numeric vector, using the Park-Kim-Wang approach. The method
#' adds a small sample correction factor to make MAD unbiased at the normal distribution.
#'
#' @details
#' The correction factor, \eqn{C}, is calculated differently based on the sample size \eqn{n}:
#' - For \eqn{n > 100}, \eqn{C} is calculated using an analytical approximation
#' proposed by either Hayes (2014) or Williams (2011).
#' - For \eqn{n \leq 100}, \eqn{C} is obtained from a pre-computed table of
#' values proposed by Park *et al.* (2020).
#'
#' @references
#' - Park, C., Kim, H., Wang, M., (2020).
#' Investigation of finite-sample properties of robust location and scale
#' estimators.
#' Communications in Statistics - Simulation and Computation, 51(5):2619–2645.
#' - Hayes, K., (2014).
#' Finite-Sample Bias-Correction Factors for the Median
#' Absolute Deviation.Communications in Statistics - Simulation and Computation, 43(10):2205–2212.
#' - Williams, D.C., (2011).
#' Finite sample correction factors for several simple robust estimators of
#' normal standard deviation.
#' Journal of Statistical Computation and Simulation, 81(11):1697–1702.
#'
#' @param x A numeric vector.
#' @param method A character string specifying the method to use for calculating the correction factor when the number of sample is more than 100. The available options are "hayes" (default) and "williams".
#' @param drop_na A logical value indicating whether to remove missing values (NA) from the calculations. If `TRUE` (the default), missing values will be removed. If `FALSE`, missing values will be included.
#' @param drop.na `r lifecycle::badge("deprecated")` Use `drop_na`.
#'
#' @return The MAD scale estimate for the input vector `x`.
#'
#' @export umad
#'
#' @examples
#' # mad() is unbiased for the standard deviation of a normal distribution
#' # only in large samples. In 2000 samples of 5 replicate values from a
#' # standard normal distribution (standard deviation 1), mad() is low by
#' # about 16% on average, while umad() is unbiased
#' set.seed(1)
#' samples <- replicate(2000, rnorm(5), simplify = FALSE)
#' est <- data.frame(estimator = rep(c("mad()", "umad()"), each = 2000),
#' value = c(sapply(samples, mad), sapply(samples, umad)))
#' means <- tapply(est$value, est$estimator, mean)
#' round(means, 3)
#' # the estimates from 5 values are skewed: the peak of umad() lies below 1,
#' # but its mean (solid line) is at 1 (dashed line)
#' ggplot2::ggplot(est, ggplot2::aes(value, fill = estimator)) +
#' ggplot2::geom_density(alpha = 0.4) +
#' ggplot2::geom_vline(xintercept = means, colour = c("#b2182b", "#2166ac")) +
#' ggplot2::geom_vline(xintercept = 1, linetype = "dashed") +
#' ggplot2::scale_fill_manual(values = c("#b2182b", "#2166ac"))
#'
#' # the bias of mad() fades as the samples grow: the means of each
#' # estimator over 1000 samples of n values
#' set.seed(2)
#' bias <- sapply(c(3, 5, 10, 30, 100), function(n) {
#' s <- replicate(1000, rnorm(n), simplify = FALSE)
#' c(n = n, mad = mean(sapply(s, mad)), umad = mean(sapply(s, umad)))
#' })
#' round(bias, 3)
#'
#' # both are robust: two outliers inflate the standard deviation, but
#' # neither MAD
#' set.seed(1)
#' x <- c(rnorm(50), 10, 12)
#' sd(x)
#' mad(x)
#' umad(x)
umad <- function(x, method = "hayes", drop_na = TRUE,
drop.na = deprecated()) {
drop_na <- renamed_arg(drop.na, drop_na, "umad", "drop.na", "drop_na")
if (missing(x)) {
stop("Missing 'x' argument.")
}
check_numeric_vector(x, "umad")
if (!is.logical(drop_na) || length(drop_na) != 1) {
stop("'drop_na' must be a single logical value (TRUE or FALSE).")
}
if (!is.character(method) || !(method %in% c("hayes", "williams"))) {
stop("'method' must be either 'hayes' or 'williams'.")
}
if (drop_na) {
x <- x[!is.na(x)]
}
if (length(x) < 2) {
stop("The size of 'x' must be greater than 1")
} else {
n <- length(x)
}
if (all(x == x[1])) {
stop("All values in the vector 'x' are the same (constant value).")
}
med_x <- stats::median(x)
mad_x <- stats::median(abs(x - med_x))
if (n > 100) {
if (method == "hayes") {
a <- -(0.76213 / n) - (0.86413 / n^2)
} else {
a <- -0.804168866 * n^(-1.008922)
}
c_n <- 1 / (stats::qnorm(3/4) * (1 + a))
} else {
factors <- c(
NA, 1.772150, 2.204907, 2.016673, 1.803927, 1.763788, 1.686813,
1.671843, 1.632940, 1.624681, 1.601308, 1.596155, 1.580754, 1.577272,
1.566339, 1.563769, 1.555284, 1.553370, 1.547206, 1.545705, 1.540681,
1.539302, 1.535165, 1.534053, 1.530517, 1.529996, 1.526916, 1.526422,
1.523608, 1.523031, 1.520732, 1.520333, 1.518509, 1.517941, 1.516279,
1.516070, 1.514425, 1.513989, 1.512747, 1.512418, 1.511078, 1.511041,
1.509858, 1.509499, 1.508529, 1.508365, 1.507535, 1.507247, 1.506382,
1.506307, 1.505611, 1.505172, 1.504575, 1.504417, 1.503713, 1.503604,
1.503095, 1.502864, 1.502253, 1.502085, 1.501611, 1.501460, 1.501019,
1.500841, 1.500331, 1.500343, 1.499877, 1.499772, 1.499291, 1.499216,
1.498922, 1.498838, 1.498491, 1.498399, 1.497917, 1.497901, 1.497489,
1.497544, 1.497248, 1.497185, 1.496797, 1.496779, 1.496428, 1.496501,
1.496295, 1.496089, 1.495794, 1.495796, 1.495557, 1.495420, 1.495270,
1.495141, 1.494944, 1.494958, 1.494706, 1.494665, 1.494379, 1.494331,
1.494113, 1.494199
)
c_n <- factors[n]
}
mad_n <- c_n * mad_x
return(mad_n)
}
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.