ggstatsplot: grouped_ggscatterstats – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

grouped_ggscatterstats

Scatterplot with marginal distributions for all levels of a grouping variable

Description

Grouped scatterplots from ggplot2 combined with marginal distribution plots with statistical details added as a subtitle.

Usage

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 colorblind-friendly. `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 colorblind-friendly. `type` A character specifying the type of statistical approach. Four possible options: `"parametric"` `"nonparametric"` `"robust"` `"bayes"` Corresponding abbreviations are also accepted: `"p"` (for parametric), `"np"` (for nonparametric), `"r"` (for robust), or `"bf"` (for 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. `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

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")
)

ggstatsplot

'ggplot2' Based Plots with Statistical Details

v0.7.2

GPL-3 | file LICENSE

Authors

Indrajeet Patil [cre, aut, cph] (<https://orcid.org/0000-0003-1995-6531>, @patilindrajeets)

Initial release