Rename normalized_chi() to fei() (#475)

DESCRIPTION

@@ -89,7 +89,7 @@ VignetteBuilder:
 Encoding: UTF-8
 Language: en-US
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.1.9000
 Config/testthat/edition: 3
 Config/testthat/parallel: true
 Config/Needs/website:

NAMESPACE

@@ -53,6 +53,7 @@ export(F_to_omega2)
 export(F_to_r)
 export(chisq_to_cohens_w)
 export(chisq_to_cramers_v)
+export(chisq_to_fei)
 export(chisq_to_normalized)
 export(chisq_to_pearsons_c)
 export(chisq_to_phi)
@@ -93,6 +94,7 @@ export(eta_squared)
 export(eta_squared_posterior)
 export(f2_to_eta2)
 export(f_to_eta2)
+export(fei)
 export(format_standardize)
 export(get_effectsize_label)
 export(get_effectsize_name)

NEWS.md

@@ -1,6 +1,9 @@
-
 # effectsize 0.7.0.9999
 
+## Breaking Changes
+
+- `normalized_chi()` has been renamed `fei()`.
+
 ## Bug fixes
 
 - Effect sizes for goodness-of-fit now work when passing a `p` that is a table.

R/convert_stat_chisq.R

@@ -1,10 +1,13 @@
-#' Conversion Chi-Squared to Phi or Cramer's V
+#' Convert chi-square to correlation-like effect sizes (phi, V, Fei, C)
 #'
-#' Convert between Chi square (\eqn{\chi^2}), Cramer's V, phi (\eqn{\phi}),
-#' Cohen's *w*, normalized Chi (\eqn{\chi}) and Pearson's *C* for contingency
-#' tables or goodness of fit.
+#' Convert between \eqn{\chi^2} (chi-square), \eqn{\phi} (phi), Cramer's \eqn{V},
+#' Cohen's \eqn{w}, \ifelse{latex}{\eqn{Fei}}{פ (Fei)} and Pearson's \eqn{C}
+#' for contingency tables or goodness of fit.
 #'
-#' @param chisq The Chi-squared statistic.
+#' @name chisq_to_phi
+#' @rdname convert_chisq
+#'
+#' @param chisq The \eqn{\chi^2} (chi-square) statistic.
 #' @param n Total sample size.
 #' @param nrow,ncol The number of rows/columns in the contingency table.
 #' @param ci Confidence Interval (CI) level
@@ -19,18 +22,25 @@
 #' @return A data frame with the effect size(s), and confidence interval(s). See
 #'   [cramers_v()].
 #'
-#' @details These functions use the following formulae:
-#' \cr
-#' \deqn{\phi = \sqrt{\chi^2 / n}}{phi = sqrt(\chi^2 / n)}
-#' \cr
-#' \deqn{Cramer's V = \phi / \sqrt{min(nrow,ncol)-1}}{Cramer's V = \phi / sqrt(min(nrow,ncol)-1)}
-#' \cr
-#' \deqn{Pearson's C = \sqrt{\chi^2 / (\chi^2 + n)}}{Pearson's C = sqrt(\chi^2 / (\chi^2 + n))}
-#' \cr
-#' \deqn{\chi_{Normalized} = w \times \sqrt{\frac{q}{1-q}}}{Chi (Normalized) = w * sqrt(q/(1-q))}
-#' Where `q` is the smallest of the expected probabilities.
-#' \cr\cr
-#' For adjusted versions of *phi* and *V*, see Bergsma, 2013.
+#' @details These functions use the following formulas:
+#'
+#' \deqn{\phi = w = \sqrt{\chi^2 / n}}{phi = w = sqrt(\frac{\chi^2}{n})}
+#' \ifelse{latex}{
+#' \deqn{\textrm{Cramer's } V = \phi / \sqrt{\min(\textit{nrow}, \textit{ncol}) - 1}}
+#' }{
+#' \deqn{\textrm{Cramer's } V = \phi / \sqrt{\min(\textit{nrow}, \textit{ncol }) - 1}}{Cramer's V = \phi / sqrt(min(nrow, ncol) - 1)}
+#' }
+#'
+#' \ifelse{latex}{
+#' \deqn{\textit{Fei} = \phi / \sqrt{[1 / \min(p_E)] - 1}}
+#' }{
+#' \deqn{פ = \phi / \sqrt{[1 / \min(p_E)] - 1}}{פ = w / sqrt(1 / min(p_E) - 1))}
+#' }
+#' Where \eqn{p_E} are the expected probabilities.
+#'
+#' \deqn{\textrm{Pearson's } C = \sqrt{\chi^2 / (\chi^2 + n)}}{Pearson's C = sqrt(\chi^2 / (\chi^2 + n))}
+#'
+#' For adjusted versions of \eqn{\phi} and \eqn{V}, see Bergsma, 2013.
 #'
 #' @inheritSection effectsize_CIs Confidence (Compatibility) Intervals (CIs)
 #' @inheritSection effectsize_CIs CIs and Significance Tests
@@ -65,7 +75,7 @@
 #' #> data:  Smoking_ASD
 #' #> X-squared = 7.8521, df = 2, p-value = 0.01972
 #'
-#' chisq_to_normalized(
+#' chisq_to_fei(
 #'   7.8521,
 #'   n = sum(Smoking_ASD),
 #'   nrow = 1,
@@ -160,7 +170,7 @@ chisq_to_phi <- function(chisq, n, nrow = 2, ncol = 2, ci = 0.95, alternative =
 }
 
 
-#' @rdname chisq_to_phi
+#' @rdname convert_chisq
 #' @export
 chisq_to_cohens_w <- function(chisq, n, nrow, ncol, ci = 0.95, alternative = "greater", ...) {
   res <- chisq_to_phi(chisq, n, nrow, ncol, ci = ci, alternative = alternative, adjust = FALSE, dont_stop = TRUE)
@@ -191,7 +201,7 @@ chisq_to_cohens_w <- function(chisq, n, nrow, ncol, ci = 0.95, alternative = "gr
   return(res)
 }
 
-#' @rdname chisq_to_phi
+#' @rdname convert_chisq
 #' @export
 chisq_to_cramers_v <- function(chisq, n, nrow, ncol, ci = 0.95, alternative = "greater", adjust = FALSE, ...) {
   if (ncol == 1 || nrow == 1) {
@@ -226,10 +236,10 @@ chisq_to_cramers_v <- function(chisq, n, nrow, ncol, ci = 0.95, alternative = "g
 }
 
 
-#' @rdname chisq_to_phi
+#' @rdname convert_chisq
 #' @export
 #' @param p Vector of expected values. See [stats::chisq.test()].
-chisq_to_normalized <- function(chisq, n, nrow, ncol, p,
+chisq_to_fei <- function(chisq, n, nrow, ncol, p,
                                 ci = 0.95, alternative = "greater", ...) {
   if (is.numeric(ci) || (!missing(nrow) && !missing(ncol))) {
     # This means that the user passed ncol/nrow
@@ -255,7 +265,7 @@ chisq_to_normalized <- function(chisq, n, nrow, ncol, p,
   N <- n * (1 - q) / q
 
   res <- chisq_to_phi(chisq, N, nrow, ncol, ci = ci, alternative = alternative, adjust = FALSE, dont_stop = TRUE)
-  colnames(res)[1] <- "normalized_chi"
+  colnames(res)[1] <- "Fei"
 
   if ("CI" %in% colnames(res)) {
     if ((alternative <- attr(res, "alternative")) == "less") {
@@ -272,7 +282,7 @@ chisq_to_normalized <- function(chisq, n, nrow, ncol, p,
   return(res)
 }
 
-#' @rdname chisq_to_phi
+#' @rdname convert_chisq
 #' @export
 chisq_to_pearsons_c <- function(chisq, n, nrow, ncol, ci = 0.95, alternative = "greater", ...) {
   res <- chisq_to_phi(chisq, n, nrow, ncol, ci = ci, alternative = alternative, adjust = FALSE, dont_stop = TRUE)
@@ -292,8 +302,8 @@ chisq_to_pearsons_c <- function(chisq, n, nrow, ncol, ci = 0.95, alternative = "
 
 # Reverse -----------------------------------------------------------------
 
-#' @rdname chisq_to_phi
-#' @param phi The Phi statistic.
+#' @rdname convert_chisq
+#' @param phi The \eqn{\phi} (phi) statistic.
 #' @export
 phi_to_chisq <- function(phi, n, ...) {
   n * (phi^2)

R/effectsize.R

@@ -13,7 +13,7 @@
 #' - For an object of class `htest`, data is extracted via [insight::get_data()], and passed to the relevant function according to:
 #'   - A **t-test** depending on `type`: `"cohens_d"` (default), `"hedges_g"`, or `"cles"`.
 #'   - A **Chi-squared tests of independence**, depending on `type`: `"cramers_v"` (default), `"phi"`, `"cohens_w"`, `"pearsons_c"`, `"cohens_h"`, `"oddsratio"`, or `"riskratio"`.
-#'   - A **Chi-squared tests of goodness-of-fit**, depending on `type`: `"normalized_chi"` (default) `"cohens_w"`, `"pearsons_c"`
+#'   - A **Chi-squared tests of goodness-of-fit**, depending on `type`: `"fei"` (default) `"cohens_w"`, `"pearsons_c"`
 #'   - A **One-way ANOVA test**, depending on `type`: `"eta"` (default), `"omega"` or `"epsilon"` -squared, `"f"`, or `"f2"`.
 #'   - A **McNemar test** returns *Cohen's g*.
 #'   - A **Wilcoxon test** depending on `type`: returns "`rank_biserial`" correlation (default) or `"cles"`.

R/effectsize.htest.R

@@ -114,14 +114,14 @@ effectsize.htest <- function(model, type = NULL, verbose = TRUE, ...) {
 
   if (is.null(type)) {
     if (nr == 1 || nc == 1) {
-      type <- "normalized_chi"
+      type <- "fei"
     } else {
       type <- "cramers_v"
     }
   }
 
-  if (grepl("(c|v|w|phi)$", tolower(type)) || tolower(type) %in% c("normalized_chi", "chi")) {
-    if (tolower(type) %in% c("normalized_chi", "chi")) {
+  if (grepl("(c|v|w|phi|fei)$", tolower(type))) {
+    if (tolower(type) == "fei") {
       p <- Exp
     } else {
       p <- NULL
@@ -136,7 +136,8 @@ effectsize.htest <- function(model, type = NULL, verbose = TRUE, ...) {
       c = ,
       pearsons_c = chisq_to_pearsons_c,
       chi = ,
-      normalized_chi = chisq_to_normalized
+      normalized_chi = ,
+      fei = chisq_to_fei
     )
 
     out <- f(

R/interpret.R

@@ -172,6 +172,7 @@ interpret.effectsize_table <- function(x, rules, ...) {
     Cramers_v = ,
     Cramers_v_adjusted = ,
     normalized_chi = ,
+    fei = ,
     Cohens_w = ,
     phi = ,
     phi_adjusted = interpret_cramers_v(value, rules = rules),

R/is_effectsize_name.R

@@ -55,7 +55,7 @@ es_info <- matrix(
     "phi_adjusted", "Phi (adj.)", "onetail", 0, 1, 0,
     "Pearsons_c", "Pearson's C", "onetail", 0, 1, 0,
     "Cohens_w", "Cohen's w", "onetail", 0, Inf, 0,
-    "normalized_chi", "Norm. Chi", "onetail", 0, 1, 0,
+    "Fei", "Fei", "onetail", 0, 1, 0,
     "Cohens_g", "Cohen's g", "onetail", -0.5, 0.5, 0,
     "Cohens_h", "Cohen's h", "twotail", -pi, pi, 0,
     "Odds_ratio", "Odds ratio", "twotail", 0, Inf, 1,