ggstatsplot: ggcoefstats – R documentation

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

ggcoefstats

Dot-and-whisker plots for regression analyses

Description

Plot with the regression coefficients' point estimates as dots with confidence interval whiskers and other statistical details included as labels.

Usage

ggcoefstats(
  x,
  output = "plot",
  statistic = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  k = 2L,
  exclude.intercept = FALSE,
  effsize = "eta",
  meta.analytic.effect = FALSE,
  meta.type = "parametric",
  bf.message = TRUE,
  sort = "none",
  xlab = "regression coefficient",
  ylab = "term",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  only.significant = FALSE,
  point.args = list(size = 3, color = "blue"),
  errorbar.args = list(height = 0),
  vline = TRUE,
  vline.args = list(size = 1, linetype = "dashed"),
  stats.labels = TRUE,
  stats.label.color = NULL,
  stats.label.args = list(size = 3, direction = "y"),
  package = "RColorBrewer",
  palette = "Dark2",
  ggtheme = ggplot2::theme_bw(),
  ggstatsplot.layer = TRUE,
  ...
)

Arguments

`x`	A model object to be tidied, or a tidy data frame containing results from a regression model. Function internally uses `parameters::model_parameters` to get a tidy dataframe. If a data frame is used, it must contain columns named `term` (names of predictors) and `estimate` (corresponding estimates of coefficients or other quantities of interest).
`output`	Character describing the expected output from this function: `"plot"` (visualization of regression coefficients) or `"tidy"` (tidy dataframe of results `parameters::model_parameters`) or `"glance"` (object from `performance::model_performance`).
`statistic`	Which statistic is to be displayed (either `"t"` or `"f"`or `"z"` or `"chi"`) in the label. This is relevant if the `x` argument is a dataframe.
`conf.int`	Logical. Decides whether to display confidence intervals as error bars (Default: `TRUE`).
`conf.level`	Numeric deciding level of confidence or credible intervals (Default: `0.95`).
`k`	Number of digits after decimal point (should be an integer) (Default: `k = 2L`).
`exclude.intercept`	Logical that decides whether the intercept should be excluded from the plot (Default: `FALSE`).
`effsize`	Character describing the effect size to be displayed: `"eta"` (default) or `"omega"`. This argument is relevant only for models objects of class `aov`, `anova`, `aovlist`, `"Gam"`, and `"manova"`.
`meta.analytic.effect`	Logical that decides whether subtitle for meta-analysis via linear (mixed-effects) models (default: `FALSE`). If `TRUE`, input to argument `subtitle` will be ignored. This will be mostly relevant if a data frame with estimates and their standard errors is entered.
`meta.type`	Type of statistics used to carry out random-effects meta-analysis. If `"parametric"` (default), `metafor::rma` function will be used. If `"robust"`, `metaplus::metaplus` function will be used. If `"bayes"`, `metaBMA::meta_random` function will be used.
`bf.message`	Logical that decides whether results from running a Bayesian meta-analysis assuming that the effect size d varies across studies with standard deviation t (i.e., a random-effects analysis) should be displayed in caption. Defaults to `TRUE`.
`sort`	If `"none"` (default) do not sort, `"ascending"` sort by increasing coefficient value, or `"descending"` sort by decreasing coefficient value.
`xlab, ylab`	Labels for `x`- and `y`- axis variables, respectively (Defaults: `"regression coefficient"` and `"term"`).
`title`	The text for the plot title.
`subtitle`	The text for the plot subtitle. The input to this argument will be ignored if `meta.analytic.effect` is set to `TRUE`.
`caption`	The text for the plot caption.
`only.significant`	If `TRUE`, only stats labels for significant effects is shown (Default: `FALSE`). This can be helpful when a large number of regression coefficients are to be displayed in a single plot. Relevant only when the `output` is a plot.
`point.args`	Additional arguments that will be passed to `ggplot2::geom_point` geom. Please see documentation for that function to know more about these arguments.
`errorbar.args`	Additional arguments that will be passed to `ggplot2::geom_errorbarh` geom. Please see documentation for that function to know more about these arguments.
`vline`	Decides whether to display a vertical line (Default: `"TRUE"`).
`vline.args`	Additional arguments that will be passed to `ggplot2::geom_vline` geom. Please see documentation for that function to know more about these arguments.
`stats.labels`	Logical. Decides whether the statistic and p-values for each coefficient are to be attached to each dot as a text label using `ggrepel` (Default: `TRUE`).
`stats.label.color`	Color for the labels. If set to `NULL`, colors will be chosen from the specified `package` (Default: `"RColorBrewer"`) and `palette` (Default: `"Dark2"`).
`stats.label.args`	Additional arguments that will be passed to `ggrepel::geom_label_repel` geom. Please see documentation for that function to know more about these arguments.
`package`	Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running `View(paletteer::palettes_d_names)`.
`palette`	Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running `View(paletteer::palettes_d_names)`.
`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`.
`...`	Additional arguments to tidying method. For more, see `parameters::model_parameters`.

Note

Important: In case you want to carry out meta-analysis using this function, it assumes that you have already downloaded the needed package (metafor, metaplus, or metaBMA) for meta-analysis.

All rows of regression estimates where either of the following quantities is NA will be removed if labels are requested: estimate, statistic, p.value.
Given the rapid pace at which new methods are added to these packages, it is recommended that you install the GitHub versions of parameters and performance in order to make most of this function.

References

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

Examples

# for reproducibility
set.seed(123)
library(ggstatsplot)

# model object
mod <- lm(formula = mpg ~ cyl * am, data = mtcars)

# to get a plot
ggcoefstats(x = mod, output = "plot")

# to get a tidy dataframe
ggcoefstats(x = mod, output = "tidy")

# to get a glance summary
ggcoefstats(x = mod, output = "glance")

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