Merge pull request Lakens#77 from Lakens/brunner-munzel

TOSTER version 0.8.0

Author: arcaldwell49

.github/workflows/test-coverage.yaml

@@ -18,9 +18,9 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
 
-      - uses: r-lib/actions/setup-pandoc@v1
+      - uses: r-lib/actions/setup-pandoc@v2
 
       - name: Query dependencies
         run: |

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: TOSTER
-Version: 0.7.1
+Version: 0.8.0
 Title: Two One-Sided Tests (TOST) Equivalence Testing
 Description: Two one-sided tests (TOST) procedure to test equivalence for t-tests, correlations, differences between proportions, and meta-analyses, including power analysis for t-tests and correlations. Allows you to specify equivalence bounds in raw scale units or in terms of effect sizes. See: Lakens (2017) <doi:10.1177/1948550617697177>.
 Authors@R: c(
@@ -13,7 +13,7 @@ Authors@R: c(
 Maintainer: Aaron Caldwell <[email protected]>
 URL: https://aaroncaldwell.us/TOSTERpkg/
 License: GPL-3
-RoxygenNote: 7.2.3
+Roxygen: list(markdown = TRUE)
 Imports:
     stats,
     graphics,
@@ -24,7 +24,8 @@ Imports:
     cowplot,
     tidyr,
     utils,
-    R6
+    R6,
+    lifecycle
 Suggests:
     knitr,
     rmarkdown,
@@ -38,3 +39,4 @@ LazyData: true
 Config/testthat/edition: 3
 Depends: 
     R (>= 3.5)
+RoxygenNote: 7.2.3

NAMESPACE

@@ -6,6 +6,8 @@ S3method(boot_t_TOST,default)
 S3method(boot_t_TOST,formula)
 S3method(boot_t_test,default)
 S3method(boot_t_test,formula)
+S3method(brunner_munzel,default)
+S3method(brunner_munzel,formula)
 S3method(describe,TOSTnp)
 S3method(describe,TOSTt)
 S3method(log_TOST,default)
@@ -39,6 +41,7 @@ export(boot_cor_test)
 export(boot_log_TOST)
 export(boot_t_TOST)
 export(boot_t_test)
+export(brunner_munzel)
 export(compare_cor)
 export(compare_smd)
 export(corsum_test)
@@ -68,12 +71,15 @@ export(powerTOSTtwo.prop)
 export(powerTOSTtwo.raw)
 export(power_eq_f)
 export(power_t_TOST)
+export(power_twoprop)
+export(power_z_cor)
 export(rbs)
 export(ses_calc)
 export(simple_htest)
 export(smd_calc)
 export(t_TOST)
 export(tsum_TOST)
+export(twoprop_test)
 export(wilcox_TOST)
 export(z_cor_test)
 import(R6)
@@ -87,6 +93,7 @@ importFrom(graphics,plot)
 importFrom(graphics,points)
 importFrom(graphics,segments)
 importFrom(graphics,title)
+importFrom(lifecycle,deprecated)
 importFrom(stats,complete.cases)
 importFrom(stats,cor)
 importFrom(stats,density)

NEWS.md

@@ -3,6 +3,15 @@ NEWS
 
 **TOSTER R package and jamovi module**
 
+# TOSTER v0.8.0
+
+- Added Brunner-Munzel test
+- Updated documentation to include lifecycle labels
+- Created new function for two proportions tests (`twoprop_test`)
+  - And power `power_twoprop`
+- Created new function for power for correlations (`power_z_cor`)
+- Deprecated old functions
+
 # TOSTER v0.7.1
 
 - Fixing the ggplot2 error related to `after_stat` update from that package.

R/TOSTER-package.R

@@ -0,0 +1,7 @@
+#' @keywords internal
+"_PACKAGE"
+
+## usethis namespace: start
+#' @importFrom lifecycle deprecated
+## usethis namespace: end
+NULL

R/TOSTmeta.R

@@ -1,4 +1,10 @@
-#' TOST function for meta-analysis
+#' @title TOST function for meta-analysis
+#' @description
+#'
+#' `r lifecycle::badge('stable')`
+#'
+#' A function for providing TOST tests of equivlance from meta-analysis results.
+#'
 #' @param ES meta-analytic effect size
 #' @param var meta-analytic variance
 #' @param se standard error

R/TOSTone.R

@@ -1,10 +1,19 @@
 #' TOST function for a one-sample t-test (Cohen's d)
+#' @description
+#' `r lifecycle::badge('superseded')`
+#'
+#' Development on this function is complete, and for new code we recommend
+#' switching to [tsum_TOST], which is easier to use, more featureful,
+#' and still under active development.
+#'
 #' @param m mean
 #' @param mu value to compare against
 #' @param sd standard deviation
 #' @param n sample size
 #' @param low_eqbound_d lower equivalence bounds (e.g., -0.5) expressed in standardized mean difference (Cohen's d)
 #' @param high_eqbound_d upper equivalence bounds (e.g., 0.5) expressed in standardized mean difference (Cohen's d)
+#' @param low_eqbound lower equivalence bounds (e.g., -0.5) expressed in raw units
+#' @param high_eqbound upper equivalence bounds (e.g., 0.5) expressed in raw units
 #' @param alpha alpha level (default = 0.05)
 #' @param plot set whether results should be plotted (plot = TRUE) or not (plot = FALSE) - defaults to TRUE
 #' @param verbose logical variable indicating whether text output should be generated (verbose = TRUE) or not (verbose = FALSE) - default to TRUE
@@ -18,8 +27,17 @@
 #' @export
 #'
 
-TOSTone<-function(m,mu,sd,n,low_eqbound_d, high_eqbound_d, alpha, plot = TRUE, verbose = TRUE){
-  message("Note: this function is defunct. Please use tsum_TOST instead")
+TOSTone <-
+  function(m,
+           mu,
+           sd,
+           n,
+           low_eqbound_d,
+           high_eqbound_d,
+           alpha,
+           plot = TRUE,
+           verbose = TRUE) {
+    lifecycle::deprecate_soft("0.4.0", "TOSTone()", "tsum_TOST()")
   if(missing(alpha)) {
     alpha<-0.05
   }
@@ -113,3 +131,107 @@ TOSTone<-function(m,mu,sd,n,low_eqbound_d, high_eqbound_d, alpha, plot = TRUE, v
   # Return results in list()
   invisible(list(diff=dif,TOST_t1=t1,TOST_p1=p1,TOST_t2=t2,TOST_p2=p2, TOST_df=degree_f,alpha=alpha,low_eqbound=low_eqbound,high_eqbound=high_eqbound,low_eqbound_d=low_eqbound_d,high_eqbound_d=high_eqbound_d, LL_CI_TOST=LL90,UL_CI_TOST=UL90, LL_CI_TTEST=LL95, UL_CI_TTEST=UL95,NHST_t = t, NHST_p = pttest))
 }
+
+#' @rdname TOSTone
+#' @export
+
+TOSTone.raw <-
+  function(m,
+           mu,
+           sd,
+           n,
+           low_eqbound,
+           high_eqbound,
+           alpha,
+           plot = TRUE,
+           verbose = TRUE) {
+    lifecycle::deprecate_soft("0.4.0", "TOSTone.raw()", "tsum_TOST()")
+    if(missing(alpha)) {
+      alpha<-0.05
+    }
+    if(low_eqbound >= high_eqbound) warning("The lower bound is equal to or larger than the upper bound. Check the plot and output to see if the bounds are specified as you intended.")
+    if(n < 2) stop("The sample size should be larger than 1.")
+    if(1 <= alpha | alpha <= 0) stop("The alpha level should be a positive value between 0 and 1.")
+    if(sd <= 0) stop("The standard deviation should be a positive value.")
+    # Calculate TOST, t-test, 90% CIs and 95% CIs
+    degree_f<-n-1
+    t1<-(m-mu-low_eqbound)/(sd/sqrt(n))# t-test
+    p1<-pt(t1, degree_f, lower.tail=FALSE)
+    t2<-(m-mu-high_eqbound)/(sd/sqrt(n)) #t-test
+    p2<-pt(t2, degree_f, lower.tail=TRUE)
+    t<-(m-mu)/(sd/sqrt(n))
+    pttest<-2*pt(-abs(t), df=degree_f)
+    LL90<-(m-mu)-qt(1-alpha, degree_f)*(sd/sqrt(n))
+    UL90<-(m-mu)+qt(1-alpha, degree_f)*(sd/sqrt(n))
+    LL95<-(m-mu)-qt(1-(alpha/2), degree_f)*(sd/sqrt(n))
+    UL95<-(m-mu)+qt(1-(alpha/2), degree_f)*(sd/sqrt(n))
+    ptost<-max(p1,p2) #Get highest p-value for summary TOST result
+    ttost<-ifelse(abs(t1) < abs(t2), t1, t2) #Get lowest t-value for summary TOST result
+    results<-data.frame(t1,p1,t2,p2,degree_f,LL90,UL90)
+    colnames(results) <- c("t-value 1","p-value 1","t-value 2","p-value 2","df", paste("Lower Limit ",100*(1-alpha*2),"% CI",sep=""),paste("Upper Limit ",100*(1-alpha*2),"% CI",sep=""))
+    dif<-(m-mu)
+    testoutcome<-ifelse(pttest<alpha,"significant","non-significant")
+    TOSToutcome<-ifelse(ptost<alpha,"significant","non-significant")
+
+    # Plot results
+    if (plot == TRUE) {
+      plot(NA, ylim=c(0,1), xlim=c(min(LL95,low_eqbound,dif)-max(UL95-LL95, high_eqbound-low_eqbound,dif)/10, max(UL95,high_eqbound,dif)+max(UL95-LL95, high_eqbound-low_eqbound, dif)/10), bty="l", yaxt="n", ylab="",xlab="Mean Difference")
+      points(x=dif, y=0.5, pch=15, cex=2)
+      abline(v=high_eqbound, lty=2)
+      abline(v=low_eqbound, lty=2)
+      abline(v=0, lty=2, col="grey")
+      segments(LL90,0.5,UL90,0.5, lwd=3)
+      segments(LL95,0.5,UL95,0.5, lwd=1)
+      title(main=paste("Equivalence bounds ",round(low_eqbound,digits=3)," and ",round(high_eqbound,digits=3),"\nMean difference = ",round(dif,digits=3)," \n TOST: ", 100*(1-alpha*2),"% CI [",round(LL90,digits=3),";",round(UL90,digits=3),"] ", TOSToutcome," \n NHST: ", 100*(1-alpha),"% CI [",round(LL95,digits=3),";",round(UL95,digits=3),"] ", testoutcome,sep=""), cex.main=1)
+    }
+
+    if(missing(verbose)) {
+      verbose <- TRUE
+    }
+    if(verbose == TRUE){
+      cat("TOST results:\n")
+      cat("t-value lower bound:",format(t1, digits = 3, nsmall = 2, scientific = FALSE),"\tp-value lower bound:",format(p1, digits = 1, nsmall = 3, scientific = FALSE))
+      cat("\n")
+      cat("t-value upper bound:",format(t2, digits = 3, nsmall = 2, scientific = FALSE),"\tp-value upper bound:",format(p2, digits = 1, nsmall = 3, scientific = FALSE))
+      cat("\n")
+      cat("degrees of freedom :",round(degree_f, digits = 2))
+      cat("\n\n")
+      cat("Equivalence bounds (raw scores):")
+      cat("\n")
+      cat("low eqbound:", paste0(round(low_eqbound, digits = 4)),"\nhigh eqbound:",paste0(round(high_eqbound, digits = 4)))
+      cat("\n\n")
+      cat("TOST confidence interval:")
+      cat("\n")
+      cat("lower bound ",100*(1-alpha*2),"% CI: ", paste0(round(LL90, digits = 3)),"\nupper bound ",100*(1-alpha*2),"% CI:  ",paste0(round(UL90,digits = 3)), sep = "")
+      cat("\n\n")
+      cat("NHST confidence interval:")
+      cat("\n")
+      cat("lower bound ",100*(1-alpha),"% CI: ", paste0(round(LL95, digits = 3)),"\nupper bound ",100*(1-alpha),"% CI:  ",paste0(round(UL95,digits = 3)), sep = "")
+      cat("\n\n")
+      cat("Equivalence Test Result:\n")
+      message(cat("The equivalence test was ",TOSToutcome,", t(",round(degree_f, digits=2),") = ",format(ttost, digits = 3, nsmall = 3, scientific = FALSE),", p = ",format(ptost, digits = 3, nsmall = 3, scientific = FALSE),", given equivalence bounds of ",format(low_eqbound, digits = 3, nsmall = 3, scientific = FALSE)," and ",format(high_eqbound, digits = 3, nsmall = 3, scientific = FALSE)," (on a raw scale) and an alpha of ",alpha,".",sep=""))
+      cat("\n")
+      cat("Null Hypothesis Test Result:\n")
+      message(cat("The null hypothesis test was ",testoutcome,", t(",round(degree_f, digits=2),") = ",format(t, digits = 3, nsmall = 3, scientific = FALSE),", p = ",format(pttest, digits = 3, nsmall = 3, scientific = FALSE),", given an alpha of ",alpha,".",sep=""))
+      if(pttest <= alpha && ptost <= alpha){
+        combined_outcome <- paste0("NHST: reject null significance hypothesis that the effect is equal to ", 0," \n",
+                                   "TOST: reject null equivalence hypothesis")
+      }
+      if(pttest < alpha && ptost > alpha){
+        combined_outcome <- paste0("NHST: reject null significance hypothesis that the effect is equal to ",0," \n",
+                                   "TOST: don't reject null equivalence hypothesis")
+      }
+      if(pttest > alpha && ptost <= alpha){
+        combined_outcome <- paste0("NHST: don't reject null significance hypothesis that the effect is equal to ",0," \n",
+                                   "TOST: reject null equivalence hypothesis")
+      }
+      if(pttest > alpha && ptost > alpha){
+        combined_outcome <-  paste0("NHST: don't reject null significance hypothesis that the effect is equal to ",0," \n",
+                                    "TOST: don't reject null equivalence hypothesis")
+      }
+      cat("\n")
+      message(combined_outcome)
+    }
+    # Return results in list(),NHST_t = t, NHST_p = pttest
+    invisible(list(diff=dif,TOST_t1=t1,TOST_p1=p1,TOST_t2=t2,TOST_p2=p2, TOST_df=degree_f,alpha=alpha,low_eqbound=low_eqbound,high_eqbound=high_eqbound, LL_CI_TOST=LL90,UL_CI_TOST=UL90, LL_CI_TTEST=LL95, UL_CI_TTEST=UL95,NHST_t = t, NHST_p = pttest))
+  }