R/biweight_midvariance.R

Defines functions biweight_terms biweight_midvariance

Documented in biweight_midvariance

#' @title Biweight Midvariance
#'
#' @description
#' This function calculates the biweight midvariance of a numeric vector,
#' which is a robust measure of scale that can be used to estimate the
#' variability of the data while being resistant to the influence of outliers.
#'
#' @details
#' For scale estimators, the standard deviation (or variance) is the optimal
#' estimator for Gaussian data. However, it is not resistant and it does not
#' have robustness of efficiency. In robust statistics, the median absolute
#' deviation (MAD) is a resistant estimate, but it has only modest robustness
#' of efficiency, while the biweight midvariance estimator is both resistant
#' and robust of efficiency.
#'
#' @references
#'    - Wilcox, R., (1997).
#'      Introduction to Robust Estimation and Hypothesis Testing.
#'      Academic Press
#'
#' @author Christian L. Goueguel
#'
#' @param x A numeric vector.
#' @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 midvariance of the input vector.
#'
#' @examples
#' data(forageLIBS)
#' # iron contents (mg/kg): a few samples are far above the others
#' fe <- forageLIBS$Fe[!is.na(forageLIBS$Fe)]
#' c(variance = stats::var(fe), biweight = biweight_midvariance(fe))
#'
#' @export biweight_midvariance
#'
biweight_midvariance <- function(x, drop_na = FALSE,
                                 drop.na = deprecated()) {
  drop_na <- renamed_arg(drop.na, drop_na, "biweight_midvariance", "drop.na", "drop_na")

  if (missing(x)) {
    stop("Input 'x' must be provided.")
  }
  check_numeric_vector(x, "biweight_midvariance")
  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("The length of 'x' cannot be less than 2.")
  }
  if (length(unique(x)) == 1) {
    stop("Input 'x' cannot be constant a vector.")
  }

  w <- biweight_terms(x)
  if (is.null(w)) {
    return(0)
  }
  return(length(x) * sum(w$a^2) / sum(w$d)^2)
}

# Terms shared by the biweight midvariance, midcovariance and midcorrelation
# (Wilcox, 1997): a_i = (x_i - M)(1 - u_i^2)^2 and d_i = (1 - u_i^2)(1 - 5u_i^2)
# over |u_i| < 1, with u_i = (x_i - M) / (9 * MAD). Returns NULL when MAD = 0.
biweight_terms <- function(x) {
  med <- stats::median(x)
  mad_x <- stats::mad(x, center = med, constant = 1)
  if (mad_x == 0) {
    return(NULL)
  }
  u <- (x - med) / (9 * mad_x)
  keep <- as.numeric(abs(u) < 1)
  list(
    a = keep * (x - med) * (1 - u^2)^2,
    d = keep * (1 - u^2) * (1 - 5 * u^2)
  )
}

Try the specProc package in your browser

Any scripts or data that you put into this service are public.

specProc documentation built on Nov. 20, 2026, 5:11 p.m.