Skip to contents

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,
  k = 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),
  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).

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

effectsize.type

This is the same as effectsize_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.

Note

  1. 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.

  2. All rows of regression estimates where either of the following quantities is NA will be removed if labels are requested: estimate, statistic, p.value.

  3. 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}.

Summary of graphics

graphical elementgeom usedargument for further modification
regression estimateggplot2::geom_point()point.args
error barsggplot2::geom_errorbarh()errorbar.args
vertical lineggplot2::geom_vline()vline.args
label with statistical detailsggrepel::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

TypeTestCI available?Function used
ParametricPearson's correlation coefficientYescorrelation::correlation()
Non-parametricSpearman's rank correlation coefficientYescorrelation::correlation()
RobustWinsorized Pearson correlation coefficientYescorrelation::correlation()
BayesianBayesian Pearson's correlation coefficientYescorrelation::correlation()

Examples

# \donttest{
# for reproducibility
set.seed(123)
library(lme4)
#> Loading required package: Matrix

# 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)
#> $subtitle_data
#> NULL
#> 
#> $caption_data
#> NULL
#> 
#> $pairwise_comparisons_data
#> NULL
#> 
#> $descriptive_data
#> NULL
#> 
#> $one_sample_data
#> NULL
#> 
#> $tidy_data
#> # A tibble: 4 × 11
#>   term  estim…¹ std.e…² conf.…³ conf.…⁴ conf.…⁵ stati…⁶ df.er…⁷  p.value conf.…⁸
#>   <fct>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <int>    <dbl> <chr>  
#> 1 (Int…   30.9    3.19     0.95   24.3   37.4      9.68      28 1.95e-10 Wald   
#> 2 cyl     -1.98   0.449    0.95   -2.89  -1.06    -4.40      28 1.41e- 4 Wald   
#> 3 am      10.2    4.30     0.95    1.36  19.0      2.36      28 2.53e- 2 Wald   
#> 4 cyl:…   -1.31   0.707    0.95   -2.75   0.143   -1.85      28 7.55e- 2 Wald   
#> # … with 1 more variable: expression <list>, and abbreviated variable names
#> #   ¹​estimate, ²​std.error, ³​conf.level, ⁴​conf.low, ⁵​conf.high, ⁶​statistic,
#> #   ⁷​df.error, ⁸​conf.method
#> 
#> $glance_data
#> # A tibble: 1 × 8
#>     AIC  AICc   BIC    R2 R2_adjusted  RMSE Sigma expression  
#>   <dbl> <dbl> <dbl> <dbl>       <dbl> <dbl> <dbl> <list>      
#> 1  166.  168.  173. 0.785       0.762  2.75  2.94 <expression>
#> 

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

# }