ggcoefstats {ggstatsplot} | 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.
Although the statistical models displayed in the plot may differ based on the class of models being investigated, there are few aspects of the plot that will be invariant across models:
The dot-whisker plot contains a dot representing the estimate and their confidence intervals (
95%
is the default). The estimate can either be effect sizes (for tests that depend on theF
-statistic) or regression coefficients (for tests witht
-,chi^2
-, andz
-statistic), etc. The function will, by default, display a helpfulx
-axis label that should clear up what estimates are being displayed. The confidence intervals can sometimes be asymmetric if bootstrapping was used.The label attached to dot will provide more details from the statistical test carried out and it will typically contain estimate, statistic, and p-value.
The caption will contain diagnostic information, if available, about models that can be useful for model selection: The smaller the Akaike's Information Criterion (AIC) and the Bayesian Information Criterion (BIC) values, the "better" the model is.
The output of this function will be a
{ggplot2}
object and, thus, it can be further modified (e.g. change themes) with{ggplot2}
.
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 |
statistic |
Relevant statistic for the model ( |
conf.int |
Logical. Decides whether to display confidence intervals as
error bars (Default: |
conf.level |
Numeric deciding level of confidence or credible intervals
(Default: |
digits |
Number of digits for rounding or significant figures. May also
be |
exclude.intercept |
Logical that decides whether the intercept should be
excluded from the plot (Default: |
effectsize.type |
This is the same as |
meta.analytic.effect |
Logical that decides whether subtitle for
meta-analysis via linear (mixed-effects) models (default: |
meta.type |
Type of statistics used to carry out random-effects
meta-analysis. If |
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 |
sort |
If |
xlab |
Label for |
ylab |
Labels for |
title |
The text for the plot title. |
subtitle |
The text for the plot subtitle. The input to this argument
will be ignored if |
caption |
The text for the plot caption. This argument is relevant only
if |
only.significant |
If |
point.args |
A list of additional aesthetic arguments to be passed to
the |
errorbar.args |
Additional arguments that will be passed to
|
vline |
Decides whether to display a vertical line (Default: |
vline.args |
Additional arguments that will be passed to
|
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
|
stats.label.color |
Color for the labels. If set to |
stats.label.args |
Additional arguments that will be passed to
|
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
|
ggtheme |
A |
... |
Additional arguments to tidying method. For more, see
|
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 theinstall_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")