Skip to contents

Create coefficient plots from statistical model output using ggplot2.

Source: R/texreg.R
plotreg.Rd

Create coefficient plots of R regression output using ggplot2.

Usage

plotreg(
  l,
  file = NULL,
  custom.model.names = NULL,
  custom.title = NULL,
  custom.coef.names = NULL,
  custom.coef.map = NULL,
  custom.note = NULL,
  override.coef = 0,
  override.se = 0,
  override.pval = 0,
  override.ci.low = 0,
  override.ci.up = 0,
  override.pvalues = 0,
  omit.coef = NULL,
  reorder.coef = NULL,
  ci.level = 0.95,
  ci.force = FALSE,
  ci.force.level = 0.95,
  ci.test = 0,
  type = "facet",
  theme = NULL,
  signif.light = "#FBC9B9",
  signif.medium = "#F7523A",
  signif.dark = "#BD0017",
  insignif.light = "#C5DBE9",
  insignif.medium = "#5A9ECC",
  insignif.dark = "#1C5BA6",
  ...
)

Arguments

l

A statistical model or a list of statistical models. Lists of models can be specified as l = list(model.1, model.2, ...). Different object types can also be mixed.

file

Using this argument, the resulting table is written to a file rather than to the R prompt. The file name can be specified as a character string. Writing a table to a file can be useful for working with MS Office or LibreOffice. For example, using the htmlreg function, an HTML table can be written to a file with the extension .doc and opened with MS Word. The table can then be simply copied into any Word document, retaining the formatting of the table. Note that LibreOffice can import only plain HTML; CSS decorations are not supported; the resulting tables do not retain the full formatting in LibreOffice.

custom.model.names

A character vector of labels for the models. By default, the models are named "Model 1", "Model 2", etc. Specifying model.names = c("My name 1", "My name 2") etc. overrides the default behavior.

custom.title

With this argument, a replacement text for the ggtitle, which provides a title above the diagram, can be provided. If an empty character object is provided (custom.title = ""), the title will be omitted completely.

custom.coef.names

By default, texreg uses the coefficient names which are stored in the models. The custom.coef.names argument can be used to replace them by other character strings in the order of appearance. For example, if a table shows a total of three different coefficients (including the intercept), the argument custom.coef.names = c("Intercept", "variable 1", "variable 2") will replace their names in this order.

Sometimes it happens that the same variable has a different name in different models. In this case, the user can use this function to assign identical names. If possible, the rows will then be merged into a single row unless both rows contain values in the same column.

Where the argument contains an NA value, the original name of the coefficient is kept. For example, custom.coef.names = c(NA, "age", NA) will only replace the second coefficient name and leave the first and third name as they are in the original model.

See also custom.coef.map for an easier and more comprehensive way to rename, omit, and reorder coefficients.

custom.coef.map

The custom.coef.map argument can be used to select, omit, rename, and reorder coefficients.

Users must supply a named list of this form: list("x" = "First variable", "y" = NA, "z" = "Third variable"). With that particular example of custom.coef.map,

  1. coefficients will be presented in order: "x", "y", "z".

  2. variable "x" will appear as "First variable", variable "y" will appear as "y", and variable "z" will appear as "Third variable".

  3. all variables not named "x", "y", or "z" will be omitted from the table.

custom.note

With this argument, a replacement text for the significance note below the table can be provided. If an empty character object is provided (custom.note = ""), the note will be omitted completely. If some character string is provided (e.g., custom.note = "My note"), the significance legend is replaced by My note. The original significance legend can be included by inserting the %stars wildcard. For example, a custom note can be added right after the significance legend by providing custom.note = "%stars. My note.".

If the threeparttable argument is used, any note should be preceded by "\\item", for example "\\item %stars. \\item Second note. \\item Third note.", and it is possible to create line breaks in the formatted table by including "\\\\" and line breaks in the LaTeX code by including "\n", for example "\n\\item %stars.\\\\\n\\item Second line.\n".

override.coef

