ggeffects

General

• Overhaul of the documentation (again), to provide more clarity about the
  terminology "adjusted predictions", "marginal means" and "marginal effects",
  and how to calculate each of these quantities using the ggeffects package.

• print_html() methods were updated to work with the latest release of
  tinytable.

• New print_md() method, to print the output as markdown table. This is useful
  inside RMarkdown or Quarto documents, where the output can be directly included.

New functions

• predict_response() as "generic" high-level function, which is a replacement
  for ggpredict(), ggemmeans() and ggaverage(). The new function is more
  clear about how the function marginalizes over non-focal terms. The margin
  argument can be used to specify how to marginalize over non-focal terms, i.e.
  which function internally is used to compute the marginal effects.

General

• The documentation was revised, to provide more clarity about what the package
  functions do and how to decide, which function or method to calculate marginal
  effects is the most appropriate.

• Improved calculation of prediction intervals for Poisson regression models.

• Improved handling of the vcov_fun argument. This argument now accepts an
  estimation type as string, e.g. vcov_fun = "HC0", which is then used to
  compute the variance-covariance matrix. Thus, it is no longer necessary to
  define both vcov_fun and vcov_type, if the variance-covariance matrix is
  covered by one of the pre-defined estimation types. See ?ggpredict for
  details.

• hypothesis_test() now also accepts the vcov_fun argument, and not only
  vcov. This ensures consistency with the vcov_fun argument in ggpredict().
  Furthermore, the information about the type of variance-covariance matrix
  is saved to the ggeffects object returned by ggpredict(), predict_response()
  etc., and if this information is available, it is automatically used in
  hypothesis_test() when a ggeffects object is passed to the function.

Bug fixes

• Fixed bug in wrong order of printed (sub-)tables for predictions.

• Fixed wrong table column name for confidence interval columns for other
  confidence levels than the default 95% in print() for ggeffects objects.

• Fixed issue with ggpredict() for models of class fixest when the cluster
  variable was numeric.

Breaking Changes

• The print() method has been revised. A format() method was added, which
  allows to format the output of ggpredict() (and ggeffect() etc.) for
  printing. The refactoring of the print() method makes the code base easier
  to maintain and it is easier to enhance the print-functionality. Now it is
  possible to create HTML tables as well, using print_html(). The style of the
  output has also slightly changed. By default, confidence intervals are no
  longer enclosed in parentheses. You can change this behaviour by passing the
  ci_brackets argument to print() (see examples), or permanently define custom
  parentheses or brackets with, e.g., options(ggeffects_ci_brackets = c("[", "]")).
  Additionally, there are new arguments to further control the output of the
  tables: collapse_ci can be used to collapse confidence intervals into a
  single column together with the predicted values. collapse_tables can be used
  to collapse multiple tables into a single table (only applies when there is
  more than one focal term). Again, these settings can be permanently defined
  via options (see ?print.ggeffects for details).

New functions

• print_html(), to print the output as HTML table. This method is available
  for objects from ggpredict() (and alike) as well as hypothesis_test().

General

• A new vignette was added, showing examples for the new print-functionality.

Bug fixes

• Fixed issue with ggpredict() for models of class vglm with multivariate
  responses.

General

• ggpredict() now supports models of class rqs from package quantreg.

• Fixed issues to be compatible with forthcoming update of emmeans.

New function

• ggaverage(), to compute average predicted values. This function is based on
  marginaleffects::avg_predictons().

• pool_comparisons(), to pool results from multiple calls to hypothesis_test(),
  e.g. with imputed data sets.

General

• Support for sdmTMB (sdmTMB) models.

• Improved support for the logistf package, including models flic() and
  flac().

• Confidence intervals for predictions from merMod models (package lme4)
  now use the standard errors returned by predict(..., se.fit = TRUE). This
  should not affect numerical results, but can be more robust for certain edge
  cases. Note that standard errors are only based on predict() when
  tpye = "fixed". For type = "random", standard errors are still based on
  the model's variance-covariance matrix, taking uncertainty from random
  effects into account.

• hypothesis_test() now suppports models from package parsnip.

