Merge pull request #296 from IndrajeetPatil/interpret_eg

adding interpretation function examples to docs

DESCRIPTION

@@ -73,12 +73,13 @@ Suggests:
     rstantools,
     see,
     testthat,
-    tidyr
+    tidyr,
+    spelling
 Remotes:
     easystats/bayestestR,
     easystats/parameters
-RoxygenNote: 7.1.1
-Language: en-GB
+RoxygenNote: 7.1.1.9000
+Language: en-US
 VignetteBuilder: knitr
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)

R/cohens_d.R

@@ -47,23 +47,45 @@
 #' @family effect size indices
 #'
 #' @examples
-#' cohens_d(sleep$extra, sleep$group)
-#' hedges_g("extra", "group", data = sleep)
 #'
-#' cohens_d(sleep$extra[sleep$group == 1], sleep$extra[sleep$group == 2], paired = TRUE)
+#' # two-sample tests -----------------------
 #'
+#' # using formula interface
 #' cohens_d(mpg ~ am, data = mtcars)
 #' cohens_d(mpg ~ am, data = mtcars, pooled_sd = FALSE)
 #' cohens_d(mpg ~ am, data = mtcars, mu = -5)
 #' hedges_g(mpg ~ am, data = mtcars)
 #' if (require(boot)) glass_delta(mpg ~ am, data = mtcars)
-#'
 #' print(cohens_d(mpg ~ am, data = mtcars), append_CL = TRUE)
+#'
+#' # other acceptable ways to specify arguments
+#' cohens_d(sleep$extra, sleep$group)
+#' hedges_g("extra", "group", data = sleep)
+#' cohens_d(sleep$extra[sleep$group == 1], sleep$extra[sleep$group == 2], paired = TRUE)
+#'
+#' # one-sample tests -----------------------
+#'
+#' cohens_d("wt", data = mtcars, mu = 3)
+#' hedges_g("wt", data = mtcars, mu = 3)
+#'
+#' # interpretation -----------------------
+#'
+#' interpret_d(0.4, rules = "cohen1988")
+#' d_to_common_language(0.4)
+#' interpret_g(0.4, rules = "sawilowsky2009")
+#' interpret_delta(0.4, rules = "gignac2016")
 #' @references
-#' - Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd Ed.). New York: Routledge.
-#' - Hedges, L. V. & Olkin, I. (1985). Statistical methods for meta-analysis. Orlando, FL: Academic Press.
-#' - Hunter, J. E., & Schmidt, F. L. (2004). Methods of meta-analysis: Correcting error and bias in research findings. Sage.
-#' - McGrath, R. E., & Meyer, G. J. (2006). When effect sizes disagree: the case of r and d. Psychological methods, 11(4), 386.
+#' - Cohen, J. (1988). Statistical power analysis for the behavioral
+#' sciences (2nd Ed.). New York: Routledge.
+#'
+#' - Hedges, L. V. & Olkin, I. (1985). Statistical methods for
+#' meta-analysis. Orlando, FL: Academic Press.
+#'
+#' - Hunter, J. E., & Schmidt, F. L. (2004). Methods of meta-analysis:
+#' Correcting error and bias in research findings. Sage.
+#'
+#' - McGrath, R. E., & Meyer, G. J. (2006). When effect sizes disagree: the
+#' case of r and d. Psychological methods, 11(4), 386.
 #'
 #' @importFrom stats var model.frame
 #' @export
