ggeffects - Estimated Marginal Means and Adjusted Predictions from Regression Models<img src="man/figures/logo.png" align="right" />

Lüdecke D (2018). ggeffects: Tidy Data Frames of Marginal Effects from Regression Models. Journal of Open Source Software, 3(26), 772. doi: 10.21105/joss.00772

Maintenance mode

Package ggeffects is in maintenance mode and will be superseded by the modelbased-package from the easystats-project.

The main reason is to reduce double maintenance burden for me. We have largely revised the modelbased package, adding many new features, revising the plotting capabilities, and last not least we added full support for the marginaleffects package as (defaul) backend for estimating marginal means, effects and contrasts.

ggeffects, which has a pretty stable predict_response() function to calculate adjusted predictions for many, many models, and which has very matured plotting capabilities, lately got a test_prediction() function to calculate contrasts and pairwise comparisons, too, also built on top of marginaleffects. Effectively, there are now two packages I’m involved with very similar tasks and functionality. However, marginaleffects is undergoing substantial changes right now, meaning I had to re-write a lot of code in test_predictions() to make it work again (test_predictions() is still available, relying on the emmeans package, and hence no longer that feature-rich as it was before). Therefore, I decided to remove all functionality that relied on marginaleffects, and focussing on modelbased instead, to reduce maintenance burden for me.

modelbased is easier to maintain, because it was written lateley, with more package development experience on our side. Furthermore, it has a clear and intuitive user interface and is pretty stable and finished right now. It also offers some features that ggeffects has not included, like estimating marginal effects (and not only adjusted predictions or marginal means). Thus, future development of new features will happen in modelbased. ggeffects will still be maintained, i.e. bugs will be fixed if possible, and maybe smaller new features will be added.

Your code using functions like predict_response(), ggpredict() or plot() will still work, will still work in the future and there will be no limitations regarding functionality for those functions! If you only used these functions, there is no reason to worry or to change anything! However, to leverage the full power of predictions, including contrasts and pairwise comparisons or calculating marginal effects, the recommendation is to switch to modelbased-package!

Why do we need (marginal/conditional) effects or (adjusted) predicted values?

After fitting a model, it is useful generate model-based estimates (expected values, or adjusted predictions) of the response variable for different combinations of predictor values. Such estimates can be used to make inferences about relationships between variables - adjusted predictions tell you: what is the expected ouctome for certain values or levels of my predictors?

Adjusted predictions or marginal means are often easier to understand than raw regression coefficients. In particular, their visualization allows to intuitively get the idea of how predictors and outcome are associated, even for complex models.

Aims of this package

ggeffects is a light-weight package that aims at easily calculating adjusted predictions and estimated marginal means at meaningful values of covariates from statistical models. Furthermore, it is possible to compute contrasts or pairwise comparisons, to test predictions and differences in predictions for statistical significance. Finally, you can easily produce nice figures to visualize the results.

What you basically would need for your workflow is:

• predict_response() (understand your results)
• test_predictions() (check for “significant” results)
• plot() (communicate your results)

Three core ideas describe the philosophy of the function design and help users to achieve the above mentioned goals:

1. Functions are type-safe and always return a data frame with the same, consistent structure;

2. there is a simple, unique approach to calculate adjusted predictions and estimated marginal means for many different models;

3. the package supports “labelled data” (Lüdecke 2018), which allows human readable annotations for graphical outputs.

This means, users do not need to care about any expensive steps after modeling to visualize the results. The returned as data frame is ready to use with the ggplot2-package, however, there is also a plot()-method to easily create publication-ready figures.

Adjusted predictions or estimated marginal means are always calculated on the response scale, which is the easiest and most intuitive scale to interpret the results.

It is easy to start, you just need one function: predict_response(), and two arguments: the model and the “focal terms”, i.e. the predictors that you are mainly interested in. Examples are shown below.

So, when do I need the ggeffects package?

You should use ggeffects…

• … when you want to understand how predictors and outcome are related, no matter whether you have simple or complex models, interaction or transformed terms. See how to start in this vignette. The syntax for the ggeffects functions is super easy and consistent across the different type of models and complexity.

• … when you want to perform pairwise comparisons, in order to see whether there are statistically significant differences in the association of, for instance, different groups or categories of your predictors and your outcome (“effects”, or sometimes “marginal effects”).

• … when you need impressive figures instead of long, confusing tables to describe your results. There are several examples in the documentation, for example this vignette.

• … and even when you want to check, whether your model appropriately describes your data. See this vignette to learn more about how to use ggeffects for model diagnostics.

A workflow in R would then include using following functions in this order: predict_response(), plot(), and test_predictions() - that’s all you need! See also this example workflow using logistic regression.

Installation

| Type | Source | Command | |----|----|----| | Release | CRAN | install.packages("ggeffects") | | Development | r - universe | install.packages("ggeffects", repos = "https://strengejacke.r-universe.dev") | | Development | GitHub | remotes::install_github("strengejacke/ggeffects") |

Or you can run ggeffects::install_latest() to install the latest development version from r-universe.

Adjusted predictions at…: marginalizing over non-focal predictors

predict_response() is a wrapper around three “workhorse” functions, ggpredict(), ggemmeans() and ggaverage(). Depending on the value of the margin argument, predict_response() calls one of those functions, with different arguments. It’s important to note that:

1. Predictions are always returned on the response scale, no matter which model is used. This is the most intuitive scale to interpret your results (the predicted values).

2. The response is predicted at the values or levels of your focal terms, i.e. you specify the predictors you are mainly interested in, using the terms argument. The predicted values are calculated for these values, while all other predictors are marginalized over.

The margin argument in predict_response() indicates how to marginalize over the non-focal predictors, i.e. those variables that are not specified in terms. Each option answers slightly different questions. Possible values are:

• "mean_reference" and "mean_mode": "mean_reference" calls ggpredict(), i.e. non-focal predictors are set to their mean (numeric variables), reference level (factors), or “most common” value (mode) in case of character vectors. "mean_mode" calls ggpredict(typical = c(numeric = "mean", factor = "mode")), i.e. non-focal predictors are set to their mean (numeric variables) or mode (factors, or “most common” value in case of character vectors).

  Question answered: “What is the predicted (or: expected) value of the response at meaningful values or levels of my focal terms for a ‘typical’ observation in my data?”,