MASS::polr(), ordinal::clm() or
ordinal::clmm()), estimate_contrasts() and estimate_slopes() with
backend = "emmeans" now return probabilities by default and for
predict = "response", as estimate_means() already does. Contrasts compare
the focal levels within each response category, and slopes are the slopes of
the probability of each response category. Before, both returned values on
the latent scale, and the table footer of estimate_contrasts() said they
were on the response scale. The ordinal modes of emmeans ("prob",
"cum.prob", "exc.prob", "linear.predictor", "latent" and
"mean.class") can be passed to predict. Use predict = "latent" to get
the former results.Post-processing in estimate_contrasts() including group-variable (e.g.,
post_process = ~ pairwise | group_var) now no longer prints levels from
group_var in both the group and comparison columns (i.e. redundant labels
have been removed from the output).
estimate_contrasts() with custom comparisons (e.g., when
comparison = "(b1 - b12) = (b4 - b18)") can yield incorrect results when
estimate = "average" and predictions are filtered (e.g. when
contrast = c("x=c(2,4)")). This does not happen in general, but may happen.
Therefore, now an informative warning is printed in such edge-cases.
Added a new vignette, "The Modelisation Approach", which demonstrates a complete analytical workflow from setting up models using DAGs to extracting meaningful predictions, slopes, and interaction contrasts using modelbased post-estimation functions.
estimate_means() with backend = "emmeans" now supports ordinal models,
e.g. from MASS::polr() or ordinal::clm(). predict accepts the ordinal
modes of emmeans ("prob", "cum.prob", "exc.prob",
"linear.predictor", "latent" and "mean.class"). For "prob", the
output has one row per response category, in a Response column. For
"cum.prob", "exc.prob" and "linear.predictor", the output has one row
per threshold, in a Threshold column. For ordinal models, the default is
now predict = "prob", which returns the same probabilities as the
"marginaleffects" backend.
For ordinal models, plot() of estimate_means() output with
backend = "emmeans" now maps the Response or Threshold column to the
color with one by variable and to the facets with more. The
"marginaleffects" backend already does this for Response.
With backend = "emmeans", plot() now shows predicted probabilities on a
percent y-axis, "cum.prob" and "exc.prob" included. This applies to
binomial, beta, ordinal, and multinomial models.
comparison = "ratio" is a new shortcut to compute pairwise comparisons
as ratios.
The printed footer of estimate_prediction() and similar functions now
names prediction intervals as such (#485).
estimate_means(), estimate_contrasts() and estimate_slopes() now
filter the response categories of ordinal models, for example from
MASS::polr(), ordinal::clm() or ordinal::clmm(). The filter is a by
term that names the response with values, for example
by = c("Infl", "Sat = 'Low'"). The output then has only the rows of these
response categories. The filter works with backend = "emmeans" and
predict = "prob" (the default). Before, means and contrasts of factors
ignored the filter, and slopes and contrasts of slopes stopped with an
unclear error. If predict has another value, these functions now stop with
a clear error. If a value is not a response category, they also stop with an
error.
For non-linear models, the footer of predictions or contrasts on the
link-scale no longer says "FALSE-transformed" or "TRUE-transformed". This
footer appears, for example, with estimate_link(), or with
estimate_means() and predict = "link". Without transform, the footer
now says "link-scale". Except with backend = "emmeans", a function as
transform gives "transformed link-scale". estimate_contrasts() with
predict = "link" and a function as transform (for example
transform = exp) no longer fails with an error. If the output of an
earlier call is the data argument, the footer of estimate_expectation(),
estimate_prediction() and estimate_link() now names the right scale.
With backend = "marginaleffects", estimate_means(), estimate_slopes()
and estimate_contrasts() no longer drop or rename a by variable with a
name such as type, n or value. They also no longer mislabel other
columns because of such a name. Before, for example, estimate_means()
dropped a by variable named type and renamed n to n_Obs. It also
labeled a variable named Median as Mean, and the means as Coefficient.
This fix does not yet apply to Bayesian models or to inequality comparisons
(for example comparison = "inequality").
Fixed printing error for brms-Wiener models without component column.
With backend = "marginaleffects", a by variable with the name of the
estimate column (for example Mean) or of the t column is now returned as
<name>.1. The output column keeps its name. This also holds for p
with estimate_slopes() and estimate_contrasts(), and for SE, CI_low
and CI_high with estimate_slopes(). Before, for example,
estimate_means() kept a by variable named Mean and renamed the means
to Mean.1, and estimate_contrasts() renamed the p-values to p.1. As
for the fix above, this does not yet apply to Bayesian models or to
inequality comparisons. It also does not apply to estimate_contrasts() on
the output of estimate_relation().
With backend = "marginaleffects", estimate_means(),
estimate_contrasts() and estimate_slopes() now stop with an informative
error when a variable has a name that marginaleffects uses for its own
columns, and ask users to rename the variable. Before, these names gave
wrong estimates, standard errors or confidence intervals, missing columns,
or unclear errors. The names are:
by variables of estimate_means(), and of estimate_contrasts() when
the contrast variable is a factor: Predicted, SE, CI_low, CI_high,
df, rowid and s.value.contrast variable of estimate_contrasts(): SE, CI_low,
CI_high, df and rowid.estimate_means() and estimate_contrasts(): SE,
CI_low, CI_high and df.by variables of estimate_slopes(): df, rowid, s.value,
predicted, predicted_hi and predicted_lo.Bayesian models are not checked yet. For them, these names can still give missing columns or unclear errors.
With backend = "marginaleffects", estimate_contrasts() now returns a
by variable named Level1 or Level2 as Level1.1 or Level2.1, next
to the Level1 and Level2 columns of the contrasts. It also returns the
contrasts for a by variable named hypothesis and for a contrast
variable named Parameter. Before, the output had two columns with the same
name, the contrast labels were not split into Level1 and Level2, or the
call failed with an unclear error. If <name>.1 is already a variable name,
the suffix is the next free number, for example p.2. As for the fixes
above, the Level1, Level2 and hypothesis fixes do not yet apply to
Bayesian models or to inequality comparisons.
If a variable has the name of an output column, estimate_contrasts() and
estimate_slopes() with backend = "marginaleffects" now keep the values
and the order of that column. This applies to the contrast variable, and
to by variables of contrasts and of contrasts of slopes. It also applies to
by variables of contrasts with a custom comparison, for example
comparison = "b2=b1". Before, a contrast variable named t turned the
t column into a factor. A contrast variable named p replaced the
p-values with missing values and moved the p column to the front. In
contrasts, a by variable named Slope gave two Difference columns. In
contrasts of slopes, it replaced the differences with missing values. With
comparison = "ratio", a by variable named Ratio or Slope gave two
Ratio columns. Now a by variable named Ratio becomes Ratio.1 there.
estimate_slopes() with backend = "marginaleffects" now adjusts the
p-values for p_adjust = "holm", "hochberg", "hommel", "bonferroni",
"BH", "BY", "fdr", "sidak" and "tukey". Before, all but "tukey"
failed with the error "replacement has 0 rows", and "tukey" returned the
unadjusted p-values. For "tukey", estimate_slopes() and
get_marginaltrends() now use the Sidak adjustment and say so in a message.
The Tukey adjustment is only appropriate for pairwise comparisons, but these
slopes are each tested against 0. emmeans::test() makes the same
substitution. Slopes that are compared, for example with the comparison
or post_process argument, keep the Tukey adjustment.
estimate_means() with backend = "emmeans" now shows the response level
names for models from ordinal::clmm(). Before, the Response column showed
1, 2, 3, and the Threshold column showed 1|2, 2|3.
Fixed issue in estimate_contrasts() with wrong assignment of estimates in
custom comparisons (e.g., when comparison = "(b1 - b12) = (b4 - b18)"),
when some of the indexed coefficients contained the same digit (in this case,
1 in b1 and b12).
Fixed issues in offset handling when the offset was specified via the offset
argument in the model call instead of inside the formula.
Fixed issues with using offsets and predicting grand mean (i.e. when model
contains offset and by = NULL).
plot() now gives an informative error when there is nothing to put on the
x-axis, e.g. for predictions from intercept-only models, or for
estimate_prediction() without the by argument.
Fixed an "invalid regular expression" error in estimate_contrasts() for
multivariate models (for example from brms) with many observations.
estimate_contrasts() now uses the names of the response variables, not
their observed values, to find the response in the contrast labels.
estimate_contrasts() now returns separate Response1 and Response2
columns for multivariate brms models with dots in the response names, for
example mvbind(Sepal.Length, Petal.Length) ~ Species. Before, the response
names stayed in the Level1 and Level2 columns, because brms removes the
dots from the response names.
The grid argument of visualisation_recipe() and plot() now changes the
facet grid of plots with four or more by variables. Before, these functions
applied the facet argument to the facet grid instead. If facet was not
set, grid gave an error.
comparison argument in estimate_contrasts() for backend = "emmeans"
now defaults to "revpairwise", to return consistent results regarding the
sign of contrasts with the "marginaleffects" backend.For contrasts of models where predictions vary by response category
(e.g., categorical, ordinal/cumulative or multinomial models, as well as
multivariate response models), estimate_contrasts() now returns separate
Response1 and Response2 columns instead of merging the response
category label into the Level1 and Level2 columns (#646).
The iterations argument can now also be used for Bayesian model in
estimate_means(), estimate_slopes(), and estimate_contrasts(), which
is then passed to the ndraws argument and controls how many samples are
drawn from the posterior when calculating marginal means, effects or contrasts.
ci = NULL now suppresses calculation of standard errors and confidence
intervals.
The data argument can be used as an alias for newdata in estimate_means(),
estimate_slopes(), and estimate_contrasts(), and is passed to the related
marginaleffects functions.
Improved default settings for plots using tinyplot():
facets now automatically remove redundant axes. If you prefer to keep them,
you can simply enable them by setting frame = TRUE.xlim to c(0.5, n + 0.5), the geoms are moved closer
together, resulting in a more compact appearance.tinyplot() for modelbased objects now supports standard arguments following
easystats conventions, allowing for more fine-grained plot customizations
(e.g., text/line sizes, color palettes, and axis title sizes).
New options for printing (in particular, formatting CIs), see also documentation
(?modelbased::"modelbased-options").
Improved documentation for estimate_means() and vignettes about technical
details of marginalization.
estimate_contrasts() with backend = "emmeans" now correctly parses factor
levels that contain " - " in their names (e.g., "A - High", "B - Low").
emmeans wraps such levels in parentheses (e.g., "(A - Low) - (A - High)"),
which is now handled properly (#649).
Fixed issue with estimate = "average" in estimate_slopes() when no by
variable was specified and therefore no data grid created. This caused an
issue with filtering the output.
Informative error message when the trend variable in estimate_slopes() is
not numeric and backend = "emmeans".
estimate_contrasts() gets a post_process argument, to process subsequent
comparisons. It allows for complex, multi-step comparisons.
The comparison argument in estimate_contrasts() can now also be "omnibus",
to calculate a global omnibus test for differences between levels of a
predictor.
Offsets (using the offset argument) now also work when estimate is set to
"population" or "average".
Argument slope, when specific values are defined, can now also be a list
instead of only a string. E.g., slope="<variable> = seq(1, 3, 0.1)" can now
also be written as slope=list(<variable> = seq(1, 3, 0.1)).
Clarified usage of marginal group-level estimates in estimate_grouplevel().
The type argument can now be used in combination with the estimate argument,
which is now also more explained in detail in the documentation.
by = NULL now also works for backend = "emmeans", to predict the grand mean.
Minor bug fix when evaluating slope and by arguments in estimate_slopes().
get_emcontrasts(), get_emmeans() and get_emtrends() (i.e., functions
using backend = "emmeans") now give an informative error message when
by, contrast, or trend refer to a variable that is only used as random
effects grouping factor (e.g., Subject in (1 | Subject)), instead of failing
with a cryptic error. Such variables can only be used with
backend = "marginaleffects".
join_dots in the plot() method, which is used to connect dots
with lines, now defaults to FALSE.Support for models of class nestedLogit.
estimate_contrasts() can now also calculate contrasts of average slopes, by
defining two numeric predictors in the contrast argument. This can also be
useful when estimating the context effects of within- and between-effects in a
model.
The trend argument in estimate_slopes() was renamed into slope. trend
will remain as alias.
New function collapse_by_group(), which extracts the raw data points and
"averages" (i.e. "collapses") the response variable over the levels of the
grouping factor given in collapse_by. Only works with mixed models.
Additionally, the plot() and visualization_recipe() methods get a
collapse_group argument to use this feature when adding data points to plots
using show_data or show_residuals.
Fixed issue in estimate_slope() when p_adjust = "esarey".
Fixed issue in estimate_contrasts() when p_adjust = "tukey".
Fixed error with truncated message when standard errors could not be calculated.
The type argument in estimate_grouplevel() gains a "marginal" option,
to return marginal group-levels estimates.
Added an as.data.frame() method for modelbased objects.
Better formatting of the output for equivalence-tests, when the equivalence
argument was used. Related docs were added. It is also possible to use
parameters::equivalence_test() on modelbased objects.
Function calls are now saved as call attribute in modelbased objects.
More informative warnings and error messages were added to estimate_contrasts()
when computing effect sizes.
Improved plotting methods for the tinyplot package. The related vignette was also updated.
Methods for the tinyplot package were added.
estimate_slopes() now also gets the estimate argument, to specify how to
estimate / marginalize over non-focal terms.
Improvements to estimate_contrasts():
comparison = "inequality" now also works when contrasting slopes for a
numeric predictor.
New option comparison = "inequality_ratio" for estimate_contrast(),
which computes the ratio of marginal effects inequality measures across
groups.
For contrasts, the message about the units of contrasts ("in %-points") has been removed, because this was slightly misleading. The units were in %-points if multiplied by 100, but this multiplication was not done in the output.
estimate_contrasts() for slopes now allows additional grouping of contrasts
using the by argument together with the comparison argument by specifying
the grouping variable in the formula, e.g. contrast = c("x", "group") and
~ pairwise | group.
estimate_expectation() and estimate_relation() now support objects of
class htest.
estimate_grouplevel() now supports models from package coxme.
New function residualize_over_grid(), which residualizes a model
over a grid of predictors. This is useful to visualize the residuals of a
model over a grid of predictors.
visualisation_recipe() and plot() get a show_residuals argument,
to show the residuals of the model, related to the data grid, in the plot.
Documentation of the display() method for modelbased objects has been
added.
Improved documentation and improved informative messages.
Message about unreliable standard errors (for certain models, when predicting random effects) was removed for now, as it is uncertain whether the standard errors were unreliable.
Modified code base to address changes in the marginaleffects package from version 0.29.0 onwards.
Fixed issue with by in estimate_contrasts() when comparison was
"inequality".
Some comparison options, like "helmert" or "poly", could not be specified
as string-value, only as formula. This has been fixed, so they can now be
specified as string-value, too.
In-formula transformations of predictors in by could not be handled when
by was not specified. This has been fixed, and automatic detection of by
variables now also works with in-formula transformations.
The comparison argument gets two new option, "inequality" and
"inequality_pairwise", to compute the marginal effects inequality measure,
which summarizes the the overall effect of categorical predictors or the
comprehensive effect of a predictor across all outcome categories of a nominal
or ordinal dependent variable.
Added docs to show how to use modelbased with finite mixture models from package brms.
Improved support for finite mixture models (currently only the mixture()
family for model from package brms are supported).
Improved printing for joint-tests with backend = "emmeans".
Improved handling when p-adjustment methods that are only available in the emmeans package were used for the marginaleffects backend.
The column header for the predicted values in estimate_means() for
multinomial models from packages nnet and brglm2 has been changed to
Probability, to better reflect the scale of the predictions.
New vignettes (Case Studies) about using modelbased with finite mixture models and interrupted time series analysis.
The p_adjust argument gets a new option, "sup-t", to calculate
simultaneous confidence intervals.
Added a display() method for modelbased objects.
Fixed printing and plotting for models from packages nnet and brglm2.
Fixed issues with object of class aov.
Fixed issue with the plot() method for estimate_slopes() for Bayesian
models.
estimate_contrasts() for results from estimate_relation() and alike is
now more efficient for larger number of contrasts.
Updated information of citation(). If you want to cite the modelbased
package, please use the JOSS publication as reference
(https://joss.theoj.org/papers/10.21105/joss.07969).
estimate_contrasts() for results from
estimate_relation().The comparison argument can now also be a custom function, or a matrix
(e.g., to define contrasts).
The comparison argument can now also be "joint", to jointly test
hypotheses (i.e. conducting a joint test) in factorial designs.
New vignette about user-defined contrasts and joint tests in
estimate_contrasts().
pool_slopes(), to pool results from estimate_slopes() applied to
imputed data.reshape_grouplevel() now takes the correct number of specified random effects
groups into account when reshaping results.In general, it is now possible to make estimate means, contrasts and slopes
for distributional parameters for models from package brms using the
predict argument.
estimate_grouplevel() gets arguments test, dispersion and diagnostic,
that are internally passed to parameters::model_parameters(), but with
different defaults.
estimate_prediction() and estimate_relation() now support Wiener-models
(Drift Diffusion Models) from package brms.
estimate_prediction(), estimate_relation() and similar functions now
include the Row column for models with ordinal or categorical response
variables when the data argument was provided.
estimate_slopes() can now also calculate average marginal effects of a
predictor, just for the trend of that predictor within a certain range of
values.
estimate_slopes() gets a predict argument, to either select the scale
of the estimates slopes, or to estimate slopes (marginal effects) for
distributional parameters of brms models.
estimate_contrasts() gives an informative error message when arguments
by and contrast have identical variables (which does not work).
Column names of predicted values for backend = "emmeans" has changed for
models like logistic regression, or beta regression. Formerly, name was
Mean, now it is Probability or Proportion, depending on the model.
Exposed iterations argument in estimate_prediction() and estimate_relation().
Option estimate = "average no longer prints information on averaged predictors
in the footer, because strictly, the predictions are averaged over, and not
the non-focal variables.
Better handling for models with offsets in estimate_means() and
estimate_contrasts(). Informative messages are given when models include
offset terms, and it is possible to fix the offset value using the offset
argument. The offset argument is also available for estimate_relation(),
estimate_prediction() and similar.
For consistency, estimate_slopes() now also uses the residual degrees of
freedom by default (like estimate_means()) when calculating confidence
intervals and p-values.
Minor improvements to the documentation.
Fixed issues in estimate_grouplevel() for models from package rstanarm.
Fixed issues in calculating correct confidence intervals (and possibly p-values)
for pooling functions pool_parameters() and pool_predictions().
Fixed issue in estimate_means() for multivariate response models from
package brms.
Fixed issue with wrong y-axis label for plots from estimate_slopes().
Fixed issue with weights in estimate_relation().
Fixed issue in printed output for the statistic column, which should be z
for the marginaleffects backend, when argument df = Inf.
The deprecated function visualisation_matrix() has been removed. Use
insight::get_datagrid() instead.
The "average" option for argument estimate was renamed into "typical".
The former "average" option is still available, but now returns marginal
means fully averaged across the sample.
The transform argument now also works for estimate_slopes() and for
estimate_contrasts() with numeric focal terms.
estimate_contrasts() no longer calls estimate_slopes() for numeric focal
terms when these are integers with only few values. In this case, it is assumed
that contrasts of values ("levels") are desired, because integer variables with
only two to five unique values are factor-alike.
estimate_contrasts: now supports optional standardized effect sizes, one of
"none" (default), "emmeans", or "bootES" (#227, @rempsyc).
The predict() argument for estimate_means() gets an "inverse_link" option,
to calculate predictions on the link-scale and back-transform them to the
response scale after aggregation by groups.
estimate_means(), estimate_slopes() and estimate_contrasts() get a
keep_iterations argument, to keep all posterior draws from Bayesian models
added as columns to the output.
New functions pool_predictions() and pool_contrasts(), to deal with
modelbased objects that were applied to imputed data sets. E.g., functions
like estimate_means() can be run on several data sets where missing values
were imputed, and the multiple results from estimate_means() can be pooled
using pool_predictions().
The print() method is now explicitly documented and gets some new options
to customize the output for tables.
estimate_grouplevel() gets a new option, type = "total", to return the
sum of fixed and random effects (similar to what coef() returns for (Bayesian)
mixed models).
New option "esarey" for the p_adjust argument. The "esarey" option is
specifically for the case of Johnson-Neyman intervals, i.e. when calling
estimate_slopes() with two numeric predictors in an interaction term.
print_html() and print_md() pass ... to format-methods (e.g. to
insight::format_table()), to tweak the output.
The show_data argument in plot() is automatically set to FALSE when
the models has a transformed response variable, but predictions were not
back-transformed using the transform argument.
The plot() method gets a numeric_as_discrete argument, to decide whether
numeric predictors should be treated as factor or continuous, based on the
of unique values in numeric predictors.
Plots now use a probability scale for the y-axis for models whose response scale are probabilities (e.g., logistic regression).
Improved printing for estimate_contrasts() when one of the focal predictors
was numeric.
Fixed issue in the summary() method for estimate_slopes().
Fixed issues with multivariate response models.
Fixed issues with plotting ordinal or multinomial models.
Fixed issues with ci argument, which was ignored for Bayesian models.
Fixed issues with contrasting slopes when backend was "emmeans".
Fixed issues in estimate_contrasts() when filtering numeric values in by.
Fixed issues in estimate_grouplevel().
Fixed issue in estimate_slopes() for models from package lme4.
The default package used for estimate_means(), estimate_slopes() and
estimate_contrasts() is now marginaleffects. You can set your preferred
package as backend using either the backend argument, or in general by setting
options(modelbased_backend = "marginaleffects") or
options(modelbased_backend = "emmeans").
Deprecated argument and function names have been removed.
Argument fixed has been removed, as you can fix predictor at certain values
using the by argument.
Argument transform is no longer used to determine the scale of the predictions.
Please use predict instead.
Argument transform is now used to (back-) transform predictions and confidence
intervals.
Argument method in estimate_contrasts() was renamed into comparison.
All model_*() alias names have been removed. Use the related get_*()
functions instead.
The show_data argument in plot() defaults to FALSE.
The "marginaleffects" backend is now fully implemented and no longer
work-in-progress. You can set your preferred package as backend using
either the backend argument, or in general by setting
options(modelbased_backend = "marginaleffects") or
options(modelbased_backend = "emmeans").
All estimate_*() functions get a predict argument, which can be used
to modulate the type of transformation applied to the predictions (i.e. whether
predictions should be on the response scale, link scale, etc.). It can also
be used to predict auxiliary (distributional) parameters.
estimate_means() and estimate_contrasts() get a estimate argument,
to specify how to estimate over non-focal terms. This results in slightly
different predicted values, each approach answering a different question.
estimate_contrasts() gains a backend argument. This defaults to
"marginaleffects", but can be set to "emmeans" to use features of that
package to estimate contrasts and pairwise comparisons.
estimate_expectation() and related functions also get a by argument, as
alternative to create a datagrid for the data argument.
Many functions get a verbose argument, to silence warnings and messages.
estimate_contrasts() did not calculate contrasts for all levels when the
predictor of interest was converted to a factor inside the model formula.
Fixed issue in estimate_contrasts() when comparsison (formerly: method)
was not "pairwise".
3.6.Fixed issues with printing-methods.
Maintenance release to fix failing tests in CRAN checks.
visualisation_matrix() has now become an alias (alternative name) for the get_datagrid() function, which is implemented in the insight package.API changes: levels in estimate_contrasts has been replaced by contrast.
levels and modulate are in general aggregated under at.
estimate_prediction() deprecated in favour of estimate_response().
estimate_expectation() now has data=NULL by default.
General overhaul of the package.
Entire refactoring of visualisation_matrix().
Option of standardizing/unstandardizing predictions, contrasts and means is
now available via standardize() instead of via options.
Introduction of model_emmeans() as a wrapper to easily create emmeans
objects.
estimate_smooth() transformed into describe_nonlinear() and made more
explicit.
estimate_link() now does not transform predictions on the response scale
for GLMs. To keep the previous behaviour, use the new estimate_relation()
instead. This follows a change in how predictions are made internally (which
now relies on
get_predicted(),
so more details can be found there).Predicted is now the name of the predicted column for Bayesian models
(similarly to Frequentist ones), instead of the centrality index (e.g.,
Median).estimate_slope() now gives an informative error when no numeric predictor is
present.Partial support of formulas.
Refactor the emmeans wrapping.
parameters
package update.NEWS.md file to track changes to the package