ggcoefstats.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggcoefstats.R
\name{ggcoefstats}
\alias{ggcoefstats}
\title{Dot-and-whisker plots for regression analyses}
\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{
\item{x}{A model object to be tidied, or a tidy data frame from a regression
model. Function internally uses \code{\link[parameters:model_parameters]{parameters::model_parameters()}} to get a
tidy data frame. If a data frame, it \emph{must} contain at the minimum two
columns named \code{term} (names of predictors) and \code{estimate} (corresponding
estimates of coefficients or other quantities of interest).}

\item{statistic}{Relevant statistic for the model (\code{"t"}, \code{"f"}, \code{"z"}, or
\code{"chi"}) in the label. Relevant only if \code{x} is a \emph{data frame}.}

\item{conf.int}{Logical. Decides whether to display confidence intervals as
error bars (Default: \code{TRUE}).}

\item{conf.level}{Numeric deciding level of confidence or credible intervals
(Default: \code{0.95}).}

\item{digits}{Number of digits for rounding or significant figures. May also
be \code{"signif"} to return significant figures or \code{"scientific"}
to return scientific notation. Control the number of digits by adding the
value as suffix, e.g. \code{digits = "scientific4"} to have scientific
notation with 4 decimal places, or \code{digits = "signif5"} for 5
significant figures (see also \code{\link[=signif]{signif()}}).}

\item{exclude.intercept}{Logical that decides whether the intercept should be
excluded from the plot (Default: \code{FALSE}).}

\item{effectsize.type}{This is the same as \code{es_type} argument of
\code{\link[parameters:model_parameters]{parameters::model_parameters()}}. Defaults to \code{"eta"}, and relevant for
ANOVA-like objects.}

\item{meta.analytic.effect}{Logical that decides whether subtitle for
meta-analysis via linear (mixed-effects) models (default: \code{FALSE}). If
\code{TRUE}, input to argument \code{subtitle} will be ignored. This will be mostly
relevant if a data frame with estimates and their standard errors is
entered.}

\item{meta.type}{Type of statistics used to carry out random-effects
meta-analysis. If \code{"parametric"} (default), \code{\link[metafor:rma.uni]{metafor::rma()}} will be
used. If \code{"robust"}, \code{\link[metaplus:metaplus]{metaplus::metaplus()}} will be used. If \code{"bayes"},
\code{\link[metaBMA:meta_random]{metaBMA::meta_random()}} will be used.}

\item{bf.message}{Logical that decides whether results from running a
Bayesian meta-analysis assuming that the effect size \emph{d} varies across
studies with standard deviation \emph{t} (i.e., a random-effects analysis)
should be displayed in caption. Defaults to \code{TRUE}.}

\item{sort}{If \code{"none"} (default) do not sort, \code{"ascending"} sort by
increasing coefficient value, or \code{"descending"} sort by decreasing
coefficient value.}

\item{xlab}{Label for \code{x} axis variable. If \code{NULL} (default),
variable name for \code{x} will be used.}

\item{ylab}{Labels for \code{y} axis variable. If \code{NULL} (default),
variable name for \code{y} will be used.}

\item{title}{The text for the plot title.}

\item{subtitle}{The text for the plot subtitle. The input to this argument
will be ignored if \code{meta.analytic.effect} is set to \code{TRUE}.}

\item{caption}{The text for the plot caption. This argument is relevant only
if \code{bf.message = FALSE}.}

\item{only.significant}{If \code{TRUE}, only stats labels for significant effects
is shown (Default: \code{FALSE}). This can be helpful when a large number of
regression coefficients are to be displayed in a single plot.}

\item{point.args}{A list of additional aesthetic arguments to be passed to
the \code{\link[ggplot2:geom_point]{ggplot2::geom_point()}}.}

\item{errorbar.args}{Additional arguments that will be passed to
\code{geom_errorbarh()} geom. Please see documentation for that function
to know more about these arguments.}

\item{vline}{Decides whether to display a vertical line (Default: \code{"TRUE"}).}

\item{vline.args}{Additional arguments that will be passed to
\code{geom_vline} geom. Please see documentation for that function to
know more about these arguments.}

\item{stats.labels}{Logical. Decides whether the statistic and \emph{p}-values for
each coefficient are to be attached to each dot as a text label using
\code{{ggrepel}} (Default: \code{TRUE}).}

\item{stats.label.color}{Color for the labels. If set to \code{NULL}, colors will
be chosen from the specified \code{package} (Default: \code{"RColorBrewer"}) and
\code{palette} (Default: \code{"Dark2"}).}

\item{stats.label.args}{Additional arguments that will be passed to
\code{\link[ggrepel:geom_text_repel]{ggrepel::geom_label_repel()}}.}

\item{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
\code{View(paletteer::palettes_d_names)}.}

\item{ggtheme}{A \code{{ggplot2}} theme. Default value is
\code{\link[=theme_ggstatsplot]{theme_ggstatsplot()}}. Any of the \code{{ggplot2}} themes (e.g.,
\code{\link[ggplot2:ggtheme]{ggplot2::theme_bw()}}), or themes from extension packages are allowed
(e.g., \code{ggthemes::theme_fivethirtyeight()}, \code{hrbrthemes::theme_ipsum_ps()},
etc.). But note that sometimes these themes will remove some of the details
that \code{{ggstatsplot}} plots typically contains. For example, if relevant,
\code{\link[=ggbetweenstats]{ggbetweenstats()}} shows details about multiple comparison test as a
label on the secondary Y-axis. Some themes (e.g.
\code{ggthemes::theme_fivethirtyeight()}) will remove the secondary Y-axis and
thus the details as well.}

\item{...}{Additional arguments to tidying method. For more, see
\code{\link[parameters:model_parameters]{parameters::model_parameters()}}.}
}
\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:
\itemize{
\item The dot-whisker plot contains a dot representing the \strong{estimate} and their
\strong{confidence intervals} (\verb{95\%} is the default). The estimate can either be
effect sizes (for tests that depend on the \code{F}-statistic) or regression
coefficients (for tests with \code{t}-, \code{chi^2}-, and \code{z}-statistic), etc. The
function will, by default, display a helpful \code{x}-axis label that should
clear up what estimates are being displayed. The confidence intervals can
sometimes be asymmetric if bootstrapping was used.
\item The label attached to dot will provide more details from the statistical
test carried out and it will typically contain estimate, statistic, and
\emph{p}-value.
\item The caption will contain diagnostic information, if available, about
models that can be useful for model selection: The smaller the Akaike's
Information Criterion (\strong{AIC}) and the Bayesian Information Criterion
(\strong{BIC}) values, the "better" the model is.
\item The output of this function will be a \code{{ggplot2}} object and, thus,
it can be further modified (e.g. change themes) with \code{{ggplot2}}.
}
}
\details{
For details, see:
\url{https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/ggcoefstats.html}
}
\note{
\enumerate{
\item In case you want to carry out meta-analysis, you will be asked to install
the needed packages (\code{{metafor}}, \code{{metaplus}}, or \code{{metaBMA}}) if they are
unavailable.
\item All rows of regression estimates where either of the following
quantities is \code{NA} will be removed if labels are requested:
\code{estimate}, \code{statistic}, \code{p.value}.
\item Given the rapid pace at which new methods are added to these packages, it
is recommended that you install development versions of \code{{easystats}}
packages using the \code{install_latest()} function from \code{{easystats}}.
}
}
\section{Summary of graphics}{
\tabular{lll}{
   graphical element \tab \code{geom} used \tab argument for further modification \cr
   regression estimate \tab \code{ggplot2::geom_point()} \tab \code{point.args} \cr
   error bars \tab \code{ggplot2::geom_errorbarh()} \tab \code{errorbar.args} \cr
   vertical line \tab \code{ggplot2::geom_vline()} \tab \code{vline.args} \cr
   label with statistical details \tab \code{ggrepel::geom_label_repel()} \tab \code{stats.label.args} \cr
}
}

\section{Random-effects meta-analysis}{



The table below provides summary about:
\itemize{
\item statistical test carried out for inferential statistics
\item type of effect size estimate and a measure of uncertainty for this estimate
\item functions used internally to compute these details
}

\strong{Hypothesis testing} and \strong{Effect size estimation}\tabular{llll}{
   Type \tab Test \tab CI available? \tab Function used \cr
   Parametric \tab Pearson's correlation coefficient \tab Yes \tab \code{correlation::correlation()} \cr
   Non-parametric \tab Spearman's rank correlation coefficient \tab Yes \tab \code{correlation::correlation()} \cr
   Robust \tab Winsorized Pearson's correlation coefficient \tab Yes \tab \code{correlation::correlation()} \cr
   Bayesian \tab Bayesian Pearson's correlation coefficient \tab Yes \tab \code{correlation::correlation()} \cr
}

}

\examples{
\dontshow{if (identical(Sys.getenv("NOT_CRAN"), "true") && requireNamespace("lme4", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# 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")
\dontshow{\}) # examplesIf}
}