Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JOSS rev2 #228

Merged
merged 13 commits into from
Dec 10, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 27 additions & 18 deletions R/adjust.R
Original file line number Diff line number Diff line change
@@ -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)
#' }
#' }
#'
Expand Down
2 changes: 1 addition & 1 deletion R/change_scale.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
11 changes: 7 additions & 4 deletions R/cohens_d.R
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions R/convert_OR_to_RR.R
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
#' @param p0 Baseline risk
#' @inheritParams oddsratio_to_d
#'
#' @return Converted index.
#'
#' @family convert between effect sizes
#'
#' @examples
Expand Down
3 changes: 2 additions & 1 deletion R/convert_chisq.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion R/convert_d_to_common_language.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
#'
Expand Down
2 changes: 2 additions & 0 deletions R/convert_odds_to_probs.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
#'
Expand Down
9 changes: 6 additions & 3 deletions R/convert_tF_to_pve.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 13 additions & 8 deletions R/convert_tFz_to_r.R
Original file line number Diff line number Diff line change
Expand Up @@ -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*:
Expand Down Expand Up @@ -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))
#'
Expand All @@ -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)
Expand Down
5 changes: 4 additions & 1 deletion R/effectsize.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion R/equivalence_test.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 7 additions & 1 deletion R/eta_squared.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion R/interpret_d.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion R/interpret_oddsratio.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
#'
Expand Down
3 changes: 0 additions & 3 deletions R/interpret_parameters.R
Original file line number Diff line number Diff line change
Expand Up @@ -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 ---------------------------------------
Expand Down
2 changes: 1 addition & 1 deletion R/interpret_r.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion R/interpret_r2.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion R/normalize.R
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
3 changes: 2 additions & 1 deletion R/ranktransform.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 1 addition & 3 deletions R/sd_pooled.R
Original file line number Diff line number Diff line change
Expand Up @@ -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...
Expand Down
4 changes: 2 additions & 2 deletions R/standardize.R
Original file line number Diff line number Diff line change
Expand Up @@ -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, ...) {
Expand Down
11 changes: 10 additions & 1 deletion R/standardize_info.R
Original file line number Diff line number Diff line change
Expand Up @@ -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, ...) {
Expand Down
Loading