• johnson_neyman() gains a p_adjust argument, to adjust p-values for multiple
  comparisons. Currently, only p_adjust = "esarey" (resp. p_adjust = "es") and
  p_adjust = "fdr" (resp. p_adjust = "bh") are supported.

Bug fixes

• ggpredict() now computes appropriate predicted probabilites for models
  of class rms::lrm() with ordinal outcome.

• Fixed issue in ggpredict() for type = "random" when sampling from random
  effects levels, where the levels were numeric characters with a pattern like
  "001", "002", etc.

• Fixed minor issue in plot.ggalleffects().

• ... arguments in ggpredict() are now passed down to the predict() method
  for mgcv::gam() models.

Breaking changes

• Some function arguments will be renamed, to achieve consistency across the
  package and across other packages where I'm involved in the development.
  This will be a soft transition, i.e. the old argument names will still work
  for some package updates.

Changes

• The typical argument now supports a mix of functions for different variable
  types at which numeric or categorical covariates (non-focal terms) are held
  constant.

• Clarification of how the re.form argument is set when using type = "random"
  resp. type = "fixed" in ggpredict().

• hypothesis_test() now returns the standard error of contrasts or pairwise
  comparisons as attribute standard_error. This can be used to compute the
  test-statistic, if required. In forthcoming updates, there will be methods
  for insight::get_statistic() and parameters::model_parameters() to include
  standard errors and test-statistics in the output.

• test_predictions() was added as an alias for hypothesis_test().

Bug fixes

• Fixed issue in hypothesis_test() for mixed models, which sometimes failed
  when random effects group variables were numeric, and not factors.

New functions

• johnson_neyman(), to create Johnson-Neyman intervals and plots from
  ggeffects objects.

Changes

• Better automatic handling of offset-terms, both for predictions and generating
  plots with raw data. When the model formula contains an offset-term, and the
  offset term is fixed at a specific value, the response variable is now
  automatically transformed back to the original scale, and the offset-term is
  added to the predicted values. A warning is printed when model contains transformed offset-terms that are not fixed, e.g. via the condition argument.

• ggeffect() now supports nestedLogit models.

Bug fixes

• Fixed issue in hypothesis_test(), where the by argument did not work
  together with the collapse_levels argument.

• Fixed issue in plot() method when adding raw data points for data frame
  that had now row names.

Breaking

• To avoid confusion when adding raw data or residuals to plots, the jitter
  argument that is used to add some noice to data points to avoid overlapping
  now defaults to NULL. Formerly, a small jitter was added by default,
  leading to confusion when data points did not match the original data.

Changes

• The plot() method gets a label.data argument, to add row names to data
  points when add.data = TRUE.

• tibbles are always converted into data frames, to avoid issues.

• hypothesis_test() gains a by argument, to specify a variable that is used
  to group the comparisons or contrasts. This is useful for models with interaction
  terms.

Bug fixes

• Plotting residuals did not work when model object passed to ggpredict()
  were inside a list, or when called from inside functions (scoping issues).

• Fixed issue where plotting raw data (i.e. plot(..., add.data = TRUE)) did
  not work when there were missing data in weight variables (i.e. when the
  regression model used weights).

• Fixes issue in plot() when no term was specified in the call to ggpredict().

• Fixed issues with robust estimation for models of package pscl.

• Fixed issues introduced by breaking changes in marginaleffects.

General

• Support for nestedLogit (nestedLogit) models.

• hyothesis_test() gains a scale argument, to explicitely modulate the scale
  of the contrasts or comparisons (e.g. "response" or "link", or "exp" to
  return transformed contrasts/comparisons).

• hyothesis_test() now includes the response level for models with ordinal
  outcomes (and alike).

• When ggpredict() is used inside functions and a name for a vector variable
  (passed as argument to that function) in terms is used, the variable is
  now correctly recognized.

• Partial residuals (when plot(..., residuals = TRUE)) now supports more
  linear (mixed) models, including models from package lme (such as gls()
  or lme()).

• For mixed models, type = "random" used to calculate prediction intervals
  that always accounted for random effects variances, leading to larger intervals.
  Using interval = "confidence" together with type = "random" now allows to
  calculate "usual" confidence intervals for random effects. This is usefule for
  predictions at specific group levels of random effects (when focal terms are
  only fixed effects, use type = "fixed" for regular confidence intervals).

