JOSS rev2

R/adjust.R

@@ -1,30 +1,39 @@
 #' Adjust data for the effect of other variable(s)
 #'
-#' This function can be used to adjust the data for the effect of other variables present in the dataset. It is based on an underlying fitting of regressions models, allowing for quite some flexibility, such as including factors as random effects in mixed models (multilevel partialization), continuous variables as smooth terms in general additive models (non-linear partialization) and/or fitting these models under a Bayesian framework. The values returned by this function are the residuals of the regression models. Note that a regular correlation between two "adjusted" variables is equivalent to the partial correlation between them.
+#' This function can be used to adjust the data for the effect of other
+#' variables present in the dataset. It is based on an underlying fitting of
+#' regressions models, allowing for quite some flexibility, such as including
+#' factors as random effects in mixed models (multilevel partialization),
+#' continuous variables as smooth terms in general additive models (non-linear
+#' partialization) and/or fitting these models under a Bayesian framework. The
+#' values returned by this function are the residuals of the regression models.
+#' Note that a regular correlation between two "adjusted" variables is
+#' equivalent to the partial correlation between them.
 #'
 #' @param data A dataframe.
-#' @param effect Character vector of column names to be adjusted for (regressed out). If `NULL` (the default), all variables will be selected.
+#' @param effect Character vector of column names to be adjusted for (regressed
+#'   out). If `NULL` (the default), all variables will be selected.
 #' @inheritParams standardize
-#' @param multilevel If `TRUE`, the factors are included as random factors. Else, if `FALSE` (default), they are included as fixed effects in the simple regression model.
-#' @param additive If `TRUE`, continuous variables as included as smooth terms in additive models. The goal is to regress-out potential non-linear effects.
-#' @param bayesian If `TRUE`, the models are fitted under the Bayesian framework using `rstanarm`.
+#' @param multilevel If `TRUE`, the factors are included as random factors.
+#'   Else, if `FALSE` (default), they are included as fixed effects in the
+#'   simple regression model.
+#' @param additive If `TRUE`, continuous variables as included as smooth terms
+#'   in additive models. The goal is to regress-out potential non-linear
+#'   effects.
+#' @param bayesian If `TRUE`, the models are fitted under the Bayesian framework
+#'   using `rstanarm`.
+#'
+#' @return A data frame comparable to `data`, with adjusted variables.
 #'
 #' @examples
-#' adjust(iris, effect = "Species", select = "Sepal.Length")
+#' adjust(attitude)
+#' adjust(attitude, effect = "complaints", select = "rating")
 #' \donttest{
 #' \dontrun{
-#' adjust(iris, effect = "Species", select = "Sepal.Length", multilevel = TRUE)
-#' adjust(iris, effect = "Species", select = "Sepal.Length", bayesian = TRUE)
-#' adjust(iris, effect = "Petal.Width", select = "Sepal.Length", additive = TRUE)
-#' adjust(iris,
-#'   effect = "Petal.Width", select = "Sepal.Length",
-#'   additive = TRUE, bayesian = TRUE
-#' )
-#' adjust(iris,
-#'   effect = c("Petal.Width", "Species"), select = "Sepal.Length",
-#'   multilevel = TRUE, additive = TRUE
-#' )
-#' adjust(iris)
+#' adjust(attitude, effect = "complaints", select = "rating", bayesian = TRUE)
+#' adjust(attitude, effect = "complaints", select = "rating", additive = TRUE)
+#' attitude$complaints_LMH <- cut(attitude$complaints, 3)
+#' adjust(attitude, effect = "complaints_LMH", select = "rating", multilevel = TRUE)
 #' }
 #' }
 #'

R/change_scale.R

@@ -13,7 +13,7 @@
 #' change_scale(c(0, 1, 5, -5, -2))
 #' change_scale(c(0, 1, 5, -5, -2), to = c(-5, 5))
 #'
-#' head(change_scale(iris))
+#' head(change_scale(trees))
 #' @seealso [normalize()] [standardize()] [ranktransform()]
 #'
 #' @return A rescaled object.

R/cohens_d.R

@@ -35,14 +35,17 @@
 #'
 #' @inheritSection effectsize-CIs Confidence Intervals
 #'
-#' @return A data frame with the effect size(s) and confidence interval(s).
+#' @return A data frame with the effect size ( `Cohens_d`, `Hedges_g`,
+#'   `Glass_delta`) and their CIs (`CI_low` and `CI_high`).
 #'
 #' @seealso [d_to_common_language()] [sd_pooled()]
 #' @family effect size indices
 #'
 #' @examples
-#' cohens_d(iris$Sepal.Length, iris$Sepal.Width)
-#' hedges_g("Sepal.Length", "Sepal.Width", data = iris)
+#' 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)
 #'
 #' cohens_d(mpg ~ am, data = mtcars)
 #' cohens_d(mpg ~ am, data = mtcars, pooled_sd = FALSE)