Set custom values for the coefficients. New coefficients are provided as a list of numeric vectors. The list contains vectors of coefficients for each model. There must be as many vectors of coefficients as there are models. For example, if there are two models with three model terms each, the argument could be specified as override.coef = list(c(0.1, 0.2, 0.3), c(0.05, 0.06, 0.07)). If there is only one model, custom values can be provided as a plain vector (not embedded in a list). For example: override.coef = c(0.05, 0.06, 0.07).

override.se

Set custom values for the standard errors. New standard errors are provided as a list of numeric vectors. The list contains vectors of standard errors for each model. There must be as many vectors of standard errors as there are models. For example, if there are two models with three coefficients each, the argument could be specified as override.se = list(c(0.1, 0.2, 0.3), c(0.05, 0.06, 0.07)). If there is only one model, custom values can be provided as a plain vector (not embedded in a list).For example: override.se = c(0.05, 0.06, 0.07). Overriding standard errors can be useful for the implementation of robust SEs, for example.

override.pval

Set custom values for the p-values. New p-values are provided as a list of numeric vectors. The list contains vectors of p-values for each model. There must be as many vectors of p-values as there are models. For example, if there are two models with three coefficients each, the argument could be specified as override.pvalues = list(c(0.1, 0.2, 0.3), c(0.05, 0.06, 0.07)). If there is only one model, custom values can be provided as a plain vector (not embedded in a list). For example: override.pvalues = c(0.05, 0.06, 0.07). Overriding p-values can be useful for the implementation of robust SEs and p-values, for example.

override.ci.low

Set custom lower confidence interval bounds. This works like the other override arguments, with one exception: if confidence intervals are provided here and in the override.ci.up argument, the standard errors and p-values as well as the ci.force argument are ignored.

override.ci.up

Set custom upper confidence interval bounds. This works like the other override arguments, with one exception: if confidence intervals are provided here and in the override.ci.low argument, the standard errors and p values as well as the ci.force argument are ignored.

override.pvalues

Set custom values for the p-values. New p-values are provided as a list of numeric vectors. The list contains vectors of p-values for each model. There must be as many vectors of p-values as there are models. For example, if there are two models with three coefficients each, the argument could be specified as override.pvalues = list(c(0.1, 0.2, 0.3), c(0.05, 0.06, 0.07)). If there is only one model, custom values can be provided as a plain vector (not embedded in a list). For example: override.pvalues = c(0.05, 0.06, 0.07). Overriding p-values can be useful for the implementation of robust SEs and p-values, for example.

omit.coef

