Grouped scatterplots from ggplot2
combined with marginal distribution plots
with statistical details added as a subtitle.
grouped_ggscatterstats(
data,
x,
y,
grouping.var,
label.var = NULL,
label.expression = NULL,
output = "plot",
plotgrid.args = list(),
annotation.args = list(),
...
)
Arguments
data 
A dataframe (or a tibble) from which variables specified are to
be taken. Other data types (e.g., matrix,table, array, etc.) will not
be accepted. 
x 
The column in data containing the explanatory variable to be
plotted on the x axis. Can be entered either as a character string (e.g.,
"x" ) or as a bare expression (e.g, x ). 
y 
The column in data containing the response (outcome) variable to
be plotted on the y axis. Can be entered either as a character string
(e.g., "y" ) or as a bare expression (e.g, y ). 
grouping.var 
A single grouping variable (can be entered either as a
bare name x or as a string "x" ). 
label.var 
Variable to use for points labels. Can be entered either as
a bare expression (e.g, var1 ) or as a string (e.g., "var1" ). 
label.expression 
An expression evaluating to a logical vector that
determines the subset of data points to label. This argument can be entered
either as a bare expression (e.g., y < 4 & z < 20 ) or as a string (e.g.,
"y < 4 & z < 20" ). 
output 
Character that describes what is to be returned: can be
"plot" (default) or "subtitle" or "caption" . Setting this to
"subtitle" will return the expression containing statistical results. If
you have set results.subtitle = FALSE , then this will return a NULL .
Setting this to "caption" will return the expression containing details
about Bayes Factor analysis, but valid only when type = "parametric" and
bf.message = TRUE , otherwise this will return a NULL . 
plotgrid.args 
A list of additional arguments passed to
patchwork::wrap_plots , except for guides argument which is already
separately specified here. 
annotation.args 
A list of additional arguments passed to
patchwork::plot_annotation . 
... 
Arguments passed on to ggscatterstats
point.label.args A list of additional aesthetic arguments to be passed
to ggrepel::geom_label_repel geom used to display the labels.
smooth.line.args A list of additional aesthetic arguments to be passed
to ggplot2::geom_smooth geom used to display the regression line.
point.args A list of additional aesthetic arguments to be passed
to ggplot2::geom_point geom used to display the raw data points.
marginal Decides whether marginal distributions will be plotted on
axes using ggExtra::ggMarginal() . The default is TRUE . The package
ggExtra must already be installed by the user.
point.width.jitter Degree of jitter in x and y
direction, respectively. Defaults to 0 (0%) of the resolution of the
data. Note that the jitter should not be specified in the point.args
because this information will be passed to two different geom s: one
displaying the points and the other displaying the *labels for
these points.
point.height.jitter Degree of jitter in x and y
direction, respectively. Defaults to 0 (0%) of the resolution of the
data. Note that the jitter should not be specified in the point.args
because this information will be passed to two different geom s: one
displaying the points and the other displaying the *labels for
these points.
marginal.type Type of marginal distribution to be plotted on the axes
("histogram" , "boxplot" , "density" , "violin" , "densigram" ).
marginal.size Integer describing the relative size of the marginal
plots compared to the main plot. A size of 5 means that the main plot is
5x wider and 5x taller than the marginal plots.
xfill Character describing color fill for x and y axes
marginal distributions (default: "#009E73" (for x ) and "#D55E00" (for
y )). Note that the defaults are colorblindfriendly.
yfill Character describing color fill for x and y axes
marginal distributions (default: "#009E73" (for x ) and "#D55E00" (for
y )). Note that the defaults are colorblindfriendly.
type A character specifying the type of statistical approach:
"parametric"
"nonparametric"
"robust"
"bayes"
This argument also accepts the following abbreviations: "p" (for
parametric), "np" (for nonparametric), "r" (for robust), "bf"
(for Bayes Factor or Bayesian).
conf.level Scalar between 0 and 1 . If unspecified, the defaults
return 95% confidence/credible intervals (0.95 ).
bf.prior A number between 0.5 and 2 (default 0.707 ), the prior
width to use in calculating Bayes factors and posterior estimates. In
addition to numeric arguments, several named values are also recognized:
"medium" , "wide" , and "ultrawide" , corresponding to r scale values
of 1/2, sqrt(2)/2, and 1, respectively. In case of an ANOVA, this value
corresponds to scale for fixed effects.
tr Trim level for the mean when carrying out robust tests. In case
of an error, try reducing the value of tr , which is by default set to
0.2 . Lowering the value might help.
k Number of digits after decimal point (should be an integer)
(Default: k = 2L ).
ggtheme A function, ggplot2 theme name. Default value is
ggplot2::theme_bw() . Any of the ggplot2 themes, or themes from
extension packages are allowed (e.g., ggthemes::theme_fivethirtyeight() ,
hrbrthemes::theme_ipsum_ps() , etc.).
ggstatsplot.layer Logical that decides whether theme_ggstatsplot
theme elements are to be displayed along with the selected ggtheme
(Default: TRUE ). theme_ggstatsplot is an opinionated theme layer that
override some aspects of the selected ggtheme .
bf.message Logical that decides whether to display Bayes Factor in
favor of the null hypothesis. This argument is relevant only for
parametric test (Default: TRUE ).
results.subtitle Decides whether the results of statistical tests are
to be displayed as a subtitle (Default: TRUE ). If set to FALSE , only
the plot will be returned.
xlab Labels for x and y axis variables. If NULL (default),
variable names for x and y will be used.
ylab Labels for x and y axis variables. If NULL (default),
variable names for x and y will be used.
subtitle The text for the plot subtitle. Will work only if
results.subtitle = FALSE .
caption The text for the plot caption.
ggplot.component A ggplot component to be added to the plot prepared
by ggstatsplot . This argument is primarily helpful for grouped_
variants of all primary functions. Default is NULL . The argument should
be entered as a ggplot2 function or a list of ggplot2 functions.

References
https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/ggscatterstats.html
See also
Examples
# to ensure reproducibility
set.seed(123)
library(ggstatsplot)
# skipping marginal distributions so that the examples run fast
# basic function call
grouped_ggscatterstats(
data = dplyr::filter(movies_long, genre == "Comedy"  genre == "Drama"),
x = length,
y = rating,
type = "robust",
grouping.var = genre,
marginal = FALSE,
ggplot.component = list(ggplot2::geom_rug(sides = "b"))
)
# using labeling
# (also show how to modify basic plot from within function call)
grouped_ggscatterstats(
data = dplyr::filter(ggplot2::mpg, cyl != 5),
x = displ,
y = hwy,
grouping.var = cyl,
type = "robust",
marginal = FALSE,
label.var = manufacturer,
label.expression = hwy > 25 & displ > 2.5,
ggplot.component = ggplot2::scale_y_continuous(sec.axis = ggplot2::dup_axis())
)
# labeling without expression
grouped_ggscatterstats(
data = dplyr::filter(
.data = movies_long,
rating == 7,
genre %in% c("Drama", "Comedy")
),
x = budget,
y = length,
grouping.var = genre,
bf.message = FALSE,
label.var = "title",
marginal = FALSE,
annotation.args = list(tag_levels = "a")
)