ggcoefstats: Dot-and-whisker plots for regression analyses
In ggstatsplot: 'ggplot2' Based Plots with Statistical Details

ggcoefstats

R Documentation

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,
  statistic = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  digits = 2L,
  exclude.intercept = FALSE,
  effectsize.type = "eta",
  meta.analytic.effect = FALSE,
  meta.type = "parametric",
  bf.message = TRUE,
  sort = "none",
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  only.significant = FALSE,
  point.args = list(size = 3, color = "blue", na.rm = TRUE),
  errorbar.args = list(height = 0, na.rm = TRUE),
  vline = TRUE,
  vline.args = list(linewidth = 1, linetype = "dashed"),
  stats.labels = TRUE,
  stats.label.color = NULL,
  stats.label.args = list(size = 3, direction = "y", min.segment.length = 0, na.rm =
    TRUE),
  package = "RColorBrewer",
  palette = "Dark2",
  ggtheme = ggstatsplot::theme_ggstatsplot(),
  ...
)

Arguments

`x`	A model object to be tidied, or a tidy data frame from a regression model. Function internally uses `parameters::model_parameters()` to get a tidy data frame. If a data frame, it must contain at the minimum two columns named `term` (names of predictors) and `estimate` (corresponding estimates of coefficients or other quantities of interest).
`statistic`	Relevant statistic for the model (`"t"`, `"f"`, `"z"`, or `"chi"`) in the label. Relevant only if `x` is a data frame.
`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`).
`digits`	Number of digits for rounding or significant figures. May also be `"signif"` to return significant figures or `"scientific"` to return scientific notation. Control the number of digits by adding the value as suffix, e.g. `digits = "scientific4"` to have scientific notation with 4 decimal places, or `digits = "signif5"` for 5 significant figures (see also `signif()`).
`exclude.intercept`	Logical that decides whether the intercept should be excluded from the plot (Default: `FALSE`).
`effectsize.type`	This is the same as `es_type` argument of `parameters::model_parameters()`. Defaults to `"eta"`, and relevant for ANOVA-like objects.
`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`	Label for `x` axis variable. If `NULL` (default), variable name for `x` will be used.
`ylab`	Labels for `y` axis variable. If `NULL` (default), variable name for `y` will be used.
`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. This argument is relevant only if `bf.message = FALSE`.
`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.
`point.args`	Additional arguments that will be passed to `geom_point` geom. Please see documentation for that function to know more about these arguments.
`errorbar.args`	Additional arguments that will be passed to `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 `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()`. Please see documentation for that function to know more about these arguments.
`package`, `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 `{ggplot2}` theme. Default value is `ggstatsplot::theme_ggstatsplot()`. Any of the `{ggplot2}` themes (e.g., `theme_bw()`), or themes from extension packages are allowed (e.g., `ggthemes::theme_fivethirtyeight()`, `hrbrthemes::theme_ipsum_ps()`, etc.). But note that sometimes these themes will remove some of the details that `{ggstatsplot}` plots typically contains. For example, if relevant, `ggbetweenstats()` shows details about multiple comparison test as a label on the secondary Y-axis. Some themes (e.g. `ggthemes::theme_fivethirtyeight()`) will remove the secondary Y-axis and thus the details as well.
`...`	Additional arguments to tidying method. For more, see `parameters::model_parameters`.

Details

For details, see: https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/ggcoefstats.html

Summary of graphics

graphical element	`geom` used	argument for further modification
regression estimate	`ggplot2::geom_point()`	`point.args`
error bars	`ggplot2::geom_errorbarh()`	`errorbar.args`
vertical line	`ggplot2::geom_vline()`	`vline.args`
label with statistical details	`ggrepel::geom_label_repel()`	`stats.label.args`

Random-effects meta-analysis

The table below provides summary about:

statistical test carried out for inferential statistics
type of effect size estimate and a measure of uncertainty for this estimate
functions used internally to compute these details

Hypothesis testing and Effect size estimation

Type	Test	CI available?	Function used
Parametric	Pearson's correlation coefficient	Yes	`correlation::correlation()`
Non-parametric	Spearman's rank correlation coefficient	Yes	`correlation::correlation()`
Robust	Winsorized Pearson's correlation coefficient	Yes	`correlation::correlation()`
Bayesian	Bayesian Pearson's correlation coefficient	Yes	`correlation::correlation()`

Note

In case you want to carry out meta-analysis, you will be asked to install the needed packages ({metafor}, {metaplus}, or {metaBMA}) if they are unavailable.
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 development versions of {easystats} packages using the install_latest() function from {easystats}.

Examples


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

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

# creating a plot
p <- ggcoefstats(mod)

# looking at the plot
p

# extracting details from statistical tests
extract_stats(p)

# further arguments can be passed to `parameters::model_parameters()`
ggcoefstats(lmer(Reaction ~ Days + (Days | Subject), sleepstudy), effects = "fixed")

ggstatsplot documentation built on Sept. 11, 2024, 7:48 p.m.