A character string which is used as a regular expression to remove coefficient rows from the table. For example, omit.coef = "group" deletes all coefficient rows from the table where the name of the coefficient contains the character sequence "group". More complex regular expressions can be used to filter out several kinds of model terms, for example omit.coef = "(thresh)|(ranef)" to remove all model terms matching either "thresh" or "ranef". The omit.coef argument is processed after the custom.coef.names argument, so the regular expression should refer to the custom coefficient names. To omit GOF entries instead of coefficient entries, use the custom arguments of the extract functions instead (see the help entry of the extract function.

reorder.coef

Reorder the rows of the coefficient block of the resulting table in a custom way. The argument takes a vector of the same length as the number of coefficients. For example, if there are three coefficients, reorder.coef = c(3, 2, 1) will put the third coefficient in the first row and the first coefficient in the third row. Reordering can be sensible because interaction effects are often added to the end of the model output although they were specified earlier in the model formula. Note: Reordering takes place after processing custom coefficient names and after omitting coefficients, so the custom.coef.names and omit.coef arguments should follow the original order.

ci.level

If standard errors are converted to confidence intervals (because a model does not natively support CIs), what confidence level should be used for the outer confidence interval? By default, 0.95 is used (i.e., an alpha value of 0.05).

ci.force

Should confidence intervals be used instead of the default standard errors and p-values? Most models implemented in the texreg package report standard errors and p-values by default while few models report confidence intervals. However, the functions in the texreg package can convert standard errors and into confidence intervals using z-scores if desired. To enforce confidence intervals instead of standard errors, the ci.force argument accepts either a logical value indicating whether all models or none of the models should be forced to report confidence intervals (ci.force = TRUE for all and ci.force = FALSE for none) or a vector of logical values indicating for each model separately whether the model should be forced to report confidence intervals (e.g., ci.force = c(FALSE, TRUE, FALSE)). Confidence intervals are computed using the standard normal distribution (z-values based on the qnorm function). The t-distribution is currently not supported because this would require each extract method to have an additional argument for the degrees of freedom.

ci.force.level

If the ci.force argument is used to convert standard errors to confidence intervals, what confidence level should be used? By default, 0.95 is used (i.e., an alpha value of 0.05).

ci.test

If confidence intervals are reported, the ci.test argument specifies the reference value to establish whether a coefficient/CI is significant. The default value ci.test = 0, for example, will display coefficients with a round circle and the red color if the confidence interval does not contain 0. A value of ci.test = 1 could be useful if coefficients are provided on the odds-ratio scale, for example. It is possible to provide a single value for all models or a vector with a separate value for each model (even if it would make the plot hard to read). The ci.test argument works both for models with native support for confidence intervals and in cases where the ci.force argument is used.

type

The default option is type = "facet". If only one model is specified, it will print one forest plot applied to point estimates and confidence intervals. If more than one model is specified, it will print as many facets as the number of models in a column of plots. Alternatively, if type = "forest" is specified, coefficients from one or more models will be grouped together and displayed as a single forest plot.

theme

The theme argument can be used to customize the appearance of the plot. The default theme is theme_bw. It can be replaced by any other ggplot2 theme. See ggtheme for details.

signif.light

Color of outer confidence intervals for significant model terms.

signif.medium

Color of inner confidence intervals for significant model terms.

signif.dark

Color of point estimates and labels for significant model terms.

insignif.light

Color of outer confidence intervals for insignificant model terms.

insignif.medium

Color of inner confidence intervals for insignificant model terms.

insignif.dark

Color of point estimates and labels for insignificant model terms.

...

Custom options to be passed on to the extract function. For example, most extract methods provide custom options for the inclusion or exclusion of specific goodness-of-fit statistics. See the help entries of extract for more information.

Value

Coefficient plot as a ggplot2 gg object if file = FALSE. NULL otherwise.

Details

The plotreg function produces coefficient plots (i.e., forest plots applied to point estimates and confidence intervals) and works much like the screenreg, texreg, htmlreg, matrixreg and wordreg functions. It accepts a single model or multiple statistical models as input and internally extracts the relevant data from the models. If confidence intervals are not defined in the extract method of a statistical model (see extract), the default standard errors are converted to confidence intervals. Most of the arguments work like in the screenreg, texreg, and htmlreg matrixreg, and wordreg functions. It is possible to display the plots in two ways: using the type = "facet" argument, one forest plot applied to point estimates and confidence intervals will be visualized in case there is only one model. If there is more than one model, each one will be plotted next to the other as a separate facet; using the type = "forest" argument, coefficients from one or more models will be grouped together and displayed as a single forest plot.

See also

texreg-package extract texreg matrixreg

Other texreg: htmlreg(), huxtablereg(), knitreg(), matrixreg(), screenreg(), texreg, wordreg()

Author

Claudia Zucca, Philip Leifeld

Examples

if (FALSE) { # \dontrun{
# example from the 'lm' help file:
ctl <- c(4.17, 5.58, 5.18, 6.11, 4.50, 4.61, 5.17, 4.53, 5.33, 5.14)
trt <- c(4.81, 4.17, 4.41, 3.59, 5.87, 3.83, 6.03, 4.89, 4.32, 4.69)
group <- gl(2, 10, 20, labels = c("Ctl", "Trt"))
weight <- c(ctl, trt)
lm.D9 <- lm(weight ~ group)
lm.D90 <- lm(weight ~ group - 1)
plotreg(lm.D9) # plot model output as a diagram

# customize theme and title and save as a PDF file.
plotreg(lm.D9,
        theme = theme_dark(),
        ggtitle = "my title",
        file = "myplot.pdf")
unlink("myplot.pdf")

# group coefficients from multiple models
plotreg(list(lm.D9, lm.D90), type = "forest")
} # }