Breaking changes:
datagrid() no longer includes the response variable by default when it is not explicitly specified by the user. Use the new response argument to include it.datagrid(grid_type="balanced") returns factors ordered by level rather than by order of appearance in the original data.datagrid(). Necessary to fix issue #1079 (see below).New modeling packages supported:
flexsurv: Thanks to @mattwarkentin for code contributions in PR #781. https://cran.r-project.org/web/packages/flexsurv/index.htmlREndo: https://cran.r-project.org/web/packages/REndo/index.htmlNew:
wts=TRUE tries to retrieves weights used in a weighted fit such as lm() with the weights argument or a model fitted using the survey package. Thanks to @ngreifer for feature requestprint.marginaleffects() supports style="tinytable", which returns a tinytable object. Call print(avg_slopes(model)) to get a nice printed table in Quarto or Rmarkdown documents, via Typst, LaTeX or HTML. Default print format can be set using: options(marginaleffects_print_style="tinytable")hypothesis argument accepts a function which takes a marginaleffects data frame and returns a transformed data frame with term and estimate columns.datagrid() gets a response argument (default is FALSE) to control if the response variable is included or excluded from the grid-building process.base::subset() and dplyr::filter() functions can be called with a single argument in newdata to select a subset of rows from the dataset used to fit the model.
df argument in hypotheses() accepts a vector of length 2 to control degrees of freedom in F tests.nlme::lme() objects raise a warning about degrees of freedom. Thanks to and @stefgehrig and @huftis for discussion in Issue #960.Major bugs:
datagrid() or condition. Thanks to @snhansen for report #1079.glmmTMB models now report correct standard errors, and raise a warning that these standard errors only account for uncertainty in fixed effect parameters. Thanks to contributors to Issue #1024 and especially to @bbolker for discussion and solution.Minor bugs:
comparison function returns NA in bayesian models. Thanks to @Sandhu-SS for report #1017.datagrid() returns an object with full attributes when by is used. Thanks to @Sandhu-SS for report #1058.inferences(method="simulation") with inferences() function. Thanks to @davidarmstrong for report #1054.This release represents a major step towards 1.0.0. Some functions are renamed and now raise deprecation warnings. After 1.0.0, the API will become much more stable, and any change will have to be very deliberate with much lead time and deprecation delays.
Breaking changes:
tidy() no longer takes the average of estimates in the original model object. Users who want an aggregate estimate should call the relevant avg_*() function, or use the by argument explicitly. The previous behavior led to unexpected behavior and increased code complexity a lot.summary() methods are removed. These have never provided any additional information; they just reprinted the output already available with the standard print method. At least the default summary() for data frames (which is now triggered on marginaleffects object) provides a different view on the content of the object.plot_cco(), plot_cme(), and plot_cap() were renamed in version 0.9.0, one year ago. They are now fully removed from the package.New:
datagrid(grid_type = "balanced") creates a balanced grid with all unique values of categorical predictors. This can be used with predictions() to compute marginal means as in the emmeans package.mvgam package support (multivariate generalized additive models)Deprecation warnings:
deltamethod() has been named hypotheses() for a while. We now issue a deprecation warning and it will be removed eventually.datagridcf() will eventually be deprecated and removed from the package. We will raise a warning for at least one year before removing the function. Identical results can be obtained with datagrid(..., grid_type="counterfactual")marginal_means() will eventually be deprecated and removed from the package. We will raise a warning for at least one year before removing the function. Identical results can be obtained using the predictions() function and the grid_type="balanced" argument of datagrid(). Examples are in the marginal means vignette on the website.Minor:
Bug fixes:
hypotheses(joint = "string") for comparisons() objects (no result was returned). Thanks to @BorgeJorge for report #981.brms models. Thanks to @winterstat for report #1006.Breaking changes:
comparisons() now uses “forward contrasts” by default for numeric predictors, instead of “centered contrasts”. This can lead to small numerical differences in non-linear models.variables argument of the comparisons() function no longer accepts numeric vectors unless they are of length 2, specifying the low and high contrast values. This is to avoid ambiguity between the two vector version. Users should supply a data frame or a function instead. This is nearly as easy, and removes ambiguity.New supported packages:
dbarts: https://cran.r-project.org/package=dbartsmvgam: https://nicholasjclark.github.io/mvgam/ Not available on CRAN yet, but this package maintains its own marginaleffects support function.rms::Gls: https://cran.r-project.org/package=rmsMisc:
comparisons(): The variables argument now accepts functions and data frames for factor, character, and logical variables.plot_cap(), plot_cme(), and plot_cco(). These function names will be removed in version 1.0.0.options(modelsummary_factory_default=...) is respected in Quarto and Rmarkdown documents.Bugs:
wts argument now respected in avg_slopes() for binary variables. Thanks to @trose64 for report #961comparison argument of comparisons() did not supply the correct x vector length for bayesian models when the by argument is used. Thanks to @Sandhu-SS for report #931.facet_grid) when plotting using conditioncomparisons(): When variables is a vector of length two and newdata has exactly two columns, there was ambiguity between custom vectors and length two vector of contrasts. Bug reported by C. Rainey on Twitter.fixest::fenegbin.Machine learning support:
tidymodels packagemlr3 packageMisc:
hypotheses() to inferences(). Thanks to @Tristan-Siegfried for code contribution #908.survival::survreg(). Thanks to Carlisle Rainey for Report #911.column_names argument in print.marginaleffects() to suppress the printed column names at the bottom of the printout.comparison argument of the comparisons() function can now operate on x and on newdata directly (e.g., to check the number of observations).predict().Bugs:
gamlss models generated an error related to the what argument. Thanks to @DHLocke for Issue #933hypotheses(): The FUN argument handles group columns gracefully.Amelia for multiple imputation.Documentation:
Bug fix:
predictions() function could be inaccurate when (a) running version 0.15.0, (b) type is NULL or invlink(link), (c) model is glm(), and (d) the hypothesis argument is non-numeric. Thanks to @strengejacke for report #903New:
inferences()hypothesis argument now accepts multiple string formulas.type argument now accepts an explicit invlink(link) value instead of silently back-transforming. Users are no longer pointed to type_dictionary. Instead, they should call their function with a bad type value, and they will obtain a list of valid types. The default type value is printed in the output. This is useful because the default type value is NULL, so the user often does not explicitly decide.Support new models:
survey::svyolr()Misc:
inferences(method="simulation") uses the original point estimate rather than the mean of the simulation distribution. Issue #851.newdata=NULLpredictions() and marginalmeans() (#880, #882, @etiennebacher).Bug fix:
newdata="median" returned mean of binary variables. Thanks to @jkhanson1970 for report #896.Breaking changes:
term, by, and variables explicitly supplied to datagrid. This can affect hypothesis tests computed using the b1, b2, b3, and other indices.numderiv argument use a different procedure to select the step size used in the finite difference numeric derivative used to compute standard errors: abs(x) * sqrt(.Machine$double.eps). The numerical results may not be exactly identical to previous versions of marginaleffects, but the step size should be adequate in a broader variety of cases. Note that users can use the numderiv argument for more control on numeric differentiation, as documented.bife models are no longer supported pending investigation in weird results in the tests. Looking for volunteers write more thorough tests.New:
logistf package.DCchoice package.stats::nlshypotheses() can now accept raw data frame, which gives a lot of flexibility for custom contrasts and functions. See the Hypothesis vignette for an example.numderiv argument allows users to use finite difference (center or forward) or Richardson’s method to compute the numerical derivatives used in the calculation of standard errors.Bug fixes:
inferences() supports the cross argument for comparisons() objects. Thanks to Kirill Solovev for report #856.splines::bs() in formulas could produce incorrect results due to weirdness in stats::model.matrix(). Thanks to @chiungming for report #831.mgcv with ocat are now supported. Thanks to Lorenzo Fabbri for Issue #844.quantreg problem with rowid merge did not affect estimates but did not return the full original data. Issue #829.get_modeldata() extracts weights variable when available.predictions() is no longer broken in some inferences() calls. Issue #853comparison=differenceavg some models where all predictors are categorical. Thanks to Karl Ove Hufthammer for report #865.Misc:
Breaking change:
glmmTMB: Standard errors are no longer supported because they may have been erroneous. Follow Issue #810 on Github for developments: https://github.com/vincentarelbundock/marginaleffects/issues/810New:
hypothesis argument accepts wildcards: hypothesis = "b*=b1"s.value column in all output: Shannon transforms for p values. See Greenland (2019).marginal_means supports mira (mice objects).comparisons(): The variables arguments now accepts arbitrary numeric vectors of length equal to the number of rows in newdata. This allows users to specify fully custom treatment sizes. In the documentation examples, we show how to estimate the difference for a 1 standard deviation shift in a regressor, where the standard deviation is calculated on a group-wise basis.comparisons(): the variables argument now accepts “revpairwise”, “revsequential”, “revreference” for factor and character variables.comparisons(): the comparison argument now accept “lift” and “liftavg”.Performance:
Bug fixes:
newdata is a function call. Thanks to @jcccf for report #814 and to @capnrefsmmat for the proposed fix using the rlang package.Breaking change:
by argument. This may break hypothesis tests conducted by indexing b1, b2, etc. This was necessary to fix Issue #776. Thanks to @marcora for the report.New:
hypotheses(): Joint hypothesis tests (F and Chi-square) with the joint and joint_test arguments.vcov.hypotheses method.wts is now available in plot_predictions(), plot_comparisons(), and plot_slopes().Bug:
by argument. Thanks to @shirdekel for report #782.vcov() and coef() methods for marginaleffects objects.wts are accepted with the by argument.predictions() and avg_predictions() no longer use an automatic backtransformation for GLM models unless hypothesis is NULL.vcov() can be used to retrieve a full variance-covariance matrix from objects produced by comparisons(), slopes(), predictions(), or marginal_means() objects.mice multiple imputation, the pooled model using mice::pool is attached to the model attribute of the output. This means that functions like modelsummary::modelsummary() will not erroneously report goodness-of-fit statistics from just a single model and will instead appropriately report the statistics for the pooled model. Thanks to @Tristan-Siegfried for PR #740.Performance:
inferences() is now up to 17x faster and much more memory-efficient when method is "boot" or "rsample" (#770, #771, @etiennebacher).Bugs:
brms models with nl=TRUE and a single predictor generated an error. Thanks to @Tristan-Siegried for Report #759.avg_predictions(): Incorrect group-wise averaging when all predictors are categorical, the variables variable is used, and we are averaging with avg_ or the by argument. Thanks to BorgeJorge for report #766.datagrid() when called inside a user-written function. Thanks to @NickCH-K for report #769 and to @capnrefsmmat for the diagnostics.Breaking change:
hypothesis with b1, b2, … indexing.Support new models:
nlme::lme()phylolm::phylolm()phylolm::phyloglm()New:
comparisons() accepts data frames with two numeric columns (“low” and “high”) to specify fully customizable contrasts.datagrid() gets a new by argument to create apply grid-making functions within groups.plot_*() gain a newdata argument for use with by.Bug:
comparisons(comparison = "lnratioavg") ignored wts argument. Thanks to Demetri Pananos for report #737.ordinal::clm(): incorrect standard errors when location and scale parameters are the same. Thanks to MrJerryTAO for report #718.datagrid() means newdata argument gets ignored. Thanks to Josh Errickson for report #721.by argument. Thanks to Sam Brilleman for report #723.ordinal::clm() models. Thanks to MrJerryTAO for report #729.glmmTMB models with zero-inflated components are supported. Thanks to @Helsinki-Ronan and @strengejacke for report #734.Breaking changes:
type column is replaced by type attribute.predictions() only works with officially supported model types (same list as comparisons() and slopes()).Renamed arguments (backward compatibility is preserved):
transform_pre -> comparisontransform_post -> transformNew:
p_adjust argument: Adjust p-values for multiple comparisons.equivalence argument available everywhere.Performance:
avg_*() functions for models with only categorical predictors and many rows of data, using deduplication and weights instead of unit-level estimates.lm() and glm() models using RcppEigen.Bugs:
mira objects was not pooling all datasets. Thanks to @Generalized for report #711.predictions() with by and wts. Thanks to Noah Greifer for report #695.afex: some models generated errors. Thanks to Daniel Lüdecke for report #696.group column name is always forbidden. Thanks to Daniel Lüdecke for report #697.plot_comparisons() with a list in variables.type="link" produced an error with some categorical brms models. Thanks to @shirdekel for report #703.predictions(variables = ...) for glmmTMB models. Thanks to Daniel Lüdecke for report #707.by with user-specified function in comparison and factor predictor did not aggregate correctly. Thanks to @joaotedde for report #715.ordinal::clm: Support cum.prob and linear.predictor prediction types. Thanks to @MrJerryTAO for report #717.Performance:
New models supported:
MCMCglmm::MCMCglmmRchoice::hetprobRchoice::ivpmlmice and any package which can return a list of imputed data frames (e.g., Amelia, missRanger, etc.)Plot improvements:
by argument to display marginal estimates by subgroup.rug argument to display tick marks in the margins.points argument in plot_predictions() to display a scatter plot.gray argument to plot in grayscale using line types and shapes instead of color.effect argument is renamed to variables in plot_slopes() and plot_comparisons(). This improves consistency with the analogous slopes() and comparisons() functions.Other:
mice mira objects. The multiple imputation vignette was rewritten.variables_grid argument in marginal_means() is renamed newdata. Backward compatibility is maintained.avg_*() returns an informative error when vcov is “satterthwaite” or “kenward-roger”newdata is not NULLhypothesis includes a b# larger than the available number of estimates.avg_predictions(model, variables = "x") computes average counterfactual predictions by subgroups of xdatagrid() and plot_*() functions are faster in datasets with many extraneous columns.predictions(type = NULL) with glm() and Gam() we first make predictions on the link scale and then backtransform them. Setting type="response" explicitly makes predictions directly on the response scale without backtransformation.glmmTMB models.numDeriv package for numeric differentiation in the calculation of delta method standard error. A global option can now be passed to numDeriv::jacobian:
options(marginaleffects_numDeriv = list(method = "simple", method.args = list(eps = 1e-6)))options(marginaleffects_numDeriv = list(method = "Richardson", method.args = list(eps = 1e-6)))options(marginaleffects_numDeriv = NULL)print.marginaleffects now prints all columns supplied to newdatahypothesisBugfixes:
avg_predictions(by =) did not work when the dataset included a column named term. Issue #683.brms models with multivariate outcome collapsed categories in comparisons(). Issue #639.hypotheses() now works on lists and in calls to lapply(), purrr::map(), etc. Issue #660.Breaking changes:
estimate column instead of the function-specific predicted, comparisons, dydx, etc. This change only affects unit-level estimates, and not average estimates, which already used the estimate column name.transform_avg argument in tidy() deprecated. Use transform_post instead.plot_*(draw=FALSE) now return the actual variable names supplied to the condition argument, rather than the opaque “condition1”, “condition2”, etc.New models supported:
blme package.New features:
avg_predictions(), avg_comparisons(), avg_slopes()hypotheses() function and equivalence argument.inferences() function: simulation-based inferences and bootstrap using the boot, rsample, and fwb package.df argument to set degrees of freedom manually for p and CI.print() for all objects.by argument
TRUE returns average (marginal) predictions, comparisons, or slopes.hypothesis argument
comparisons(mod, transform_pre = "ratio", hypothesis = 1)tidy(), and summary(): conf_level, transform_post, etc.?comparisonsRenamed functions (backward-compatibility is maintained by keeping the old function names as aliases):
marginaleffects() -> slopes()posteriordraws() -> posterior_draws()marginalmeans() -> marginal_means()plot_cap() -> plot_predictions()plot_cme() -> plot_slopes()plot_cco() -> plot_comparisons()Bug fixes:
plot_*() the threenum and minmax labels did not correspond to the correct numeric values.mlogit error with factors.vcov argument now accepts functions for most models.Other:
slopes()deltamethod() can run hypothesis tests on objects produced by the comparisons(), marginaleffects(), predictions(), and marginalmeans() functions. This feature relies on match.call(), which means it may not always work when used programmatically, inside functions and nested environments. It is generally safer and more efficient to use the hypothesis argument.plot_cme() and plot_cco() accept lists with user-specified values for the regressors, and can display nice labels for shortcut string-functions like “threenum” or “quartile”.posterior_draws: new shape argument to return MCMC draws in various formats, including the new rvar structure from the posterior package.transform_avg function gets printed in summary() output.transform_post and transform_avg support string shortcuts: “exp” and “ln”mlm models from lm(). Thanks to Noah Greifer.Bug fixes:
hypothesis argument with bayesian models and tidy() used to raise an error.comparisons() output for brms models.Breaking change:
interaction argument is deprecated and replaced by the cross argument. This is to reduce ambiguity with respect to the interaction argument in emmeans, which does something completely different, akin to the difference-in-differences illustrated in the Interactions vignette.71 classes of models supported, including the new:
rms::olsrms::lrmrms::ormNew features:
plot_cme(), plot_cap(), and plot_cco() are now much more flexible in specifying the comparisons to display. The condition argument accepts lists, functions, and shortcuts for common reference values, such as “minmax”, “threenum”, etc.variables argument of the comparisons() function is more flexible:
variables argument of the comparisons function.variables argument of the predictions() function is more flexible:
brms models (see Bayesian analysis vignette)New vignettes:
Bug fixes and minor improvements:
conf_level in summary() and tidy() is now NULL, which inherits the conf_level value in the original comparisons/marginaleffects/predictions calls.fixest::i() are parsed properly as categorical variablesbetareg objects, inference can now be done on all coefficients using deltamethod(). previously only the location coefficients were available.crch package, a number of bugs have been fixed; standard errors should now be correct for deltamethod(), marginaleffects(), etc.tidy() function for glmmTMB models without random effects, which caused all t statistics to be identical.gamlss. Thanks to Marcio Augusto Diniz.marginalmeans() accepts a wts argument with values: “equal”, “proportional”, “cells”.by argument
marginalmeans only accepts data frames.byfun argument for the predictions() function to aggregate using different functions.hypothesis argument
wts argument is respected in by argument and with *avg shortcuts in the transform_pre argument.tidy.predictions() and tidy.marginalmeans() get a new transform_avg argument.marginaleffects. Thanks to timpipeseek.Breaking changes:
by is deprecated in summary() and tidy(). Use the same by argument in the main functions instead: comparisons(), marginaleffects(), predictions()variables argument of the predictions() function. Use newdata="fivenum" or “grid”, “mean”, or “median” instead.Critical bug fix:
New supported packages and models:
survival::clogitbiglm: The main quantities can be computed, but not the delta method standard errors. See https://github.com/vincentarelbundock/marginaleffects/issues/387New vignette:
New features:
slope argument in marginaleffects(): eyex, dyex, eydxdatagrid() accepts functions: datagrid(newdata = mtcars, hp = range, mpg = fivenum, wt = sd)datagridcf() function to create counterfactual datasets. This is a shortcut to the datagrid() function with default to grid_type = "counterfactual"by arguments in predictions(), comparisons(), marginaleffects()newdata shortcuts: “tukey”, “grid”transform_pre in comparisons()marginalmeans() now back transforms confidence intervals when possible.vcov argument string shortcuts are now case-insensitivecomparisons() for binary predictors is now a difference between 1 and 0, rather than +1 relative to baseline.New supported packages and models:
tidymodels objects of class tidy_model are supported if the fit engine is supported by marginaleffects.New function:
deltamethod(): Hypothesis tests on functions of parametersplot_cco(): Plot conditional contrastsNew arguments:
hypothesis for hypothesis tests and custom contraststransform_post in predictions()wts argument in predictions() only affects average predictions in tidy() or summary().New or improved vignettes:
Deprecated or renamed arguments:
contrast_factor and contrast_numeric arguments are deprecated in comparisons(). Use a named list in the variables argument instead. Backward compatibility is maintained.transform_post argument in tidy() and summary() is renamed to transform_avg to disambiguate against the argument of the same name in comparisons(). Backward compatibility is preserved.Misc:
tidy.predictions() computes standard errors using the delta method for average predictionsgam models with matrix columns.eps in marginaleffects() is now “adaptive” by default: it equals 0.0001 multiplied the range of the predictor variablecomparisons() now supports “log of marginal odds ratio” in the transform_pre argument. Thanks to Noah Greifer.transform_pre shortcuts: dydx, expdydxtidy.predictions() computes standard errors and confidence intervals for linear models or GLM on the link scale.Breaking changes:
type no longer accepts a character vector. Must be a single string.conf.int argument deprecated. Use vcov = FALSE instead.New supported packages and models:
mlogitmhurdletobit1glmmTMBNew features:
interaction argument in comparisons() to compute interactions between contrasts (cross-contrasts).by argument in tidy() and summary() computes group-average marginal effects and comparisons.transform_pre argument can define custom contrasts between adjusted predictions (e.g., log adjusted risk ratios). Available in comparisons().transform_post argument allows back transformation before returning the final results. Available in comparisons(), marginalmeans(), summary(), tidy().variables argument of the comparisons() function accepts a named list to specify variable-specific contrast types.vcov argument. This requires version 0.17.1 of the insight package.
sandwich package shortcuts: vcov = "HC3", "HC2", "NeweyWest", and more.vcov = "satterthwaite" or "kenward-roger"vcov = ~cluster_variablemarginalmeans() allows interactionsbrms models using type = "average". See vignette on the marginaleffects website.eps argument for step size of numerical derivativemarginaleffects and comparisons now report confidence intervals by default.data.table package yields substantial performance improvements.New pages on the marginaleffects website: https://marginaleffects.com/
Argument name changes (backward compatibility is preserved:
conf.level -> conf_leveldatagrid():
FUN.factor -> FUN_factor (same for related arguments)grid.type -> grid_typeNew supported packages and models:
stats::loesssampleSelection::selectionsampleSelection::heckitMisc:
mgcv::bam models allow exclude argument.include_smooth argument.New function:
comparisons() computes contrastsMisc:
predictions() and plot_cap() include confidence intervals for linear modelsggplot2::theme_set() callNew supported models:
mclogit::mclogitrobust::lmRobrobustlmm::rlmerfixest confidence intervals in predictionsMisc:
modelbased::visualisation_matrix in newdata without having to specify x explicitly.tidy.predictions() and summary.predictions() methods.Support for new models and packages:
brglm2::braclmclogit::mblogitscam::scamlmerTest::lmerMisc:
numDeriv dependency, but make it available via a global option: options(“marginaleffects_numDeriv” = list(method = “Richardson”, method.args = list(eps = 1e-5, d = 0.0001)))documentation bugfix
Breaking changes:
predictions returns predictions for every observation in the original dataset instead of newdata=datagrid().marginalmeans objects have new column names, as do the corresponding tidy and summary outputs.New supported packages and models:
brms::brmrstanarm::stanglmbrglm2::brmultinomMASS::glmmPQLaod::betabinMisc:
datagrid function supersedes typical and counterfactual with the grid.type argument. The typical and counterfactual functions will remain available and exported, but their use is not encouraged.posterior_draws function can be applied to a predictions or a marginaleffects object to extract draws from the posterior distribution.marginalmeans standard errors are now computed using the delta method.predictions standard errors are now computed using the delta method when they are not available from insight::get_predicted.brmslme4data.table package is installed, marginaleffects will automatically use it to speed things up.marginaleffects output.type argument.emmeansBreaking change:
data argument becomes newdata in all functions.New supported packages and models:
lme4:glmer.nbmgcv::gamordinal::clmmgcvmarginalmeans:
variables_grid argumentpredictions:
mgcvplot_cap
type argumentMisc:
First release. Bravo!
Thanks to Marco Avina Mendoza, Resul Umit, and all those who offered comments and suggestions.