@@ -51,7 +54,7 @@
 #'
 #' print(cohens_d(mpg ~ am, data = mtcars), append_CL = TRUE)
 #' @references
-#' - Cohen, J. (2013). Statistical power analysis for the behavioral sciences. Routledge.
+#' - 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.

R/convert_OR_to_RR.R

@@ -4,6 +4,8 @@
 #' @param p0 Baseline risk
 #' @inheritParams oddsratio_to_d
 #'
+#' @return Converted index.
+#'
 #' @family convert between effect sizes
 #'
 #' @examples

R/convert_chisq.R

@@ -11,7 +11,8 @@
 #' @param adjust Should the effect size be bias-corrected? Defaults to `FALSE`.
 #' @param ... Arguments passed to or from other methods.
 #'
-#' @return A data frame with the effect size(s) between 0-1, and confidence interval(s).
+#' @return A data frame with the effect size(s) between 0-1, and confidence
+#'   interval(s). See [cramers_v()].
 #'
 #' @details These functions use the following formulae:
 #' \cr

R/convert_d_to_common_language.R

@@ -10,6 +10,8 @@
 #' \cr\cr
 #' \deqn{Pr(superiority) = \Phi(d/\sqrt{2})}
 #'
+#' @return A list of `Cohen's U3`, `Overlap`, `Probability of superiority`.
+#'
 #' @note
 #' These calculations assume that the populations have equal variance and are
 #' normally distributed.
@@ -18,7 +20,7 @@
 #' @family convert between effect sizes
 #'
 #' @references
-#' - Cohen, J. (1977). Statistical power analysis for the behavioral sciencies. Routledge.
+#' - 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.
 #'

R/convert_odds_to_probs.R

@@ -9,6 +9,8 @@
 #' from transformation.
 #' @param ... Arguments passed to or from other methods.
 #'
+#' @return Converted index.
+#'
 #' @seealso [stats::plogis()]
 #' @family convert between effect sizes
 #'

R/convert_tF_to_pve.R

@@ -15,9 +15,12 @@
 #' @inheritParams chisq_to_phi
 #' @param ... Arguments passed to or from other methods.
 #'
-#' @return A data frame with the effect size(s) between 0-1, and confidence interval(s) (Note that for \eqn{\omega_p^2} and \eqn{\epsilon_p^2}
-#' it is possible to compute a negative number; even though this doesn't make any practical sense,
-#' it is recommended to report the negative number and not a 0).
+#' @return A data frame with the effect size(s) between 0-1 (`Eta2_partial`,
+#'   `Epsilon2_partial`, `Omega2_partial`, `Cohens_f_partial` or
+#'   `Cohens_f2_partial`), and their CIs (`CI_low` and `CI_high`). (Note that
+#'   for \eqn{\omega_p^2} and \eqn{\epsilon_p^2} it is possible to compute a
+#'   negative number; even though this doesn't make any practical sense, it is
+#'   recommended to report the negative number and not a 0).
 #'
 #' @details These functions use the following formulae:
 #' \cr

R/convert_tFz_to_r.R

@@ -2,22 +2,27 @@
 
 #' 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 the data required to compute these are not easily
-#' available or their computation is not straightforward (e.g., in liner mixed models, contrasts, etc.).
+#' 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
+#' the data required to compute these are not easily available or their
+#' computation is not straightforward (e.g., in liner mixed models, contrasts,
+#' etc.).
 #' \cr
 #' See [Effect Size from Test Statistics vignette.](https://easystats.github.io/effectsize/articles/from_test_statistics.html)
 #'
 #' @param t,f,z The t, the F or the z statistics.
-#' @param df,df_error Degrees of freedom of numerator or of the error estimate (i.e., the residuals).
+#' @param df,df_error Degrees of freedom of numerator or of the error estimate
+#'   (i.e., the residuals).
 #' @param n The number of observations (the sample size).
-#' @param paired Should the estimate accout for the t-value being testing the difference between dependant means?
+#' @param paired Should the estimate accout for the t-value being testing the
+#'   difference between dependant means?
 #' @param pooled Deprecated. Use `paired`.
 #' @inheritParams chisq_to_phi
 #' @param ... Arguments passed to or from other methods.
 #'
 #'
-#' @return A data frame with the effect size(s) between 0-1, and confidence interval(s)
+#' @return A data frame with the effect size(s)(`r` or `d`), and their CIs
+#'   (`CI_low` and `CI_high`).
 #'
 #'
 #' @details These functions use the following formulae to approximate *r* and *d*:
@@ -52,7 +57,7 @@
 #' t_to_r(t = res$statistic, res$parameter)
 #' \donttest{
 #' ## Linear Regression
