Marginaleffects

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:

* Better warning messages for unsupported matrix columns, enhancing user experience and troubleshooting.
* Various improvements to documentation.
* Typos
* Repository hosts model objects for easier testing.

Bug fixes:

* Error on `hypotheses(joint = "string")` for `comparisons()` objects (no result was returned). Thanks to BorgeJorge for report 981.
* Enhanced support for multi-equation Bayesian models with `brms` models. Thanks to winterstat for report 1006.
* Parameter names with spaces could break standard errors. Thanks to Lefty2021 for report 1005.

Breaking changes:

* The `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.
* The `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=dbarts
* `mvgam`: 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=rms

Misc:

* `comparisons()`: The `variables` argument now accepts functions and data frames for factor, character, and logical variables.
* Deprecation warning for: `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 961
* Custom functions in the `comparison` 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.
* Add support for two facet variables (through `facet_grid`) when plotting using `condition`
* `comparisons()`: 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.
* Superfluous warning with `fixest::fenegbin`.

Machine learning support:

* `tidymodels` package
* `mlr3` package

Misc:

* New vignettes:
- Inverse Probability Weighting
- Machine Learning
- Matching
* Add support for `hypotheses()` to `inferences()`. Thanks to Tristan-Siegfried for code contribution 908.
* Support `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.
* The function supplied to the `comparison` argument of the `comparisons()` function can now operate on `x` and on `newdata` directly (e.g., to check the number of observations).
* More informative errors from `predict()`.

Bugs:

* Some `gamlss` models generated an error related to the `what` argument. Thanks to DHLocke for Issue 933

* `hypotheses()`: The `FUN` argument handles `group` columns gracefully.
* Native support for `Amelia` for multiple imputation.

Documentation:

* New section on "Complex aggregations" in the Hypothesis testing vignette.

Bug fix:

* Results of the `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 [903](https://github.com/vincentarelbundock/marginaleffects/issues/903)

New:

* Conformal prediction via `inferences()`
* `hypothesis` argument now accepts multiple string formulas.
* The `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.
* Allow install with Rcpp 1.0.0 and greater.

Support new models:

* `survey::svyolr()`

Misc:

* `inferences(method="simulation")` uses the original point estimate rather than the mean of the simulation distribution. Issue 851.
* Better documentation and error messages for `newdata=NULL`
* Some performance improvements for `predictions()` and `marginalmeans()` (880, 882, etiennebacher).

Bug fix:

* `newdata="median"` returned mean of binary variables. Thanks to jkhanson1970 for report 896.

Breaking changes:

* Row order of the output changes for some objects. Rows are not sorted alphabetically by `term`, `by`, and variables explicitly supplied to `datagrid`. This can affect hypothesis tests computed using the b1, b2, b3, and other indices.
* New procedure `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:

* Support: `logistf` package.
* Support: `DCchoice` package.
* Support: `stats::nls`
* `hypotheses()` 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 853
* Inaccurate averaging with `comparison=differenceavg` some models where all predictors are categorical. Thanks to Karl Ove Hufthammer for report 865.

Misc:

* Major refactor to simplify the code base and make maintenance easier.