Weighted Pearson correlation — weighted

Computes the weighted Pearson correlation coefficient $r$ between two numeric vectors.

Usage

weighted_cor(x, y, w = NULL)

weighted_cor_sq(x, y, w = NULL)

Arguments

x: (numeric)
The first variable whose weighted correlation with y is computed. Observations with missing or non-finite values are excluded pairwise.
y: (numeric)
The second variable whose weighted correlation with x is computed. Observations with missing or non-finite values are excluded pairwise.
w: (numeric or NULL)
Weights used to compute the weighted correlation. If numeric, values must be nonnegative and the same length as x and y. Zero weights are allowed. Observations with missing, negative, or non-finite values are excluded pairwise. Set to NULL (default) for an unweighted computation.

Value

weighted_cor(): Scalar numeric in $[-1, 1]$ or NA_real_.
weighted_cor_sq(): Scalar numeric $[0, 1]$ or NA_real_.

Returns NA_real_ if all observations are removed during filtering or the total weight is nonpositive. Returns 0 if either weighted variance is nonpositive.

Details

This implementation uses the population definition of correlation (no Bessel ($n-1$) correction in variance).

Observations with any non-finite value in x, y, or w, or with negative weight, are excluded. Zero weights are allowed and contribute nothing.

Let $w_i \ge 0$ denote row weights for $i=1, \dots, n$ and $\tilde{w}$ be the sum-to-1 normalized weights. For the pairwise complete subset, $\mathcal{I}\subseteq\{1,\dots,n\}$:

$$ \bar{x} = \frac{\sum_{i\in\mathcal{I}} \tilde{w}_i x_i} {\sum_{i\in\mathcal{I}} \tilde{w}_i} $$

$$ \mathrm{var}_w(x) = \sum_{i\in\mathcal{I}} \tilde{w}_i\,(x_i-\bar{x})^2, $$

$$ \mathrm{cov}_w(x,y) = \sum_{i\in\mathcal{I}} \tilde{w}_i\,(x_i-\bar{x})(y_i-\bar{y}) $$

$$ r_w(x,y) = \frac{\mathrm{cov}_w(x,y)}{\sqrt{\mathrm{var}_w(x)\,\mathrm{var}_w(y)}}. $$

The helper weighted_cor_sq() returns $r_w^2$, the weighted squared Pearson correlation.

Examples

#----------------------------------------------------------------------------
# weighted_cor() examples
#----------------------------------------------------------------------------
library(vclust)

# Basic usage with equal weights
x <- c(1, 2, 3, 4, 5)
y <- c(2, 1, 4, 3, 5)
w <- rep(1, length(x))
weighted_cor(x, y, w)
#> [1] 0.8
weighted_cor(x, y)
#> [1] 0.8

# Heavier weight on the last two observations
w2 <- c(1, 1, 1, 5, 5)
weighted_cor(x, y, w2)
#> [1] 0.8319762
weighted_cor_sq(x, y, w2)
#> [1] 0.6921844

# Pairwise handling of missing values
x_na <- c(1, NA, 3, 4, 5)
y_na <- c(2, 1, 4, NA, 5)
w_na <- c(1, 1, 1, NA, 1)
weighted_cor(x_na, y_na, w_na)
#> [1] 0.9819805

# Zero weights exclude observations without removing length alignment
w_zero <- c(1, 0, 1, 0, 1)
weighted_cor(x, y, w_zero)
#> [1] 0.9819805

# Degenerate case: zero variance in x
x_const <- c(3, 3, 3, 3)
y_any   <- c(1, 2, 3, 4)
weighted_cor(x_const, y_any)
#> [1] 0