-#' model <- lm(Sepal.Length ~ Sepal.Width + Petal.Length, data = iris)
+#' model <- lm(rating  ~ complaints + critical, data = attitude)
 #' library(parameters)
 #' (param_tab <- parameters(model))
 #'
@@ -62,7 +67,7 @@
 #'
 #' # How does this compare to actual partial correlations?
 #' if (require("correlation")) {
-#'   correlation::correlation(iris[, 1:3], partial = TRUE)[1:2, c(2, 3, 7, 8)]
+#'   correlation::correlation(attitude[, c(1, 2, 6)], partial = TRUE)[1:2, c(2, 3, 7, 8)]
 #' }
 #'
 #' ## Use with emmeans based contrasts (see also t_to_eta2)

R/effectsize.R

@@ -24,6 +24,9 @@
 #' **For statistical models it is recommended to directly use the listed
 #' functions, for the full range of options they provide.**
 #'
+#' @return A data frame with the effect size (depending on input) and and its
+#'   CIs (`CI_low` and `CI_high`).
+#'
 #' @family effect size indices
 #'
 #' @examples
@@ -49,7 +52,7 @@
 #'   bf1 <- ttestBF(mtcars$mpg[mtcars$am == 1], mtcars$mpg[mtcars$am == 0])
 #'   effectsize(bf1, test = NULL)
 #'
-#'   bf2 <- correlationBF(iris$Sepal.Length, iris$Sepal.Width)
+#'   bf2 <- correlationBF(attitude$rating, attitude$complaints)
 #'   effectsize(bf2, test = NULL)
 #'
 #'   data(raceDolls)

R/equivalence_test.R

@@ -35,7 +35,7 @@ bayestestR::equivalence_test
 #'
 #' @seealso For more details, see [bayestestR::equivalence_test()].
 #'
-#' @return A data frame.
+#' @return A data frame with the results of the equivalence test.
 #'
 #' @references
 #' - Campbell, H., & Gustafson, P. (2018). Conditional equivalence testing: An alternative remedy for publication bias. PLOS ONE, 13(4), e0195145. https://doi.org/10.1371/journal.pone.0195145

R/eta_squared.R

@@ -24,7 +24,9 @@
 #' @param ... For Bayesian models, passed to `ss_function`. Otherwise ignored.
 #'
 #' @return
-#' A data frame with the effect size(s) and confidence interval(s).
+#' A data frame with the effect size(s) between 0-1 (`Eta2`, `Epsilon2`,
+#' `Omega2`, `Cohens_f` or `Cohens_f2`, possibly with the `partial` or
+#' `generalized` suffix), and their CIs (`CI_low` and `CI_high`).
 #' \cr\cr
 #' For `eta_squared_posterior()`, a data frame containing the ppd of the Eta
 #' squared for each fixed effect, which can then be passed to
@@ -58,6 +60,10 @@
 #' Though Omega is the more popular choice (Albers \& Lakens, 2018), Epsilon is
 #' analogous to adjusted R2 (Allen, 2017, p. 382), and has been found to be less
 #' biased (Carroll & Nordholm, 1975).
+#' \cr\cr
+#' (Note that for \eqn{\omega_p^2} and \eqn{\epsilon_p^2} it is possible to
+#' compute a negative number; even though this doesn't make any practical sense,
+#' it is recommended to report the negative number and not a 0.)
 #'
 #' ## Cohen's f
 #' Cohen's f can take on values between zero, when the population means are all

R/interpret_d.R

@@ -35,7 +35,7 @@
 #' interpret_d(c(.5, .02))
 #' @references
 #' - Gignac, G. E., & Szodorai, E. T. (2016). Effect size guidelines for individual differences researchers. Personality and individual differences, 102, 74-78.
-#' - Cohen, J. (1988). Statistical power analysis for the behavioural sciences.
+#' - Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd Ed.). New York: Routledge.
 #' - Sawilowsky, S. S. (2009). New effect size rules of thumb.
 #'
 #' @export

R/interpret_oddsratio.R

@@ -25,7 +25,7 @@
 #' @aliases interpret_odds
 #'
 #' @references
-#' - Cohen, J. (1988). Statistical power analysis for the behavioural sciences.
+#' - Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd Ed.). New York: Routledge.
 #' - Chen, H., Cohen, P., & Chen, S. (2010). How big is a big odds ratio? Interpreting the magnitudes of odds ratios in epidemiological studies. Communications in Statistics—Simulation and Computation, 39(4), 860-864.
 #' - 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.
 #'

R/interpret_parameters.R

@@ -8,9 +8,6 @@
 #' @param standardize_method See [standardize_parameters()].
 #' @param standardize_robust See [standardize_parameters()].
 #'
