Marginaleffects

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.
* Order of some rows in the output may differ when using `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.html
* `REndo`: https://cran.r-project.org/web/packages/REndo/index.html

New:

* `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 request
* `print.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.
* The `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.
- Ex: avg_comparisons(fit, variables = "treatment", newdata = subset(treatment == 1))`
* Better warning for unsupported arguments.
* `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:

* Some results could be mislabelled with factor variables used in combination with `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:

* Uninformative error when a custom `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:

* 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.