% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggcoef_model.R
\name{ggcoef_model}
\alias{ggcoef_model}
\alias{ggcoef_table}
\alias{ggcoef_dodged}
\alias{ggcoef_faceted}
\alias{ggcoef_compare}
\alias{ggcoef_plot}
\title{Plot model coefficients}
\usage{
ggcoef_model(
  model,
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  tidy_args = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  exponentiate = FALSE,
  variable_labels = NULL,
  term_labels = NULL,
  interaction_sep = " * ",
  categorical_terms_pattern = "{level}",
  add_reference_rows = TRUE,
  no_reference_row = NULL,
  intercept = FALSE,
  include = dplyr::everything(),
  group_by = broom.helpers::auto_group_by(),
  group_labels = NULL,
  add_pairwise_contrasts = FALSE,
  pairwise_variables = broom.helpers::all_categorical(),
  keep_model_terms = FALSE,
  pairwise_reverse = TRUE,
  emmeans_args = list(),
  significance = 1 - conf.level,
  significance_labels = NULL,
  show_p_values = TRUE,
  signif_stars = TRUE,
  return_data = FALSE,
  ...
)

ggcoef_table(
  model,
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  tidy_args = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  exponentiate = FALSE,
  variable_labels = NULL,
  term_labels = NULL,
  interaction_sep = " * ",
  categorical_terms_pattern = "{level}",
  add_reference_rows = TRUE,
  no_reference_row = NULL,
  intercept = FALSE,
  include = dplyr::everything(),
  group_by = broom.helpers::auto_group_by(),
  group_labels = NULL,
  add_pairwise_contrasts = FALSE,
  pairwise_variables = broom.helpers::all_categorical(),
  keep_model_terms = FALSE,
  pairwise_reverse = TRUE,
  emmeans_args = list(),
  significance = 1 - conf.level,
  significance_labels = NULL,
  show_p_values = FALSE,
  signif_stars = FALSE,
  table_stat = c("estimate", "ci", "p.value"),
  table_header = NULL,
  table_text_size = 3,
  table_stat_label = NULL,
  ci_pattern = "{conf.low}, {conf.high}",
  table_widths = c(3, 2),
  table_witdhs = deprecated(),
  ...
)

ggcoef_dodged(
  model,
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  tidy_args = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  exponentiate = FALSE,
  variable_labels = NULL,
  term_labels = NULL,
  interaction_sep = " * ",
  categorical_terms_pattern = "{level}",
  add_reference_rows = TRUE,
  no_reference_row = NULL,
  intercept = FALSE,
  include = dplyr::everything(),
  group_by = broom.helpers::auto_group_by(),
  group_labels = NULL,
  significance = 1 - conf.level,
  significance_labels = NULL,
  return_data = FALSE,
  ...
)

ggcoef_faceted(
  model,
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  tidy_args = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  exponentiate = FALSE,
  variable_labels = NULL,
  term_labels = NULL,
  interaction_sep = " * ",
  categorical_terms_pattern = "{level}",
  add_reference_rows = TRUE,
  no_reference_row = NULL,
  intercept = FALSE,
  include = dplyr::everything(),
  group_by = broom.helpers::auto_group_by(),
  group_labels = NULL,
  significance = 1 - conf.level,
  significance_labels = NULL,
  return_data = FALSE,
  ...
)

ggcoef_compare(
  models,
  type = c("dodged", "faceted", "table"),
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  tidy_args = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  exponentiate = FALSE,
  variable_labels = NULL,
  term_labels = NULL,
  interaction_sep = " * ",
  categorical_terms_pattern = "{level}",
  add_reference_rows = TRUE,
  no_reference_row = NULL,
  intercept = FALSE,
  include = dplyr::everything(),
  add_pairwise_contrasts = FALSE,
  pairwise_variables = broom.helpers::all_categorical(),
  keep_model_terms = FALSE,
  pairwise_reverse = TRUE,
  emmeans_args = list(),
  significance = 1 - conf.level,
  significance_labels = NULL,
  table_stat = c("estimate", "ci", "p.value"),
  table_header = NULL,
  table_text_size = 3,
  table_stat_label = NULL,
  ci_pattern = "{conf.low}, {conf.high}",
  table_widths = c(3, 2),
  return_data = FALSE,
  ...
)

ggcoef_plot(
  data,
  x = "estimate",
  y = "label",
  exponentiate = FALSE,
  y_labeller = NULL,
  point_size = 2,
  point_stroke = 2,
  point_fill = "white",
  colour = NULL,
  colour_guide = TRUE,
  colour_lab = "",
  colour_labels = ggplot2::waiver(),
  shape = "significance",
  shape_values = c(16, 21),
  shape_guide = TRUE,
  shape_lab = "",
  errorbar = TRUE,
  errorbar_height = 0.1,
  errorbar_coloured = FALSE,
  stripped_rows = TRUE,
  strips_odd = "#11111111",
  strips_even = "#00000000",
  vline = TRUE,
  vline_colour = "grey50",
  dodged = FALSE,
  dodged_width = 0.8,
  facet_row = "var_label",
  facet_col = NULL,
  facet_labeller = "label_value",
  plot_title = NULL,
  x_limits = NULL
)
}
\arguments{
\item{model}{a regression model object}

\item{tidy_fun}{(\code{function})\cr
Option to specify a custom tidier function.}

\item{tidy_args}{Additional arguments passed to
\code{\link[broom.helpers:tidy_plus_plus]{broom.helpers::tidy_plus_plus()}} and to \code{tidy_fun}}

\item{conf.int}{(\code{logical})\cr
Should confidence intervals be computed? (see \code{\link[broom:reexports]{broom::tidy()}})}

\item{conf.level}{the confidence level to use for the confidence
interval if \code{conf.int = TRUE}; must be strictly greater than 0
and less than 1; defaults to 0.95, which corresponds to a 95
percent confidence interval}

\item{exponentiate}{if \code{TRUE} a logarithmic scale will
be used for x-axis}

\item{variable_labels}{(\code{\link[gtsummary:syntax]{formula-list-selector}})\cr
A named list or a named vector of custom variable labels.}

\item{term_labels}{(\code{list} or \code{vector})\cr
A named list or a named vector of custom term labels.}

\item{interaction_sep}{(\code{string})\cr
Separator for interaction terms.}

\item{categorical_terms_pattern}{(\code{\link[glue:glue]{glue pattern}})\cr
A \link[glue:glue]{glue pattern} for labels of categorical terms with treatment
or sum contrasts (see \code{\link[broom.helpers:model_list_terms_levels]{model_list_terms_levels()}}).}

\item{add_reference_rows}{(\code{logical})\cr
Should reference rows be added?}

\item{no_reference_row}{(\code{\link[dplyr:dplyr_tidy_select]{tidy-select}})\cr
Variables for those no reference row should be added,
when \code{add_reference_rows = TRUE}.}

\item{intercept}{(\code{logical})\cr
Should the intercept(s) be included?}

\item{include}{(\code{\link[dplyr:dplyr_tidy_select]{tidy-select}})\cr
Variables to include. Default is \code{everything()}.
See also \code{\link[broom.helpers:all_continuous]{all_continuous()}}, \code{\link[broom.helpers:all_categorical]{all_categorical()}}, \code{\link[broom.helpers:all_dichotomous]{all_dichotomous()}}
and \code{\link[broom.helpers:all_interaction]{all_interaction()}}.}

\item{group_by}{(\code{\link[dplyr:dplyr_tidy_select]{tidy-select}})\cr
One or several variables to group by. Default is \code{auto_group_by()}.
Use \code{NULL} to force ungrouping.}

\item{group_labels}{(\code{string})\cr
An optional named vector of custom term labels.}

\item{add_pairwise_contrasts}{(\code{logical})\cr
Apply \code{\link[broom.helpers:tidy_add_pairwise_contrasts]{tidy_add_pairwise_contrasts()}}?}

\item{pairwise_variables}{(\code{\link[dplyr:dplyr_tidy_select]{tidy-select}})\cr
Variables to add pairwise contrasts.}

\item{keep_model_terms}{(\code{logical})\cr
Keep original model terms for variables where
pairwise contrasts are added? (default is \code{FALSE})}

\item{pairwise_reverse}{(\code{logical})\cr
Determines whether to use \code{"pairwise"} (if \code{TRUE})
or \code{"revpairwise"} (if \code{FALSE}), see \code{\link[emmeans:contrast]{emmeans::contrast()}}.}

\item{emmeans_args}{(\code{list})\cr
List of additional parameter to pass to
\code{\link[emmeans:emmeans]{emmeans::emmeans()}} when computing pairwise contrasts.}

\item{significance}{level (between 0 and 1) below which a
coefficient is consider to be significantly different from 0
(or 1 if \code{exponentiate = TRUE}), \code{NULL} for not highlighting
such coefficients}

\item{significance_labels}{optional vector with custom labels
for significance variable}

\item{show_p_values}{if \code{TRUE}, add p-value to labels}

\item{signif_stars}{if \code{TRUE}, add significant stars to labels}

\item{return_data}{if \code{TRUE}, will return the data.frame used
for plotting instead of the plot}

\item{...}{parameters passed to \code{\link[=ggcoef_plot]{ggcoef_plot()}}}

\item{table_stat}{statistics to display in the table, use any column name
returned by the tidier or \code{"ci"} for confidence intervals formatted
according to \code{ci_pattern}}

\item{table_header}{optional custom headers for the table}

\item{table_text_size}{text size for the table}

\item{table_stat_label}{optional named list of labeller functions for the
displayed statistic (see examples)}

\item{ci_pattern}{glue pattern for confidence intervals in the table}

\item{table_widths}{relative widths of the forest plot and the coefficients
table}

\item{table_witdhs}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}\cr
use \code{table_widths} instead}

