Box-Violin Plots to Compare Between Groups

Wrapper Function for ggstatsplot::ggbetweenstats and ggstatsplot::grouped_ggbetweenstats to generate Box-Violin Plots for comparing continuous variables between groups with statistical annotations.

Usage

jjbetweenstats(
  data,
  dep,
  group,
  grvar = NULL,
  centralityplotting = FALSE,
  centralitytype = "parametric",
  typestatistics = "parametric",
  pairwisecomparisons = FALSE,
  pairwisedisplay = "significant",
  padjustmethod = "holm",
  effsizetype = "biased",
  mytitle = "Between Group Comparison",
  xtitle = "",
  ytitle = "",
  originaltheme = FALSE,
  resultssubtitle = FALSE,
  bfmessage = FALSE,
  k = 2,
  conflevel = 0.95,
  varequal = FALSE,
  multiEndpointCorrection = "none",
  plotwidth = 650,
  plotheight = 450,
  colorblindSafe = FALSE,
  showexplanations = FALSE,
  addGGPubrPlot = FALSE,
  ggpubrPlotType = "boxplot",
  ggpubrPalette = "jco",
  ggpubrAddStats = TRUE,
  ggpubrAddPoints = FALSE
)

Arguments

data

The data as a data frame.

dep

.

group

.

grvar

.

centralityplotting

.

centralitytype

.

typestatistics

.

pairwisecomparisons

.

pairwisedisplay

.

padjustmethod

.

effsizetype

.

mytitle

.

xtitle

.

ytitle

.

originaltheme

.

resultssubtitle

.

bfmessage

Whether to display Bayes Factor in the subtitle when using Bayesian analysis.

k

Number of decimal places for displaying statistics in the subtitle.

conflevel

Confidence level for confidence intervals.

varequal

Whether to assume equal variances across groups for parametric tests.

multiEndpointCorrection

Display guidance for multiple testing correction when analyzing multiple dependent variables. IMPORTANT: This option does NOT automatically adjust p-values. It provides instructions for manual correction. When testing multiple endpoints (e.g., cholesterol, glucose, triglycerides), the family-wise error rate increases. For example, testing 3 variables at alpha=0.05 gives actual error rate of ~14\ a correction method to see step-by-step instructions for manually applying that correction to the p-values shown in the plots.

plotwidth

Width of the plot in pixels. Default is 650.

plotheight

Height of the plot in pixels. Default is 450.

colorblindSafe

Whether to use colorblind-safe color palette for plot elements.

showexplanations

Display additional explanatory content including about section, summary, assumptions, interpretation guide, and copy-ready report template.

addGGPubrPlot

Add publication-ready plot using ggpubr package. This provides an alternative visualization with publication-quality aesthetics.

ggpubrPlotType

Type of ggpubr plot to display when addGGPubrPlot is enabled.

ggpubrPalette

Color palette for ggpubr plot.

ggpubrAddStats

Add statistical comparison p-values to ggpubr plot.

ggpubrAddPoints

Overlay individual data points on ggpubr plot.

Value

A results object containing:

results$todo					a html
results$about					a html
results$summary					a html
results$assumptions					a html
results$interpretation					a html
results$report					a html
results$plot2					an image
results$plot					an image
results$ggpubrPlot					an image
results$ggpubrPlot2					an image

Examples

# Basic comparison between groups
jjbetweenstats(
    data = iris,
    dep = "Sepal.Length",
    group = "Species",
    typestatistics = "parametric",
    pairwisecomparisons = TRUE
)
#> 
#>  BOX-VIOLIN PLOTS TO COMPARE BETWEEN GROUPS
#> 
#>  Violin plot analysis comparing Sepal.Length by Species.


# Multiple variables comparison
jjbetweenstats(
    data = mtcars,
    dep = c("mpg", "hp", "wt"),
    group = "cyl",
    typestatistics = "nonparametric",
    pairwisecomparisons = TRUE,
    pairwisedisplay = "significant",
    padjustmethod = "bonferroni"
)
#> 
#>  BOX-VIOLIN PLOTS TO COMPARE BETWEEN GROUPS
#> 
#>  Violin plot analysis comparing mpg, hp, wt by cyl.
#> Error in purrr::pmap(.l = list(y = dep2_symbols, messages = FALSE), .f = function(y,     messages) {    plot_args <- list(data = mydata, x = rlang::sym(group), y = !!y,         messages = messages, title = opts$mytitle, xlab = opts$xtitle,         ylab = opts$ytitle, type = opts$typestatistics, pairwise.comparisons = opts$pairwisecomparisons,         pairwise.display = opts$pairwisedisplay, p.adjust.method = opts$padjustmethod,         effsize.type = opts$effsizetype, bf.message = opts$bfmessage,         k = opts$k, conf.level = opts$conflevel, var.equal = opts$varequal,         point.args = opts$pointargs, results.subtitle = opts$resultssubtitle,         centrality.plotting = if (!is.null(opts$centrality.plotting)) opts$centrality.plotting else FALSE,         centrality.type = if (!is.null(opts$centrality.type)) opts$centrality.type else NULL)    if (!is.null(opts$violinargs)) {        plot_args$violin.args <- opts$violinargs    }    if (!is.null(opts$boxplotargs)) {        plot_args$boxplot.args <- opts$boxplotargs    }    do.call(ggstatsplot::ggbetweenstats, plot_args)}): ℹ In index: 1.
#> Caused by error in `!y`:
#> ! invalid argument type

# Grouped analysis with split variable
jjbetweenstats(
    data = mtcars,
    dep = "mpg",
    group = "cyl",
    grvar = "am",
    typestatistics = "robust",
    centralityplotting = TRUE,
    centralitytype = "robust",
)
#> 
#>  BOX-VIOLIN PLOTS TO COMPARE BETWEEN GROUPS
#> 
#>  Violin plot analysis comparing mpg by cyl, grouped by am.



# Bayesian analysis with custom aesthetics
jjbetweenstats(
    data = ToothGrowth,
    dep = "len",
    group = "supp",
    grvar = "dose",
    typestatistics = "bayes",
    bfmessage = TRUE,
    mytitle = "Tooth Growth by Supplement Type",
    xtitle = "Supplement",
    ytitle = "Tooth Length"
)
#> 
#>  BOX-VIOLIN PLOTS TO COMPARE BETWEEN GROUPS
#> 
#>  Violin plot analysis comparing len by supp, grouped by dose.