marginaleffects 0.11.0
Breaking changes:
-
type
column is replaced bytype
attribute. -
predictions()
only works with officially supported model types (same list ascomparisons()
andslopes()
).
Renamed arguments (backward compatibility is preserved):
-
transform_pre
->comparison
-
transform_post
->transform
New:
-
p_adjust
argument: Adjust p-values for multiple comparisons. -
equivalence
argument available everywhere.
Performance:
- Much faster results in
avg_*()
functions for models with only categorical predictors and many rows of data, using deduplication and weights instead of unit-level estimates. - Faster predictions in
lm()
andglm()
models usingRcppEigen
. - Bayesian models with many rows. Thanks to Etienne Bacher. #694
- Faster predictions, especially with standard errors and large datasets.
Bugs:
- Multiple imputation with
mira
objects was not pooling all datasets. Thanks to @Generalized for report #711. - Support for more models with offsets. Thanks to @mariofiorini for report #705.
- Error on
predictions()
withby
andwts
. 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. - Blank graphs in
plot_comparisons()
with a list invariables
. -
type="link"
produced an error with some categoricalbrms
models. Thanks to @shirdekel for report #703. - Error on
predictions(variables = ...)
forglmmTMB
models. Thanks to Daniel Lüdecke for report #707. -
by
with user-specified function incomparison
and factor predictor did not aggregate correctly. Thanks to @joaotedde for report #715. -
ordinal::clm
: Supportcum.prob
andlinear.predictor
prediction types. Thanks to @MrJerryTAO for report #717.
marginaleffects 0.10.0
CRAN release: 2023-02-22
Performance:
- 2-4x faster execution for many calls. Thanks to Etienne Bacher.
New models supported:
MCMCglmm::MCMCglmm
Rchoice::hetprob
Rchoice::ivpml
- Multiple imputation using
mice
and any package which can return a list of imputed data frames (e.g.,Amelia
,missRanger
, etc.)
Plot improvements:
- New
by
argument to display marginal estimates by subgroup. - New
rug
argument to display tick marks in the margins. - New
points
argument inplot_predictions()
to display a scatter plot. - New
gray
argument to plot in grayscale using line types and shapes instead of color. - The
effect
argument is renamed tovariables
inplot_slopes()
andplot_comparisons()
. This improves consistency with the analogousslopes()
andcomparisons()
functions. - The plotting vignette was re-written.
Other:
- Support multiple imputation with
mice
mira
objects. The multiple imputation vignette was rewritten. - The
variables_grid
argument inmarginal_means()
is renamednewdata
. Backward compatibility is maintained. -
avg_*()
returns an informative error whenvcov
is “satterthwaite” or “kenward-roger” - “satterthwaite” and “kenward-roger” are now supported when
newdata
is notNULL
- Informative error when
hypothesis
includes ab#
larger than the available number of estimates. -
avg_predictions(model, variables = "x")
computes average counterfactual predictions by subgroups ofx
-
datagrid()
andplot_*()
functions are faster in datasets with many extraneous columns. - In
predictions(type = NULL)
withglm()
andGam()
we first make predictions on the link scale and then backtransform them. Settingtype="response"
explicitly makes predictions directly on the response scale without backtransformation. - Standard errors now supported for more
glmmTMB
models. - Use the
numDeriv
package for numeric differentiation in the calculation of delta method standard error. A global option can now be passed tonumDeriv::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:
- Print fewer significant digits.
-
print.marginaleffects
now prints all columns supplied tonewdata
- Less redundant labels when using
hypothesis
- Many improvements to documentation.
Bugfixes:
- Standard errors could be inaccurate in models with non-linear components (and interactions) when some of the coefficients were very small. This was related to the step size used for numerical differentiation for the delta method. Issue #684.
-
avg_predictions(by =)
did not work when the dataset included a column namedterm
. Issue #683. -
brms
models with multivariate outcome collapsed categories incomparisons()
. Issue #639. -
hypotheses()
now works on lists and in calls tolapply()
,purrr::map()
, etc. Issue #660.
marginaleffects 0.9.0
CRAN release: 2023-02-01
Breaking changes:
- All functions return an
estimate
column instead of the function-specificpredicted
,comparisons
,dydx
, etc. This change only affects unit-level estimates, and not average estimates, which already used theestimate
column name. - The
transform_avg
argument intidy()
deprecated. Usetransform_post
instead. -
plot_*(draw=FALSE)
now return the actual variable names supplied to thecondition
argument, rather than the opaque “condition1”, “condition2”, etc.
New models supported:
-
blme
package.
New features:
- New functions:
avg_predictions()
,avg_comparisons()
,avg_slopes()
- Equivalence, non-inferiority, and non-superiority tests with the
hypotheses()
function andequivalence
argument. - New experimental
inferences()
function: simulation-based inferences and bootstrap using theboot
,rsample
, andfwb
package. - New
df
argument to set degrees of freedom manually for p and CI. - Pretty
print()
for all objects. -
by
argument-
TRUE
returns average (marginal) predictions, comparisons, or slopes. - Supports bayesian models.
-
-
hypothesis
argument- Numeric value sets the null used in calculating Z and p.
- Example:
comparisons(mod, transform_pre = "ratio", hypothesis = 1)
- All arguments from the main functions are now available through
tidy()
, andsummary()
:conf_level
,transform_post
, etc. - Bayesian posterior distribution summaries (median, mean, HDI, quantiles) can be customized using global options. See
?comparisons
Renamed 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:
- Incorrect results: In 0.8.1,
plot_*()
thethreenum
andminmax
labels did not correspond to the correct numeric values. - Fix corner case for slopes when the dataset includes infinite values.
-
mlogit
error with factors. - The
vcov
argument now accepts functions for most models.
Other:
- Removed major performance bottleneck for
slopes()
marginaleffects 0.8.1
CRAN release: 2022-11-23
-
deltamethod()
can run hypothesis tests on objects produced by thecomparisons()
,marginaleffects()
,predictions()
, andmarginalmeans()
functions. This feature relies onmatch.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 thehypothesis
argument. -
plot_cme()
andplot_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
: newshape
argument to return MCMC draws in various formats, including the newrvar
structure from theposterior
package. -
transform_avg
function gets printed insummary()
output. -
transform_post
andtransform_avg
support string shortcuts: “exp” and “ln” - Added support for
mlm
models fromlm()
. Thanks to Noah Greifer.
Bug fixes:
-
hypothesis
argument with bayesian models andtidy()
used to raise an error. - Missing values for some regressors in the
comparisons()
output forbrms
models.
marginaleffects 0.8.0
CRAN release: 2022-11-02
Breaking change:
- The
interaction
argument is deprecated and replaced by thecross
argument. This is to reduce ambiguity with respect to theinteraction
argument inemmeans
, which does something completely different, akin to the difference-in-differences illustrated in the Interactions vignette.
71 classes of models supported, including the new:
New features:
- Plots:
plot_cme()
,plot_cap()
, andplot_cco()
are now much more flexible in specifying the comparisons to display. Thecondition
argument accepts lists, functions, and shortcuts for common reference values, such as “minmax”, “threenum”, etc. -
variables
argument of thecomparisons()
function is more flexible:- Accepts functions to specify custom differences in numeric variables (e.g., forward and backward differencing).
- Can specify pairs of factors to compare in the
variables
argument of thecomparisons
function.
-
variables
argument of thepredictions()
function is more flexible:- Accepts shortcut strings, functions, and vectors of arbitrary length.
- Integrate out random effects in bayesian
brms
models (see Bayesian analysis vignette)
New vignettes:
- Experiments
- Extending marginal effects
- Integrating out random effects in bayesian models
Bug fixes and minor improvements:
- The default value of
conf_level
insummary()
andtidy()
is nowNULL
, which inherits theconf_level
value in the originalcomparisons
/marginaleffects
/predictions
calls. - Fix typo in function names for missing “lnratioavgwts”
- Interactions with
fixest::i()
are parsed properly as categorical variables - For
betareg
objects, inference can now be done on all coefficients usingdeltamethod()
. previously only the location coefficients were available. - For objects from
crch
package, a number of bugs have been fixed; standard errors should now be correct fordeltamethod()
,marginaleffects()
, etc. - Fixed a bug in the
tidy()
function forglmmTMB
models without random effects, which caused all t statistics to be identical.
marginaleffects 0.7.1
CRAN release: 2022-09-25
- New supported model class:
gamlss
. Thanks to Marcio Augusto Diniz. -
marginalmeans()
accepts awts
argument with values: “equal”, “proportional”, “cells”. -
by
argument- accepts data frames for complex groupings.
- in
marginalmeans
only accepts data frames. - accepts “group” to group by response level.
- works with bayesian models.
-
byfun
argument for thepredictions()
function to aggregate using different functions. -
hypothesis
argument- The matrix column names are used as labels for hypothesis tests.
- Better labels with “sequential”, “reference”, “pairwise”.
- new shortcuts “revpairwise”, “revsequential”, “revreference”
-
wts
argument is respected inby
argument and with*avg
shortcuts in thetransform_pre
argument. -
tidy.predictions()
andtidy.marginalmeans()
get a newtransform_avg
argument. - New vignettes:
- Unit-level contrasts in logistic regressions. Thanks to @arthur-albuquerque.
- Python Numpy models in
marginaleffects
. Thanks to @timpipeseek. - Bootstrap example in standard errors vignette.
marginaleffects 0.7.0
CRAN release: 2022-08-06
Breaking changes:
-
by
is deprecated insummary()
andtidy()
. Use the sameby
argument in the main functions instead:comparisons()
,marginaleffects()
,predictions()
- Character vectors are no longer supported in the
variables
argument of thepredictions()
function. Usenewdata="fivenum"
or “grid”, “mean”, or “median” instead.
Critical bug fix:
- Contrasts with interactions were incorrect in version 0.6.0. The error should have been obvious to most analysts in most cases (weird-looking alignment). Thanks to @vmikk.
New supported packages and models:
survival::clogit
-
biglm
: The main quantities can be computed, but not the delta method standard errors. See https://github.com/vincentarelbundock/marginaleffects/issues/387
New vignette:
- Elasticity
- Frequently Asked Questions
New features:
- Elasticity and semi-elasticity using the new
slope
argument inmarginaleffects()
: eyex, dyex, eydx -
datagrid()
accepts functions:datagrid(newdata = mtcars, hp = range, mpg = fivenum, wt = sd)
- New
datagridcf()
function to create counterfactual datasets. This is a shortcut to thedatagrid()
function with default togrid_type = "counterfactual"
- New
by
arguments inpredictions()
,comparisons()
,marginaleffects()
- New
newdata
shortcuts: “tukey”, “grid” - New string shortcuts for
transform_pre
incomparisons()
-
marginalmeans()
now back transforms confidence intervals when possible. -
vcov
argument string shortcuts are now case-insensitive - The default contrast in
comparisons()
for binary predictors is now a difference between 1 and 0, rather than +1 relative to baseline. - documentation improvements
marginaleffects 0.6.0
CRAN release: 2022-06-20
New supported packages and models:
-
tidymodels
objects of classtidy_model
are supported if the fit engine is supported bymarginaleffects
.
New function:
-
deltamethod()
: Hypothesis tests on functions of parameters -
plot_cco()
: Plot conditional contrasts
New arguments:
-
hypothesis
for hypothesis tests and custom contrasts -
transform_post
inpredictions()
-
wts
argument inpredictions()
only affects average predictions intidy()
orsummary()
.
New or improved vignettes:
- Hypothesis Tests and Custom Contrasts using the Delta Method: https://vincentarelbundock.github.io/marginaleffects/articles/hypothesis.html
- Multiple Imputation: https://vincentarelbundock.github.io/marginaleffects/articles/multiple_imputation.html
- Causal Inference with the g-Formula: https://vincentarelbundock.github.io/marginaleffects/articles/gformula.html (Thanks to Rohan Kapre for the idea)
Deprecated or renamed arguments:
-
contrast_factor
andcontrast_numeric
arguments are deprecated incomparisons()
. Use a named list in thevariables
argument instead. Backward compatibility is maintained. - The
transform_post
argument intidy()
andsummary()
is renamed totransform_avg
to disambiguate against the argument of the same name incomparisons()
. Backward compatibility is preserved.
Misc:
-
tidy.predictions()
computes standard errors using the delta method for average predictions - Support
gam
models with matrix columns. -
eps
inmarginaleffects()
is now “adaptive” by default: it equals 0.0001 multiplied the range of the predictor variable -
comparisons()
now supports “log of marginal odds ratio” in thetransform_pre
argument. Thanks to Noah Greifer. - New
transform_pre
shortcuts: dydx, expdydx -
tidy.predictions()
computes standard errors and confidence intervals for linear models or GLM on the link scale.
marginaleffects 0.5.0
CRAN release: 2022-05-17
Breaking changes:
-
type
no longer accepts a character vector. Must be a single string. -
conf.int
argument deprecated. Usevcov = FALSE
instead.
New supported packages and models:
mlogit
mhurdle
tobit1
glmmTMB
New features:
-
interaction
argument incomparisons()
to compute interactions between contrasts (cross-contrasts). -
by
argument intidy()
andsummary()
computes group-average marginal effects and comparisons. -
transform_pre
argument can define custom contrasts between adjusted predictions (e.g., log adjusted risk ratios). Available incomparisons()
. -
transform_post
argument allows back transformation before returning the final results. Available incomparisons()
,marginalmeans()
,summary()
,tidy()
. - The
variables
argument of thecomparisons()
function accepts a named list to specify variable-specific contrast types. - Robust standard errors with the
vcov
argument. This requires version 0.17.1 of theinsight
package.-
sandwich
package shortcuts:vcov = "HC3"
,"HC2"
,"NeweyWest"
, and more. - Mixed effects models:
vcov = "satterthwaite"
or"kenward-roger"
- One-sided formula to clusters:
vcov = ~cluster_variable
- Variance-covariance matrix
- Function which returns a named squared matrix
-
-
marginalmeans()
allows interactions - Bayesian Model Averaging for
brms
models usingtype = "average"
. See vignette on themarginaleffects
website. -
eps
argument for step size of numerical derivative -
marginaleffects
andcomparisons
now report confidence intervals by default. - New dependency on the
data.table
package yields substantial performance improvements. - More informative error messages and warnings
- Bug fixes and performance improvements
New pages on the marginaleffects
website: https://vincentarelbundock.github.io/marginaleffects/
- Alternative software packages
- Robust standard errors (and more)
- Performance tips
- Tables and plots
- Multinomial Logit and Discrete Choice Models
- Generalized Additive Models
- Mixed effects models (Bayesian and Frequentist)
- Transformations and Custom Contrasts: Adjusted Risk Ratio Example
Argument name changes (backward compatibility is preserved:
- Everywhere:
-
conf.level
->conf_level
-
-
datagrid()
:-
FUN.factor
->FUN_factor
(same for related arguments) -
grid.type
->grid_type
-
marginaleffects 0.4.1
CRAN release: 2022-03-27
New supported packages and models:
Misc:
-
mgcv::bam
models allowexclude
argument. - Gam models allow
include_smooth
argument. - New tests
- Bug fixes
marginaleffects 0.4.0
CRAN release: 2022-03-13
New function:
-
comparisons()
computes contrasts
Misc:
- Speed optimizations
-
predictions()
andplot_cap()
include confidence intervals for linear models - More robust handling of in-formula functions: factor(), strata(), mo()
- Do not overwrite user’s
ggplot2::theme_set()
call
marginaleffects 0.3.3
CRAN release: 2022-01-26
New supported models:
mclogit::mclogit
robust::lmRob
robustlmm::rlmer
-
fixest
confidence intervals inpredictions
Misc:
- Support
modelbased::visualisation_matrix
innewdata
without having to specifyx
explicitly. -
tidy.predictions()
andsummary.predictions()
methods. - Documentation improvements.
- CRAN test fixes
marginaleffects 0.3.2
CRAN release: 2022-01-18
Support for new models and packages:
Misc:
- Drop
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))) - Bugfixes
- Documentation improvements
- CRAN tests
marginaleffects 0.3.0
CRAN release: 2022-01-08
Breaking changes:
-
predictions
returns predictions for every observation in the original dataset instead ofnewdata=datagrid()
. -
marginalmeans
objects have new column names, as do the correspondingtidy
andsummary
outputs.
New supported packages and models:
brms::brm
rstanarm::stanglm
brglm2::brmultinom
MASS::glmmPQL
aod::betabin
Misc:
-
datagrid
function supersedestypical
andcounterfactual
with thegrid.type
argument. Thetypical
andcounterfactual
functions will remain available and exported, but their use is not encouraged. -
posterior_draws
function can be applied to apredictions
or amarginaleffects
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 frominsight::get_predicted
. - New vignette on Bayesian models with
brms
- New vignette on Mixed effects models with
lme4
- If the
data.table
package is installed,marginaleffects
will automatically use it to speed things up. - Contrast definition reported in a separate column of
marginaleffects
output. - Safer handling of the
type
argument. - Comprehensive list of supported and tests models on the website.
- Many bug fixes
- Many new tests, including several against
emmeans
marginaleffects 0.2.0
CRAN release: 2021-10-18
Breaking change:
-
data
argument becomesnewdata
in all functions.
New supported packages and models:
lme4:glmer.nb
mgcv::gam
ordinal::clm
mgcv
marginalmeans
:
- New
variables_grid
argument
predictions
:
- Support
mgcv
plot_cap
- New
type
argument
Misc:
- New validity checks and tests