ggstatsplot (version 0.5.0)

ggcoefstats: Dot-and-whisker plots for regression analyses

Description

Dot-and-whisker plots for regression analyses

Usage

ggcoefstats(
  x,
  output = "plot",
  statistic = NULL,
  bf.message = TRUE,
  effsize = "eta",
  partial = TRUE,
  nboot = 500L,
  meta.analytic.effect = FALSE,
  meta.type = "parametric",
  conf.int = TRUE,
  conf.level = 0.95,
  k = 2,
  exclude.intercept = TRUE,
  exponentiate = FALSE,
  sort = "none",
  xlab = "regression coefficient",
  ylab = "term",
  title = NULL,
  subtitle = NULL,
  only.significant = FALSE,
  caption = NULL,
  caption.summary = TRUE,
  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,
  messages = FALSE,
  ...
)

Arguments

x

A model object to be tidied, or a tidy data frame containing results. If a data frame is to be plotted, it must contain columns named term (names of predictors), or estimate (corresponding estimates of coefficients or other quantities of interest). Other optional columns are conf.low and conf.high (for confidence intervals); p.value. It is important that all term names should be unique. Function internally uses broom::tidy or parameters::model_parameters to get a tidy dataframe.

output

Character describing the expected output from this function: "plot" (visualization of regression coefficients) or "tidy" (tidy dataframe of results from broom::tidy) or "glance" (object from broom::glance) or "augment" (object from broom::augment).

statistic

Which statistic is to be displayed (either "t" or "f"or "z") in the label. This is especially important if the x argument in ggcoefstats is a dataframe in which case the function wouldn't know what kind of model it is dealing with.

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.

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

partial

Logical that decides if partial eta-squared or partial omega-squared are returned (Default: TRUE). If FALSE, eta-squared or omega-squared will be returned.

nboot

Number of bootstrap samples for confidence intervals for partial eta-squared and omega-squared (Default: 500L).

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.

conf.int

Logical. Decides whether to display confidence intervals as error bars (Default: TRUE).

conf.level

Numeric deciding level of confidence intervals (Default: 0.95). For MCMC model objects (Stan, JAGS, etc.), this will be probability level for CI.

k

Number of decimal places expected for results displayed in labels (Default : k = 2).

exclude.intercept

Logical that decides whether the intercept should be excluded from the plot (Default: TRUE).

exponentiate

If TRUE, the x-axis will be logarithmic (Default: FALSE). Note that exponents for the coefficient estimates and associated standard errors plus confidence intervals are computed by the underlying tidying packages (broom/parameters) and not done by ggcoefstats. So this might not work if the underlying packages don't support exponentiation.

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.

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.

caption

Text to display as caption. This argument is relevant only when output = "caption".

caption.summary

Logical that decides whether the model summary should be displayed as a cation to the plot (Default: TRUE). Color of the line segment. Defaults to the same color as the text.

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 stats.label.color is 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 package from which the palette is desired as string or symbol.

palette

Name of palette as string or symbol.

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.

messages

Deprecated. Retained only for backward compatibility.

...

Additional arguments to tidying method.

Value

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

References

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

Examples

# NOT RUN {
# for reproducibility
set.seed(123)

# -------------- with model object --------------------------------------

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

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

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

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

# to get augmented dataframe
ggstatsplot::ggcoefstats(x = mod, output = "augment")

# -------------- with custom dataframe -----------------------------------

# creating a dataframe
df <-
  structure(
    list(
      term = structure(
        c(3L, 4L, 1L, 2L, 5L),
        .Label = c(
          "Africa",
          "Americas", "Asia", "Europe", "Oceania"
        ),
        class = "factor"
      ),
      estimate = c(
        0.382047603321706,
        0.780783111514665,
        0.425607573765058,
        0.558365541235078,
        0.956473848429961
      ),
      std.error = c(
        0.0465576338644502,
        0.0330218199731529,
        0.0362834986178494,
        0.0480571500648261,
        0.062215818388157
      ),
      statistic = c(
        8.20590677855356,
        23.6444603038067,
        11.7300588415607,
        11.6187818146078,
        15.3734833553524
      ),
      conf.low = c(
        0.290515146096969,
        0.715841986960399,
        0.354354575031406,
        0.46379116008131,
        0.827446138277154
      ),
      conf.high = c(
        0.473580060546444,
        0.845724236068931,
        0.496860572498711,
        0.652939922388847,
        1.08550155858277
      ),
      p.value = c(
        3.28679518728519e-15,
        4.04778497135963e-75,
        7.59757330804449e-29,
        5.45155840151592e-26,
        2.99171217913312e-13
      ),
      df.error = c(
        394L, 358L, 622L,
        298L, 22L
      )
    ),
    row.names = c(NA, -5L),
    class = c(
      "tbl_df",
      "tbl", "data.frame"
    )
  )

# plotting the dataframe
ggstatsplot::ggcoefstats(
  x = df,
  statistic = "t",
  meta.analytic.effect = TRUE,
  k = 3
)

# -------------- getting model summary ------------------------------

# model
library(lme4)
lmm1 <- lme4::lmer(
  formula = Reaction ~ Days + (Days | Subject),
  data = sleepstudy
)

# dataframe with model summary
ggstatsplot::ggcoefstats(x = lmm1, output = "glance")
# }