rstatix (version 1.1.0)

cramer_v: Compute Cramer's V

Description

Compute Cramer's V, which measures the strength of the association between categorical variables.

See the Datanovia tutorial Chi-Square Test of Independence in R for a worked walkthrough.

Usage

cramer_v(x, y = NULL, correct = FALSE, ..., ci = FALSE, conf.level = 0.95)

Value

By default, a single numeric value: Cramer's V.

When ci = TRUE, a one-row tibble with the columns effsize

(Cramer's V), conf.low and conf.high -- the same confidence interval columns that anova_test(ci = ) returns.

Arguments

x

a numeric vector or matrix. x and y can also both be factors.

y

a numeric vector; ignored if x is a matrix. If x is a factor, y should be a factor of the same length.

correct

logical. If TRUE, Yates' continuity correction is applied when computing the chi-square statistic, which only affects 2x2 tables. Default is FALSE. Yates' correction improves the chi-square approximation to the null distribution of the test statistic, so it belongs to the test (see chisq_test()) rather than to an effect size: it shrinks the statistic and therefore biases Cramer's V downward. Set correct = TRUE to reproduce the value returned by earlier versions of rstatix, which applied the correction by default.

...

other arguments passed to the function chisq.test().

ci

logical. If TRUE, a confidence interval for Cramer's V is added to the result and a one-row data frame is returned instead of a single value. Default is FALSE.

conf.level

The level of the confidence interval. Default is 0.95. Only used when ci = TRUE.

Details

Cramer's V is \(V = \sqrt{\chi^2 / (N (k - 1))}\) (Cramer, 1946), where \(\chi^2\) is the Pearson chi-square statistic, \(N\) the total count and \(k\) the smaller of the two table dimensions.

The confidence interval is obtained by inverting the noncentral chi-square distribution (Smithson, 2003; Steiger, 2004): the noncentrality parameters \(\lambda\) whose distributions place the observed chi-square statistic at the \(1 - \alpha/2\) and \(\alpha/2\) quantiles are found by root finding, and each is converted with \(V = \sqrt{\lambda / (N (k - 1))}\). The interval is computed from the same chi-square statistic as the point estimate, so correct = TRUE shifts both.

The bounds are clipped to \([0, 1]\), the range of Cramer's V. They are NA, with a warning, when the statistic or its degrees of freedom are undefined -- for instance when the table has an empty row or column, or when simulate.p.value = TRUE is passed on to chisq.test(), which then reports no degrees of freedom.

The interval usually brackets the reported effsize, but it does not in the near-independence corner: when the observed chi-square falls below the \(\alpha/2\) quantile of its central distribution, no noncentrality is consistent with the data at that quantile, both bounds collapse to \([0, 0]\), and the (necessarily positive) point estimate lies above them. This is a property of the noncentral inversion rather than of this implementation, and it only arises for effect sizes indistinguishable from zero.

At the default correct = FALSE, the results match effectsize::cramers_v(adjust = FALSE, ci = , alternative = "two.sided") away from the near-independence corner above (where numerical inversions differ), and DescTools::CramerV(conf.level = ) to about four decimals (its inversion uses a looser tolerance), except at a chi-square of exactly zero, where DescTools returns NA bounds and this function returns the collapsed [0, 0] interval. Neither package applies Yates' continuity correction, so correct = TRUE values have no counterpart there (DescTools's own correct argument selects the Bergsma bias correction, a different adjustment).

References

Cramer, H. (1946). Mathematical Methods of Statistics. Princeton University Press.

Smithson, M. (2003). Confidence Intervals. Sage Publications.

Steiger, J. H. (2004). Beyond the F test: Effect size confidence intervals and tests of close fit in the analysis of variance and contrast analysis. Psychological Methods, 9, 164-182.

See Also

The Datanovia tutorial: Chi-Square Test of Independence in R.

Examples

# Data preparation
df <- as.table(rbind(c(762, 327, 468), c(484, 239, 477)))
dimnames(df) <- list(
  gender = c("F", "M"),
  party = c("Democrat","Independent", "Republican")
)
df
# Compute cramer's V
cramer_v(df)

# Add a confidence interval
cramer_v(df, ci = TRUE)

# Yates' continuity correction only affects 2x2 tables. It belongs to the
# test, not to the effect size, so it is off by default.
tab <- as.table(rbind(c(20, 30), c(35, 15)))
cramer_v(tab)
cramer_v(tab, correct = TRUE)