\item{models}{named list of models}

\item{type}{a dodged plot, a faceted plot or multiple table plots?}

\item{data}{a data frame containing data to be plotted,
typically the output of \code{ggcoef_model()}, \code{ggcoef_compare()}
or \code{ggcoef_multinom()} with the option \code{return_data = TRUE}}

\item{x, y}{variables mapped to x and y axis}

\item{y_labeller}{optional function to be applied on y labels (see examples)}

\item{point_size}{size of the points}

\item{point_stroke}{thickness of the points}

\item{point_fill}{fill colour for the points}

\item{colour}{optional variable name to be mapped to
colour aesthetic}

\item{colour_guide}{should colour guide be displayed
in the legend?}

\item{colour_lab}{label of the colour aesthetic in the legend}

\item{colour_labels}{labels argument passed to
\code{\link[ggplot2:scale_colour_discrete]{ggplot2::scale_colour_discrete()}} and
\code{\link[ggplot2:discrete_scale]{ggplot2::discrete_scale()}}}

\item{shape}{optional variable name to be mapped to the
shape aesthetic}

\item{shape_values}{values of the different shapes to use in
\code{\link[ggplot2:scale_manual]{ggplot2::scale_shape_manual()}}}

\item{shape_guide}{should shape guide be displayed in the legend?}

