Marginaleffects

Breaking change:

* Row orders are now more consistent, but may have changed from previous version. This could affect results from `hypothesis` with `b1`, `b2`, ... indexing.

Support new models:

* `nlme::lme()`
* `phylolm::phylolm()`
* `phylolm::phyloglm()`

New:

* Vignette on 2x2 experimental designs. Thanks to Demetri Pananos.
* `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.
* Incorrect label for "2sd" comparisons. Thanks to Andy Milne for report 720.
* Invalid factor levels in `datagrid()` means `newdata` argument gets ignored. Thanks to Josh Errickson for report 721.
* Error in models with only categorical predictors and the `by` argument. Thanks to Sam Brilleman for report 723.
* Elasticities are now supported for `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` -> `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()` and `glm()` models using `RcppEigen`.
* 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()` 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.
* Blank graphs in `plot_comparisons()` with a list in `variables`.
* `type="link"` produced an error with some categorical `brms` models. Thanks to shirdekel for report 703.
* Error on `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:

* 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 in `plot_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 to `variables` in `plot_slopes()` and `plot_comparisons()`. This improves consistency with the analogous `slopes()` and `comparisons()` 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 in `marginal_means()` is renamed `newdata`. Backward compatibility is maintained.
* `avg_*()` returns an informative error when `vcov` is "satterthwaite" or "kenward-roger"
* "satterthwaite" and "kenward-roger" are now supported when `newdata` is not `NULL`
* Informative error when `hypothesis` includes a `b` larger than the available number of estimates.
* `avg_predictions(model, variables = "x")` computes average counterfactual predictions by subgroups of `x`
* `datagrid()` and `plot_*()` functions are faster in datasets with many extraneous columns.
* In `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.
* 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 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:
- Print fewer significant digits.
- `print.marginaleffects` now prints all columns supplied to `newdata`
- 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 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:

* All functions return an `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.
* The `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:

* New functions: `avg_predictions()`, `avg_comparisons()`, `avg_slopes()`
* Equivalence, non-inferiority, and non-superiority tests with the `hypotheses()` function and `equivalence` argument.
* New experimental `inferences()` function: simulation-based inferences and bootstrap using the `boot`, `rsample`, and `fwb` 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()`, and `summary()`: `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_*()` the `threenum` and `minmax` 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()`

* `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"
* Added support for `mlm` models from `lm()`. Thanks to Noah Greifer.

Bug fixes:

* `hypothesis` argument with bayesian models and `tidy()` used to raise an error.
* Missing values for some regressors in the `comparisons()` output for `brms` models.

Breaking change:

* The `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::ols`
* `rms::lrm`
* `rms::orm`

New features:

* Plots: `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:
- 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 the `comparisons` function.
* `variables` argument of the `predictions()` 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` in `summary()` and `tidy()` is now `NULL`, which inherits the `conf_level` value in the original `comparisons`/`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 using `deltamethod()`. 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 for `deltamethod()`, `marginaleffects()`, etc.
* Fixed a bug in the `tidy()` function for `glmmTMB` models without random effects, which caused all t statistics to be identical.