Weighted \(\eta\) association

Computes the weighted \(\eta\) and \(\eta^2\), a measure for the association between a numeric variable \(x\) and a single categorical variable \(y\).

Usage

weighted_eta_sq(x, y, w = NULL)

weighted_eta(x, y, w = NULL)

Arguments

x

(numeric)
The numeric variable whose weighted association with factor y is computed. Observations with missing or non-finite values are excluded pairwise.

y

(factor)
The factor variable whose weighted association with numeric x is computed. Observations with missing or non-finite values are excluded pairwise. Non-factor inputs are coerced via as.factor(y).

w

(numeric or NULL)
Weights used to compute the weighted association. 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_eta_sq(): Scalar numeric \([0, 1]\) or NA_real_.

• weighted_eta(): Scalar numeric in \([0, 1]\) or NA_real_.

Returns NA_real_ if all observations are removed during filtering or the total weight is nonpositive. Returns 0 if fewer than two nonempty groups remain or if the weighted total sum of squares is non-finite or effectively zero.

Details

Let \(x_i \in \mathbb{R}\) denote the numeric response for observation \(i = 1,\dots,n\), \(y_i \in \{1,\dots,G\}\) denote the group membership, and \(w_i \ge 0\) be the weight for observation \(i\). Internally, non-finite \(x_i\) or \(w_i\), missing \(y_i\), and negative \(w_i\) observations are removed pairwise prior to computation.

The weights are normalized to sum to one, i.e., \(\tilde{w}_i = w_i / \sum_{j=1}^n w_j\) with \(\sum_i \tilde{w}_i = 1\). Define group weights \(W_g = \sum_{i : y_i = g} \tilde{w}_i\) and group means \(\bar{x}_g = \left(\sum_{i : y_i = g} \tilde{w}_i x_i\right) / W_g\) for groups with \(W_g > 0\). The weighted grand mean is \(\bar{x} = \sum_{i=1}^n \tilde{w}_i x_i\).

The between-group sum of squares is

$$ \mathrm{SSB} = \sum_{g=1}^G W_g (\bar{x}_g - \bar{x})^2, $$

and the total sum of squares is

$$ \mathrm{SST} = \sum_{i=1}^n \tilde{w}_i (x_i - \bar{x})^2. $$

The weighted eta-squared is then

$$ \eta^2(x \mid y) = \frac{\mathrm{SSB}}{\mathrm{SST}}. $$

This quantity lies in \([0,1]\) and is truncated to that interval for numerical robustness.

Groups with zero total weight \(W_g = 0\) are dropped from the SSB computation. If there are fewer than two nonempty groups, or if \(\mathrm{SST}\) is non-finite, the function returns 0. This implementation corresponds to the standard (fixed-effects, one-way) eta-squared effect size.

The helper weighted_eta() returns \(\eta(x \mid y)\), the weighted association, which takes values in \([0,1]\).

Examples

#----------------------------------------------------------------------------
# weighted_eta_sq() examples
#----------------------------------------------------------------------------
library(vclust)

set.seed(123)
n <- 30
x <- rnorm(n, mean = rep(c(0, 0.5, 1), each = n/3), sd = 1)
y <- factor(rep(LETTERS[1:3], each = n/3))

# Unweighted eta-squared (all weights equal)
weighted_eta_sq(x, y)
#> [1] 0.08005536
weighted_eta_sq(x, y, rep_len(1, n))
#> [1] 0.08005536

# With nonnegative weights that upweight group C
w <- rep_len(1, n)
w[y == "C"] <- 2
weighted_eta_sq(x, y, w)
#> [1] 0.06552423

# Rows with NA/Inf in x or w are dropped automatically
x_bad <- x
x_bad[c(2, 10)] <- NA
w_bad <- w
w_bad[5] <- Inf
weighted_eta_sq(x_bad, y, w_bad)
#> [1] 0.03485878

# Degenerate cases
## Single nonempty group after zeroing weights returns 0
w_single <- as.numeric(y == "A")
weighted_eta_sq(x, y, w_single)
#> [1] 0

## All rows removed (e.g., all weights negative) returns NA_real_
w_all_bad <- rep(-1, n)
weighted_eta_sq(x, y, w_all_bad)
#> [1] NA