ggstatsplot: ggscatterstats – R documentation

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

ggscatterstats

Scatterplot with marginal distributions and statistical results

Description

Scatterplots from ggplot2 combined with marginal histograms/boxplots/density plots with statistical details added as a subtitle.

Usage

ggscatterstats(
  data,
  x,
  y,
  type = "parametric",
  conf.level = 0.95,
  bf.prior = 0.707,
  bf.message = TRUE,
  tr = 0.2,
  k = 2L,
  results.subtitle = TRUE,
  label.var = NULL,
  label.expression = NULL,
  point.args = list(size = 3, alpha = 0.4),
  point.width.jitter = 0,
  point.height.jitter = 0,
  point.label.args = list(size = 3, max.overlaps = 1e+06),
  smooth.line.args = list(size = 1.5, color = "blue"),
  marginal = TRUE,
  marginal.type = "densigram",
  marginal.size = 5,
  xfill = "#009E73",
  yfill = "#D55E00",
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  ggtheme = ggplot2::theme_bw(),
  ggstatsplot.layer = TRUE,
  ggplot.component = NULL,
  output = "plot",
  ...
)

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`).
`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.
`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`).
`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`).
`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.
`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"`).
`point.args`	A list of additional aesthetic arguments to be passed to `ggplot2::geom_point` geom used to display the raw data points.
`point.width.jitter, 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.
`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.
`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.
`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, 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.
`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.
`title`	The text for the plot title.
`subtitle`	The text for the plot subtitle. Will work only if `results.subtitle = FALSE`.
`caption`	The text for the plot caption.
`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`.
`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.
`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`.
`...`	Currently ignored.

Note

If you set marginal = TRUE, the resulting plot can not be further modified with ggplot2 functions since it is no longer a ggplot object. In case you want a ggplot object, set marginal = FALSE. Also have a look at the ggplot.component argument.
The plot uses ggrepel::geom_label_repel to attempt to keep labels from over-lapping to the largest degree possible. As a consequence plot times will slow down massively (and the plot file will grow in size) if you have a lot of labels that overlap.

References

https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/ggscatterstats.html

Examples

# to get reproducible results from bootstrapping
set.seed(123)
library(ggstatsplot)

# creating dataframe with rownames converted to a new column
mtcars_new <- as_tibble(mtcars, rownames = "car")

# simple function call with the defaults
if (require("ggExtra")) {
  ggscatterstats(
    data = mtcars_new,
    x = wt,
    y = mpg,
    label.var = car,
    label.expression = wt < 4 & mpg < 20,
    # making further customization with `ggplot2` functions
    ggplot.component = list(ggplot2::geom_rug(sides = "b"))
  )
}

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