From 4892756e211eecac21bbf93fcbff70f8c67fe402 Mon Sep 17 00:00:00 2001
From: mattansb <35330040+mattansb@users.noreply.github.com>
Date: Sun, 29 Nov 2020 11:14:06 +0200
Subject: [PATCH] #212

---
 R/cohens_d.R                       | 12 ++++++++----
 R/convert_d_to_r.R                 |  7 ++++---
 R/convert_tFz_to_r.R               | 20 +++++++++++++-------
 man/d_to_r.Rd                      |  7 ++++---
 man/t_to_r.Rd                      | 20 +++++++++++++-------
 vignettes/from_test_statistics.Rmd | 15 +++++++++++----
 6 files changed, 53 insertions(+), 28 deletions(-)

diff --git a/R/cohens_d.R b/R/cohens_d.R
index 1320e0162..58ca8ee14 100644
--- a/R/cohens_d.R
+++ b/R/cohens_d.R
@@ -107,7 +107,7 @@ glass_delta <- function(x, y = NULL, data = NULL, correction = FALSE, ci = 0.95)
 
 
 
-#' @importFrom stats sd na.omit
+#' @importFrom stats sd na.omit complete.cases
 #' @keywords internal
 .effect_size_difference <- function(x,
                                     y = NULL,
@@ -131,9 +131,13 @@ glass_delta <- function(x, y = NULL, data = NULL, correction = FALSE, ci = 0.95)
 
   # Compute index
   if (paired) {
-    d <- mean(x - y, na.rm = TRUE)
-    s <- stats::sd(x - y, na.rm = TRUE)
-    n <- length(stats::na.omit(x - y))
+    o <- stats::complete.cases(x,y)
+    x <- x[o]
+    y <- y[o]
+
+    d <- mean(x - y)
+    s <- stats::sd(x - y)
+    n <- length(x)
     df <- n - 1
     hn <- 1 / df
     t <- d / (s / sqrt(n))
diff --git a/R/convert_d_to_r.R b/R/convert_d_to_r.R
index a89c5be1e..1160779f8 100644
--- a/R/convert_d_to_r.R
+++ b/R/convert_d_to_r.R
@@ -26,15 +26,16 @@
 #' @return Converted index.
 #'
 #' @details
+#' Conversions between *OR* and *r* is done through these formulae.
 #' - *d to r*: \eqn{d = \frac{2 * r}{\sqrt{1 - r^2}}}
 #' - *r to d*: \eqn{r = \frac{d}{\sqrt{d^2 + 4}}}
 #' - *OR to d*: \eqn{d = \frac{\log(OR)\times\sqrt{3}}{\pi}}
 #' - *d to OR*: \eqn{log(OR) = d * \frac{\pi}{\sqrt(3)}}
 #'
-#' Conversions between *OR* and *r* is done through these formulae.
 #' \cr\cr
-#' When converting *d* to *r*, the resulting *r* is also called the binomial
-#' effect size display (BESD; Rosenthal et al., 1982).
+#' The conversion from *d* to *r* assumes equally sized groups. The resulting
+#' *r* is also called the binomial effect size display (BESD; Rosenthal et al.,
+#' 1982).
 #'
 #' @references
 #' - Sánchez-Meca, J., Marín-Martínez, F., & Chacón-Moscoso, S. (2003). Effect-size indices for dichotomized outcomes in meta-analysis. Psychological methods, 8(4), 448.
diff --git a/R/convert_tFz_to_r.R b/R/convert_tFz_to_r.R
index e3ed7f2ab..5bdafd713 100644
--- a/R/convert_tFz_to_r.R
+++ b/R/convert_tFz_to_r.R
@@ -26,11 +26,15 @@
 #' \cr\cr
 #' \deqn{r_{partial} = z / \sqrt{z^2 + N}}
 #' \cr\cr
-#' \deqn{Cohen's d = 2 * t / \sqrt{df_{error}}}
+#' \deqn{d = 2 * t / \sqrt{df_{error}}}
 #' \cr\cr
-#' \deqn{Cohen's d_z = t / \sqrt{df_{error}}}
+#' \deqn{d_z = t / \sqrt{df_{error}}}
 #' \cr\cr
-#' \deqn{Cohen's d = 2 * z / \sqrt{N}}
+#' \deqn{d = 2 * z / \sqrt{N}}
+#'
+#' The resulting `d` effect size is an *approximation* to Cohen's *d*, and
+#' assumes equal group sizes. When possible, it is advised to directly estimate
+#' Cohen's *d*, with [cohens_d()], [emmeans::eff_size()], or similar functions.
 #'
 #' @inheritSection cohens_d Confidence Intervals
 #'
@@ -65,16 +69,18 @@
 #' if (require(emmeans)) {
 #'   warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks)
 #'
-#'   conts <- summary(pairs(emmeans(warp.lm,  ~ tension | wool)))
-#'   t_to_d(conts$t.ratio, conts$df)
-#' }
 #'
+#'   # Also see emmeans::eff_size()
+#'   em_tension <- emmeans(warp.lm,  ~ tension)#'
+#'   diff_tension <- summary(pairs(em_tension))
+#'   t_to_d(diff_tension$t.ratio, diff_tension$df)
+#' }
 #' }
 #'
 #' @references
 #' - Friedman, H. (1982). Simplified determinations of statistical power, magnitude of effect and research sample sizes. Educational and Psychological Measurement, 42(2), 521-526. \doi{10.1177/001316448204200214}
 #' - Wolf, F. M. (1986). Meta-analysis: Quantitative methods for research synthesis (Vol. 59). Sage.
-#' - Rosenthal, R. (1991). Meta-analytic procedures for social research. Newbury Park, CA: SAGE Publications, Incorporated.
+#' - Rosenthal, R. (1994) Parametric measures of effect size. In H. Cooper and L.V. Hedges (Eds.). The handbook of research synthesis. New York: Russell Sage Foundation.
 #' - 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.
 #' - Cumming, G., & Finch, S. (2001). A primer on the understanding, use, and calculation of confidence intervals that are based on central and noncentral distributions. Educational and Psychological Measurement, 61(4), 532-574.
 #'
diff --git a/man/d_to_r.Rd b/man/d_to_r.Rd
index 6126252a3..5309db44c 100644
--- a/man/d_to_r.Rd
+++ b/man/d_to_r.Rd
@@ -74,6 +74,7 @@ Enables a conversion between different indices of effect size, such as
 standardized difference (Cohen's d), correlation r or (log) odds ratios.
 }
 \details{
+Conversions between \emph{OR} and \emph{r} is done through these formulae.
 \itemize{
 \item \emph{d to r}: \eqn{d = \frac{2 * r}{\sqrt{1 - r^2}}}
 \item \emph{r to d}: \eqn{r = \frac{d}{\sqrt{d^2 + 4}}}
@@ -81,10 +82,10 @@ standardized difference (Cohen's d), correlation r or (log) odds ratios.
 \item \emph{d to OR}: \eqn{log(OR) = d * \frac{\pi}{\sqrt(3)}}
 }
 
-Conversions between \emph{OR} and \emph{r} is done through these formulae.
 \cr\cr
-When converting \emph{d} to \emph{r}, the resulting \emph{r} is also called the binomial
-effect size display (BESD; Rosenthal et al., 1982).
+The conversion from \emph{d} to \emph{r} assumes equally sized groups. The resulting
+\emph{r} is also called the binomial effect size display (BESD; Rosenthal et al.,
+1982).
 }
 \examples{
 r_to_d(0.5)
diff --git a/man/t_to_r.Rd b/man/t_to_r.Rd
index d00d5d25b..9f09e064a 100644
--- a/man/t_to_r.Rd
+++ b/man/t_to_r.Rd
@@ -53,11 +53,15 @@ These functions use the following formulae to approximate \emph{r} and \emph{d}:
 \cr\cr
 \deqn{r_{partial} = z / \sqrt{z^2 + N}}
 \cr\cr
-\deqn{Cohen's d = 2 * t / \sqrt{df_{error}}}
+\deqn{d = 2 * t / \sqrt{df_{error}}}
 \cr\cr
-\deqn{Cohen's d_z = t / \sqrt{df_{error}}}
+\deqn{d_z = t / \sqrt{df_{error}}}
 \cr\cr
-\deqn{Cohen's d = 2 * z / \sqrt{N}}
+\deqn{d = 2 * z / \sqrt{N}}
+
+The resulting \code{d} effect size is an \emph{approximation} to Cohen's \emph{d}, and
+assumes equal group sizes. When possible, it is advised to directly estimate
+Cohen's \emph{d}, with \code{\link[=cohens_d]{cohens_d()}}, \code{\link[emmeans:eff_size]{emmeans::eff_size()}}, or similar functions.
 }
 \section{Confidence Intervals}{
 Confidence intervals are estimated using the Noncentrality parameter method;
@@ -96,10 +100,12 @@ if (require("correlation")) {
 if (require(emmeans)) {
   warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks)
 
-  conts <- summary(pairs(emmeans(warp.lm,  ~ tension | wool)))
-  t_to_d(conts$t.ratio, conts$df)
-}
 
+  # Also see emmeans::eff_size()
+  em_tension <- emmeans(warp.lm,  ~ tension)#'
+  diff_tension <- summary(pairs(em_tension))
+  t_to_d(diff_tension$t.ratio, diff_tension$df)
+}
 }
 
 }
@@ -107,7 +113,7 @@ if (require(emmeans)) {
 \itemize{
 \item Friedman, H. (1982). Simplified determinations of statistical power, magnitude of effect and research sample sizes. Educational and Psychological Measurement, 42(2), 521-526. \doi{10.1177/001316448204200214}
 \item Wolf, F. M. (1986). Meta-analysis: Quantitative methods for research synthesis (Vol. 59). Sage.
-\item Rosenthal, R. (1991). Meta-analytic procedures for social research. Newbury Park, CA: SAGE Publications, Incorporated.
+\item Rosenthal, R. (1994) Parametric measures of effect size. In H. Cooper and L.V. Hedges (Eds.). The handbook of research synthesis. New York: Russell Sage Foundation.
 \item 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.
 \item Cumming, G., & Finch, S. (2001). A primer on the understanding, use, and calculation of confidence intervals that are based on central and noncentral distributions. Educational and Psychological Measurement, 61(4), 532-574.
 }
diff --git a/vignettes/from_test_statistics.Rmd b/vignettes/from_test_statistics.Rmd
index 8fff8247f..f0e9507d1 100644
--- a/vignettes/from_test_statistics.Rmd
+++ b/vignettes/from_test_statistics.Rmd
@@ -192,15 +192,22 @@ These can be useful in contrast analyses.
 ### Between-Subject Contrasts
 
 ```{r}
-warp.lm <- lm(breaks ~ tension, data = warpbreaks)
+m <- lm(breaks ~ tension, data = warpbreaks)
 
-pairs(emmeans(warp.lm,  ~ tension))
+em_tension <- emmeans(m, ~ tension)
+pairs(em_tension)
 
-t_to_d(t = c(2.5, 3.7, 1.2),
+t_to_d(t = c(2.53, 3.72, 1.20),
        df_error = 51)
+```
+
+However, these are merely approximations of a *true* Cohen's *d*. It is advised to directly estimate Cohen's *d*, whenever possible. For example, here with `emmeans::eff_size()`:
 
+```{r}
+eff_size(em_tension, sigma = sigma(m), edf = df.residual(m))
 ```
 
+
 ### Within-Subject Contrasts
 
 ```{r}
@@ -213,7 +220,7 @@ t_to_d(t = c(-5.7,-5.9,-3.2),
 
 ```
 
-(Note `paired = TRUE` to not over estimate the size of the effect; @rosenthal1991meta; @rosnow2000contrasts)
+(Note set `paired = TRUE` to not over estimate the size of the effect; @rosenthal1991meta; @rosnow2000contrasts)
 
 
 # References