@@ -157,7 +179,15 @@ hedges_g <- function(x,
 
 #' @rdname cohens_d
 #' @export
-glass_delta <- function(x, y = NULL, data = NULL, mu = 0, ci = 0.95, iterations = 200, verbose = TRUE, ..., correction) {
+glass_delta <- function(x,
+                        y = NULL,
+                        data = NULL,
+                        mu = 0,
+                        ci = 0.95,
+                        iterations = 200,
+                        verbose = TRUE,
+                        ...,
+                        correction) {
   if (!missing(correction)) {
     warning("`correction` argument is deprecated. To apply bias correction, use `hedges_g()`.",
       call. = FALSE, immediate. = TRUE

R/convert_d_to_common_language.R

@@ -20,9 +20,15 @@
 #' @family convert between effect sizes
 #'
 #' @references
-#' - Cohen, J. (1977). Statistical power analysis for the behavioral sciences. New York: Routledge.
-#' - Reiser, B., & Faraggi, D. (1999). Confidence intervals for the overlapping coefficient: the normal equal variance case. Journal of the Royal Statistical Society, 48(3), 413-418.
-#' - Ruscio, J. (2008). A probability-based measure of effect size: robustness to base rates and other factors. Psychological methods, 13(1), 19–30.
+#' - Cohen, J. (1977). Statistical power analysis for the behavioral sciences.
+#' New York: Routledge.
+#'
+#' - Reiser, B., & Faraggi, D. (1999). Confidence intervals for the overlapping
+#' coefficient: the normal equal variance case. Journal of the Royal Statistical
+#' Society, 48(3), 413-418.
+#'
+#' - Ruscio, J. (2008). A probability-based measure of effect size: robustness
+#' to base rates and other factors. Psychological methods, 13(1), 19–30.
 #'
 #' @export
 #' @importFrom stats pnorm

R/convert_tFz_to_r.R

@@ -1,6 +1,7 @@
 # t -----------------------------------------------------------------------
 
-#' Convert test statistics (t, z, F) to effect sizes of differences (Cohen's d) or association (**partial** r)
+#' Convert test statistics (t, z, F) to effect sizes of differences (Cohen's d)
+#' or association (**partial** r)
 #'
 #' These functions are convenience functions to convert t, z and F test
 #' statistics to Cohen's d and **partial** r. These are useful in cases where
@@ -15,7 +16,7 @@
 #'   (i.e., the residuals).
 #' @param n The number of observations (the sample size).
 #' @param paired Should the estimate account for the t-value being testing the
-#'   difference between dependant means?
+#'   difference between dependent means?
 #' @param pooled Deprecated. Use `paired`.
 #' @inheritParams chisq_to_phi
 #' @param ... Arguments passed to or from other methods.
@@ -83,11 +84,24 @@
 #' }
 #'
 #' @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. (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.
+#' - 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. (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.
 #'
 #' @export
 t_to_r <- function(t, df_error, ci = 0.95, ...) {

R/eta_squared.R

@@ -113,8 +113,12 @@
 #' model0 <- aov(mpg ~ am_f + cyl_f, data = mtcars) # no interaction
 #' cohens_f_squared(model0, model2 = model)
 #'
+#' ## Interpretation of effect sizes
+#' ## -------------------------------------
 #'
-#'
+#' interpret_omega_squared(0.15, rules = "field2013")
+#' interpret_eta_squared(0.15, rules = "cohen1992")
+#' interpret_epsilon_squared(0.15, rules = "cohen1992")
 #'
 #' # Recommended: Type-3 effect sizes + effects coding
 #' # -------------------------------------------------
@@ -181,16 +185,31 @@
 #' }
 #' }
 #'
-#' @return A data frame containing the effect size values and their confidence intervals.
-#'
+#' @return A data frame containing the effect size values and their confidence
+#'   intervals.
 #'
 #' @references
-#' - Albers, C., \& Lakens, D. (2018). When power analyses based on pilot data are biased: Inaccurate effect size estimators and follow-up bias. Journal of experimental social psychology, 74, 187-195.
-#' - Allen, R. (2017). Statistics and Experimental Design for Psychologists: A Model Comparison Approach. World Scientific Publishing Company.
-#' - Carroll, R. M., & Nordholm, L. A. (1975). Sampling Characteristics of Kelley's epsilon and Hays' omega. Educational and Psychological Measurement, 35(3), 541-554.
-#' - Kelley, T. (1935) An unbiased correlation ratio measure. Proceedings of the National Academy of Sciences. 21(9). 554-559.
-#' - Olejnik, S., & Algina, J. (2003). Generalized eta and omega squared statistics: measures of effect size for some common research designs. Psychological methods, 8(4), 434.
-#' - 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.
+#' - Albers, C., \& Lakens, D. (2018). When power analyses based on pilot data
+#' are biased: Inaccurate effect size estimators and follow-up bias. Journal of
+#' experimental social psychology, 74, 187-195.
+#'
+#' - Allen, R. (2017). Statistics and Experimental Design for Psychologists: A
+#' Model Comparison Approach. World Scientific Publishing Company.
+#'
+#' - Carroll, R. M., & Nordholm, L. A. (1975). Sampling Characteristics of
+#' Kelley's epsilon and Hays' omega. Educational and Psychological Measurement,
+#' 35(3), 541-554.
+#'
+#' - Kelley, T. (1935) An unbiased correlation ratio measure. Proceedings of the
+#' National Academy of Sciences. 21(9). 554-559.
+#'
+#' - Olejnik, S., & Algina, J. (2003). Generalized eta and omega squared
+#' statistics: measures of effect size for some common research designs.
+#' Psychological methods, 8(4), 434.
+#'
+#' - 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.
 #'
 #' @export
 eta_squared <- function(model,
@@ -199,7 +218,15 @@ eta_squared <- function(model,
                         ci = 0.9,
                         verbose = TRUE,
                         ...) {
-  out <- .anova_es(model, type = "eta", partial = partial, generalized = generalized, ci = ci, verbose = verbose, ...)
+  out <- .anova_es(
+    model,
+    type = "eta",
+    partial = partial,
+    generalized = generalized,
+    ci = ci,
+    verbose = verbose,
+    ...
+  )
   class(out) <- unique(c("effectsize_table", "see_effectsize_table", class(out)))
   return(out)
 }
@@ -277,7 +304,15 @@ cohens_f <- function(model, partial = TRUE, ci = 0.9, squared = FALSE,
 cohens_f_squared <- function(model, partial = TRUE, ci = 0.9, squared = TRUE,
                              verbose = TRUE,
                              model2 = NULL, ...) {
-  cohens_f(model, partial = partial, ci = ci, squared = squared, verbose = verbose, model2 = model2, ...)
+  cohens_f(
+    model,
+    partial = partial,
+    ci = ci,
+    squared = squared,
+    verbose = verbose,
+    model2 = model2,
+    ...
+  )
 }
 
 

R/interpret_bayesian_indices.R

@@ -29,11 +29,15 @@
 #' interpret_rhat(1.00)
 #' interpret_rhat(c(1.5, 0.9))
 #' @references
-#' \itemize{
-#'   \item Bürkner, P. C. (2017). brms: An R package for Bayesian multilevel models using Stan. Journal of Statistical Software, 80(1), 1-28.
-#'   \item Gelman, A., & Rubin, D. B. (1992). Inference from iterative simulation using multiple sequences. Statistical science, 7(4), 457-472.
-#'   \item Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., & Bürkner, P. C. (2019). Rank-normalization, folding, and localization: An improved Rhat for assessing convergence of MCMC. arXiv preprint arXiv:1903.08008.
-#' }
+#'   - Bürkner, P. C. (2017). brms: An R package for Bayesian multilevel models
+#'   using Stan. Journal of Statistical Software, 80(1), 1-28.
+#'
+#'   - Gelman, A., & Rubin, D. B. (1992). Inference from iterative simulation
+#'   using multiple sequences. Statistical science, 7(4), 457-472.
+#'
+#'   - Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., & Bürkner, P. C.
+#'   (2019). Rank-normalization, folding, and localization: An improved Rhat for
+#'   assessing convergence of MCMC. arXiv preprint arXiv:1903.08008.
 #' @export
 interpret_ess <- function(ess, rules = "burkner2017") {
   rules <- .match.rules(

R/interpret_bf.R

@@ -30,13 +30,24 @@
 #' @examples
 #' interpret_bf(1)
 #' interpret_bf(c(5, 2))
+#'
 #' @references
-#' - Jeffreys, H. (1961), Theory of Probability, 3rd ed., Oxford University Press, Oxford.
-#' - Raftery, A. E. (1995). Bayesian model selection in social research. Sociological methodology, 25, 111-164.
-#' - Jarosz, A. F., & Wiley, J. (2014). What are the odds? A practical guide to computing and reporting Bayes factors. The Journal of Problem Solving, 7(1), 2.
+#' - Jeffreys, H. (1961), Theory of Probability, 3rd ed., Oxford University
+#' Press, Oxford.
+#'
+#' - Raftery, A. E. (1995). Bayesian model selection in social research.
+#' Sociological methodology, 25, 111-164.
+#'
+#' - Jarosz, A. F., & Wiley, J. (2014). What are the odds? A practical guide to
+#' computing and reporting Bayes factors. The Journal of Problem Solving, 7(1),
+#' 2.
 #'
 #' @export
-interpret_bf <- function(bf, rules = "jeffreys1961", include_value = FALSE, protect_ratio = TRUE, exact = TRUE) {
+interpret_bf <- function(bf,
+                         rules = "jeffreys1961",
+                         include_value = FALSE,
+                         protect_ratio = TRUE,
+                         exact = TRUE) {
   match.call()
 
   if (any(bf < 0, na.rm = TRUE)) {