-#' @examples
-#' model <- lm(Sepal.Length ~ Species * Petal.Width, data = iris)
-#' interpret_parameters(model)
 #' @export
 interpret_parameters <- function(model, ...) {
   ## ----------------------------- NOTE ---------------------------------------

R/interpret_r.R

@@ -39,7 +39,7 @@
 #' @references
 #' - Funder, D. C., & Ozer, D. J. (2019). Evaluating effect size in psychological research: sense and nonsense. Advances in Methods and Practices in Psychological Science.
 #' - Gignac, G. E., & Szodorai, E. T. (2016). Effect size guidelines for individual differences researchers. Personality and individual differences, 102, 74-78.
-#' - Cohen, J. (1988). Statistical power analysis for the behavioural sciences.
+#' - Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd Ed.). New York: Routledge.
 #' - Evans, J. D. (1996). Straightforward statistics for the behavioral sciences. Thomson Brooks/Cole Publishing Co.
 #'
 #' @export

R/interpret_r2.R

@@ -33,7 +33,7 @@
 #' interpret_r2(.02)
 #' interpret_r2(c(.5, .02))
 #' @references
-#' - Cohen, J. (1988). Statistical power analysis for the behavioural sciences.
+#' - Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd Ed.). New York: Routledge.
 #' - Falk, R. F., & Miller, N. B. (1992). A primer for soft modeling. University of Akron Press.
 #' - Chin, W. W. (1998). The partial least squares approach to structural equation modeling. Modern methods for business research, 295(2), 295-336.
 #' - Hair, J. F., Ringle, C. M., & Sarstedt, M. (2011). PLS-SEM: Indeed a silver bullet. Journal of Marketing theory and Practice, 19(2), 139-152.

R/normalize.R

@@ -18,13 +18,14 @@
 #' normalize(c(0, 1, 5, -5, -2))
 #' normalize(c(0, 1, 5, -5, -2), include_bounds = FALSE)
 #'
-#' head(normalize(iris))
+#' head(normalize(trees))
 #' @references
 #' - Smithson M, Verkuilen J (2006). A Better Lemon Squeezer? Maximum-Likelihood Regression with Beta-Distributed Dependent Variables. Psychological Methods, 11(1), 54–71.
 #'
 #' @family transform utilities
 #'
 #' @return A normalized object.
+#'
 #' @export
 normalize <- function(x, ...) {
   UseMethod("normalize")

R/ranktransform.R

@@ -13,7 +13,8 @@
 #' ranktransform(c(0, 1, 5, -5, -2))
 #' ranktransform(c(0, 1, 5, -5, -2), sign = TRUE)
 #'
-#' head(ranktransform(iris))
+#' head(ranktransform(trees))
+#'
 #' @return A rank-transformed object.
 #'
 #' @family transform utilities

R/sd_pooled.R

@@ -15,9 +15,7 @@ sd_pooled <- function(x, y = NULL, data = NULL) {
 
   # This actually works, you must see if you want to keep this code. If you do,
   # following will work:
-  # sd_pooled(Sepal.Length, Petal.Width, data = iris)
-  # sd_pooled("Sepal.Length", "Petal.Width", data = iris)
-  # sd_pooled(iris$Sepal.Length, iris$Petal.Width)
+  # sd_pooled(mpg, hp, data = mtcars)
   # sd_pooled(x, y) # called from a different function, like cohens_d()
 
   # needs modification in in ".sd_pooled()" as well...

R/standardize.R

@@ -38,10 +38,10 @@
 #'
 #' @examples
 #' # Data frames
-#' summary(standardize(iris))
+#' summary(standardize(swiss))
 #'
 #' # Models
-#' model <- lm(Sepal.Length ~ Species * Petal.Width, data = iris)
+#' model <- lm(Infant.Mortality ~ Education * Fertility, data = swiss)
 #' coef(standardize(model))
 #' @export
 standardize <- function(x, robust = FALSE, two_sd = FALSE, weights = NULL, verbose = TRUE, ...) {

R/standardize_info.R

@@ -6,10 +6,19 @@
 #' @param include_pseudo (For (G)LMMs) Should Pseudo-standardized information be included?
 #' @param ... Arguments passed to or from other methods.
 #'
+#' @return A data frame with information on each parameter (see
+#'   [parameters::parameters_type]), and various standardization coefficients
+#'   for the post-hoc methods (see [standardize_parameters()]) for the predictor
+#'   and the response.
+#'
 #' @family standardize
 #'
 #' @examples
-#' model <- lm(Sepal.Width ~ Sepal.Length * Species, data = iris)
+#' model <- lm(mpg ~ ., data = mtcars)
+#' standardize_info(model)
+#' standardize_info(model, robust = TRUE)
+#' standardize_info(model, two_sd = TRUE)
+#'
 #' @importFrom parameters parameters_type
 #' @export
 standardize_info <- function(model, robust = FALSE, two_sd = FALSE, include_pseudo = FALSE, ...) {