• The vcov.fun argument can now also be a function that returns a
  variance-covariance matrix.

• The verbose argument in ggpredict() and hypothesis_test() now also toggle
  messages for the respective print() methods.

• The print() method for hypothesis_test() has been revised and now provides
  more details for possible transformation of the scale of comparisons and
  contrasts.

• The print() method now shows all rows by default when the focal term is
  a factor. If rows are not shown in the output, a message is printed to inform
  the user about truncated output.

• A new vignette about using ggeffects in the context of an intersectional
  multilevel analysis of individual heterogeneity, using the MAIHDA framework.

Bug fixes

• Fixed issue with wrong order of x-axis-labels for plots when the focal term
  on the x-axis was a character vector, where alphabetical order of values did
  not match order of predictions.

• Fixed issues in hyothesis_test() for models with ordinal outcomes (and alike).

General

• Added a new [.ggeffects function, which allows to subset ggeffects objects
  in the same way as regular data frames, i.e. it is now possible to do:

  gge <- ggpredict(model, "x1")
  gge[c(1:2)]
  

• Using a name for a vector variable in terms now works from inside functions.
  E.g., you can now do:

  foo <- function(data) {
    fit <- lm(barthtot ~ c12hour + c172code, data = data)
    v <- c(20, 50, 70)
    ggpredict(fit, terms = "c12hour [v]")
  }
  foo(efc)
  

• The colors argument in plot() can now also be applied to single-colored
  plots.

• hyothesis_test() gains a collapse_level argument, to collapse term labels
  that refer to the same levels into a singel unique level string.

Bug fixes

• Fixed issue with misplaced residuals when x-axis was categorical and the
  factor levels were not in alphabetical order.

• pool_predictions() now correctly handles models with transformed response
  variables (like log(y)) and returns the correct back-transformed pooled
  predictions (and their confidence intervals).

• Fixed issue with wrong computation of confidence intervals for models of class
  clm from package ordinal.

• Fixed failing tests due to changes in the logistf package, which now also
  supports emmeans. That means, ggemmeans() now also works for models from
  package logistf.

• Fixed bug in plot() when partial residuals were added (i.e. residuals = TRUE)
  and collapse.group was provided (in case of mixed models).

• Fixed issue with on-the-fly created factors inside formulas, which were not
  correctly treated as factors in the plot() method. This bug was related to
  recent changes in insight::get_data().

• Fixed issue with wrong labels in hyothesis_test() for comparisons with many
  rows, when betas starting with same digit were specified (e.g.
  test = "(b1-b13)=(b3-b15)").

• Fixed issue in hyothesis_test() for mixed models when focal terms included
  factors with factor levels that contained a comma.

• Fixed issue with missing confidence intervals for mixed models when one of
  the variable names contains white space characters (e.g. y ~ 'x a' + xb).

Breaking

• Confidence intervals of adjusted predictions now take the model's degrees of
  freedom into account, thereby leading to slightly larger intervals for models
  that do not have infinite degrees of freedom (like linear models with
  t-statistic).

New functions

• hypothesis_test(), to compute contrasts and comparisons of predictions and
  test differences for statistical significance. Additionally, an accompanying
  vignette that explains the new function in detail is added.

• install_latest(), to install the latest official package version from
  CRAN, or the latest development version from r-universe.

• An as.data.frame() method was added, which converts ggeffects objects
  returned by ggpredict() into data frame, where standard column names are
  replaced by their related variable names.

General

• Response values are now also back-transformed when these were transformed
  using log2(), log10() or log1p().

• The terms argument can now also be a named list. Thus, instead of
  terms = c("score [30,50,70]", "status [low, middle]") one could also write
  terms = list(score = c(30,50,70), status = c("low", "middle")).

General

• Reduced package dependencies. Packages sjlabelled and MASS were moved
  from imports to suggests. ggeffects is now a very lightweight package to
  compute adjusted predictions and estimated marginal means.

New supported models

• logitr (package logitr)

Bug fixes

• Fixed issue with wrong standard errors for predicting random effect groups
  for more multiple levels.

• Fixed issue in ggemmeans(), which did not correctly averaged over character
  vectors when these were hold constant.

• Fixed bug for models of class lme when type = "re" was requested.

General

• New vignette Different Output between Stata and ggeffects.

Changes to functions

• ggpredict() now automatically back-transforms predictions to the response scale for model with log-transformed response.
• ggeffect() and ggpredict() now automatically set numeric vectors with 10 or more unique values to representative values (see rprs_values()), if these are used as second or third value in the terms-argument (to represent a grouping structure).
• Fix memory allocation issue in ggeffect().
• rprs_values() is now exported.
• The pretty-argument is deprecated, because prettifying values almost always makes sense - so this is done automatically.
• ggpredict() now supports brmsfit-objects with categorical-family.
• ggalleffect() has been removed. ggeffect() now plots effects for all model terms if terms = NULL.
• gginteraction() and ggpoly() have been removed, as ggpredict() and ggeffect() are more efficient and generic for plotting interaction or polynomial terms.

Bug fixes

• Fix issues with categorical or ordinal outcome models (polr, clm, multinom) for ggeffect().
• Fix issues with confidence intervals for mixed models with log-transformed response value.
• Fix issues with confidence intervals for generalized mixed models when response value was a rate or proportion created with cbind() in model formula.

General

• Removed alias names mem(), eff() and ame().
• For mixed models (packages lme4, nlme, glmmTMB), the uncertainty of the random effect variances is now taken into account when type = "re".
• Computing confidence intervals for mixed models should be much more memory efficient now, resulting less often in warnings about memory allocation problems.
• Updated reference in CITATION to the publication in the Journal of Open Source Software.
• A test-suite was added to the package.

New functions

• pretty_range(), to create a pretty sequence of integers of a vector.

Changes to functions

• ggpredict() gets a condition-argument to specify values at which covariates should be held constant, instead of their typical value.
• The pretty-option for ggpredict() now calculates more values, leading to smoother plots.
• The terms-argument in ggpredict() can now also select a range of feasible values for numeric values, e.g. terms = "age [pretty]". In contrast to the pretty-argument, which prettyfies all terms, you can selectively prettify specific terms with this option.
• The terms-argument in ggpredict() now also supports all shortcuts that are possible for the mdrt.values-argument in gginteraction(), so for instance term = "age [meansd]" would return three values: mean(age) - sd(age), mean(age) and mean(age) + sd(age).
• plot() gets some new arguments to control which plot-title to show or hide: show.title, show.x.title and show.y.title.
• plot() gets a log.y argument to transform the y-axis to logarithmic scale, which might be useful for binomial models with predicted probabilities, or other models with log-alike link-functions.
• The plot()-method for plotting all effects with ggpredict() (when term = NULL) now allows to arrange the plot in facets (using facets = TRUE).
• Values in dot-argument for plot() are now passed down to ggplot::scale_y*(), to control the appearance of the y-axis (like breaks).

Bug fixes

• Fixed issue with binomial models that used cbind(...) as response variable.
• Fixed issue with suboptimal precision of confidence resp. prediction intervals for mixed models (packages lme4, nlme), which are now more accurate.

Release with revisions suggested during JOSS-review.

General

• Prediction for glmmTMB-objects now compute proper confidence intervals, due to fix in package glmmTMB 0.2.1
• If terms in ggpredict() is missing or NULL, marginal effects for each model term are calculated. ggpredict() then returns a list of data frames, which can also be plotted with plot().

Changes to functions

• The jitter-argument from plot() now accepts a numeric value between 0 and 1, to control the width of the random variation in data points.
• ggpredict() and ggeffect() can now predict transformed values, which is useful, for instance, to exponentiate predictions for log(term) on the original scale of the variable. See package vignette, section Marginal effects at specific values or levels for examples.

Bug fixes

• Multivariate response models in brms with variable names with underscores and dots were not correctly plotted.

General

• Better support for multivariate-response-models from brms.
• Support for cumulative-link-models from brms.
• ggpredict() now supports linear multivariate response models, i.e. lm() with multiple outcomes.

Changes to functions

• ggpredict() gets a pretty-argument to reduce and "prettify" the value range from variables in terms for predictions. This applies to all variables in terms with more than 25 unique values.

Bug fixes

• Recognize negative binomial family from brmsfit-models.