\item{shape_lab}{label of the shape aesthetic in the legend}

\item{errorbar}{should error bars be plotted?}

\item{errorbar_height}{height of error bars}

\item{errorbar_coloured}{should error bars be colored as the points?}

\item{stripped_rows}{should stripped rows be displayed in the background?}

\item{strips_odd}{color of the odd rows}

\item{strips_even}{color of the even rows}

\item{vline}{should a vertical line be drawn at 0 (or 1 if
\code{exponentiate = TRUE})?}

\item{vline_colour}{colour of vertical line}

\item{dodged}{should points be dodged (according to the colour aesthetic)?}

\item{dodged_width}{width value for \code{\link[ggplot2:position_dodge]{ggplot2::position_dodge()}}}

\item{facet_row}{variable name to be used for row facets}

\item{facet_col}{optional variable name to be used for column facets}

\item{facet_labeller}{labeller function to be used for labeling facets;
if labels are too long, you can use \code{\link[ggplot2:labellers]{ggplot2::label_wrap_gen()}} (see
examples), more information in the documentation of \code{\link[ggplot2:facet_grid]{ggplot2::facet_grid()}}}

\item{plot_title}{an optional plot title}

\item{x_limits}{optional limits for the x axis}
}
\value{
A \code{ggplot2} plot or a \code{tibble} if \code{return_data = TRUE}.
}
\description{
\code{ggcoef_model()}, \code{ggcoef_table()}, \code{ggcoef_dodged()},
\code{ggcoef_faceted()} and \code{ggcoef_compare()}
use \code{\link[broom.helpers:tidy_plus_plus]{broom.helpers::tidy_plus_plus()}}
to obtain a \code{tibble} of the model coefficients,
apply additional data transformation and then pass the
produced \code{tibble} to \code{ggcoef_plot()} to generate the plot.
}
\details{
For more control, you can use the argument \code{return_data = TRUE} to
get the produced \code{tibble}, apply any transformation of your own and
then pass your customized \code{tibble} to \code{ggcoef_plot()}.
}
\section{Functions}{
\itemize{
\item \code{ggcoef_table()}: a variation of \code{\link[=ggcoef_model]{ggcoef_model()}} adding a table
with estimates, confidence intervals and p-values

\item \code{ggcoef_dodged()}: a dodged variation of \code{\link[=ggcoef_model]{ggcoef_model()}} for
multi groups models

\item \code{ggcoef_faceted()}: a faceted variation of \code{\link[=ggcoef_model]{ggcoef_model()}} for
multi groups models

\item \code{ggcoef_compare()}: designed for displaying several models on the same
plot.

\item \code{ggcoef_plot()}: plot a tidy \code{tibble} of coefficients

}}
\note{
\code{ggcoef_compare(type = "table")} is not compatible with multi-components
models.
}
\examples{
mod <- lm(Sepal.Length ~ Sepal.Width + Species, data = iris)
ggcoef_model(mod)

ggcoef_table(mod)


\donttest{
ggcoef_table(mod, table_stat = c("estimate", "ci"))

ggcoef_table(
  mod,
  table_stat_label = list(
    estimate = scales::label_number(.001)
  )
)

ggcoef_table(mod, table_text_size = 5, table_widths = c(1, 1))

# a logistic regression example
d_titanic <- as.data.frame(Titanic)
d_titanic$Survived <- factor(d_titanic$Survived, c("No", "Yes"))
mod_titanic <- glm(
  Survived ~ Sex * Age + Class,
  weights = Freq,
  data = d_titanic,
  family = binomial
)

# use 'exponentiate = TRUE' to get the Odds Ratio
ggcoef_model(mod_titanic, exponentiate = TRUE)

ggcoef_table(mod_titanic, exponentiate = TRUE)

# display intercepts
ggcoef_model(mod_titanic, exponentiate = TRUE, intercept = TRUE)

# customize terms labels
ggcoef_model(
  mod_titanic,
  exponentiate = TRUE,
  show_p_values = FALSE,
  signif_stars = FALSE,
  add_reference_rows = FALSE,
  categorical_terms_pattern = "{level} (ref: {reference_level})",
  interaction_sep = " x ",
  y_labeller = scales::label_wrap(15)
)

# display only a subset of terms
ggcoef_model(mod_titanic, exponentiate = TRUE, include = c("Age", "Class"))

# do not change points' shape based on significance
ggcoef_model(mod_titanic, exponentiate = TRUE, significance = NULL)

# a black and white version
ggcoef_model(
  mod_titanic,
  exponentiate = TRUE,
  colour = NULL, stripped_rows = FALSE
)

# show dichotomous terms on one row
ggcoef_model(
  mod_titanic,
  exponentiate = TRUE,
  no_reference_row = broom.helpers::all_dichotomous(),
  categorical_terms_pattern =
    "{ifelse(dichotomous, paste0(level, ' / ', reference_level), level)}",
  show_p_values = FALSE
)
}
\dontshow{if (requireNamespace("reshape")) withAutoprint(\{ # examplesIf}

\donttest{
data(tips, package = "reshape")
mod_simple <- lm(tip ~ day + time + total_bill, data = tips)
ggcoef_model(mod_simple)

# custom variable labels
# you can use the labelled package to define variable labels
# before computing model
if (requireNamespace("labelled")) {
  tips_labelled <- tips |>
    labelled::set_variable_labels(
      day = "Day of the week",
      time = "Lunch or Dinner",
      total_bill = "Bill's total"
    )
  mod_labelled <- lm(tip ~ day + time + total_bill, data = tips_labelled)
  ggcoef_model(mod_labelled)
}

# you can provide custom variable labels with 'variable_labels'
ggcoef_model(
  mod_simple,
  variable_labels = c(
    day = "Week day",
    time = "Time (lunch or dinner ?)",
    total_bill = "Total of the bill"
  )
)
# if labels are too long, you can use 'facet_labeller' to wrap them
ggcoef_model(
  mod_simple,
  variable_labels = c(
    day = "Week day",
    time = "Time (lunch or dinner ?)",
    total_bill = "Total of the bill"
  ),
  facet_labeller = ggplot2::label_wrap_gen(10)
)

# do not display variable facets but add colour guide
ggcoef_model(mod_simple, facet_row = NULL, colour_guide = TRUE)

# works also with with polynomial terms
mod_poly <- lm(
  tip ~ poly(total_bill, 3) + day,
  data = tips,
)
ggcoef_model(mod_poly)

# or with different type of contrasts
# for sum contrasts, the value of the reference term is computed
if (requireNamespace("emmeans")) {
  mod2 <- lm(
    tip ~ day + time + sex,
    data = tips,
    contrasts = list(time = contr.sum, day = contr.treatment(4, base = 3))
  )
  ggcoef_model(mod2)
}
}
\dontshow{\}) # examplesIf}
\dontshow{if (requireNamespace("nnet") && requireNamespace("gtsummary")) withAutoprint(\{ # examplesIf}

\donttest{
# multinomial model
mod <- nnet::multinom(grade ~ stage + trt + age, data = gtsummary::trial)
ggcoef_model(mod, exponentiate = TRUE)
ggcoef_table(mod, group_labels = c(II = "Stage 2 vs. 1"))
ggcoef_dodged(mod, exponentiate = TRUE)
ggcoef_faceted(mod, exponentiate = TRUE)
}
\dontshow{\}) # examplesIf}
\dontshow{if (requireNamespace("pscl")) withAutoprint(\{ # examplesIf}
\donttest{
library(pscl)
data("bioChemists", package = "pscl")
mod <- zeroinfl(art ~ fem * mar | fem + mar, data = bioChemists)
ggcoef_model(mod)
ggcoef_table(mod)
ggcoef_dodged(mod)
ggcoef_faceted(
  mod,
  group_labels = c(conditional = "Count", zero_inflated = "Zero-inflated")
)

mod2 <- zeroinfl(art ~ fem + mar | 1, data = bioChemists)
ggcoef_table(mod2)
ggcoef_table(mod2, intercept = TRUE)
}
\dontshow{\}) # examplesIf}
\donttest{
# Use ggcoef_compare() for comparing several models on the same plot
mod1 <- lm(Fertility ~ ., data = swiss)
mod2 <- step(mod1, trace = 0)
mod3 <- lm(Fertility ~ Agriculture + Education * Catholic, data = swiss)
models <- list(
  "Full model" = mod1,
  "Simplified model" = mod2,
  "With interaction" = mod3
)

ggcoef_compare(models)
ggcoef_compare(models, type = "faceted")
ggcoef_compare(models, type = "table")

# you can reverse the vertical position of the point by using a negative
# value for dodged_width (but it will produce some warnings)
ggcoef_compare(models, dodged_width = -.9)
}
}
\seealso{
\code{vignette("ggcoef_model")}
}
