4141# ' packages), for instance when using complex formulae in `brms` models, the
4242# ' `predict` argument can take the value of the parameter you want to estimate,
4343# ' for instance `"sigma"`, `"kappa"`, etc.
44- # ' @param marginalize Character string, indicating the type of marginalization.
45- # ' This dictates how the predictions are "averaged" over the non-focal predictors,
46- # ' i.e. those variables that are not specified in `by` or `contrast`.
44+ # ' @param estimate Character string, indicating the type of target population
45+ # ' predictions refer to. This dictates how the predictions are "averaged" over
46+ # ' the non-focal predictors, i.e. those variables that are not specified in
47+ # ' `by` or `contrast`.
4748# ' - `"average"` (default): Takes the mean value for non-focal numeric
4849# ' predictors and marginalizes over the factor levels of non-focal terms,
4950# ' which computes a kind of "weighted average" for the values at which these
5051# ' terms are hold constant. These predictions are a good representation of the
5152# ' sample, because all possible values and levels of the non-focal predictors
5253# ' are considered. It answers the question, "What is the predicted value for
53- # ' an 'average' observation in *my data*?". It refers to randomly picking a
54- # ' subject of your sample and the result you get on average. This approach is
55- # ' the one taken by default in the `emmeans` package.
54+ # ' an 'average' observation in *my data*?". Cum grano salis, it refers to
55+ # ' randomly picking a subject of your sample and the result you get on
56+ # ' average. This approach is the one taken by default in the `emmeans`
57+ # ' package.
5658# ' - `"population"`: Non-focal predictors are marginalized over the observations
5759# ' in the sample, where the sample is replicated multiple times to produce
5860# ' "counterfactuals" and then takes the average of these predicted values
6567# ' your observed sample, but also "what would be if" we had more data, or if
6668# ' we had data from a different sample.
6769# '
68- # ' In other words, the distinction between marginalization types resides in whether
70+ # ' In other words, the distinction between estimate types resides in whether
6971# ' the prediction are made for:
7072# ' - A specific "individual" from the sample (i.e., a specific combination of
7173# ' predictor values): this is what is obtained when using [`estimate_relation()`]
7274# ' and the other prediction functions.
7375# ' - An average individual from the sample: obtained with
74- # ' `estimate_means(..., marginalize = "average")`
76+ # ' `estimate_means(..., estimate = "average")`
7577# ' - The broader, hypothetical target population: obtained with
76- # ' `estimate_means(..., marginalize = "population")`
78+ # ' `estimate_means(..., estimate = "population")`
7779# ' @param backend Whether to use `"emmeans"` or `"marginaleffects"` as a backend.
7880# ' Results are usually very similar. The major difference will be found for mixed
7981# ' models, where `backend = "marginaleffects"` will also average across random
8486# ' `options(modelbased_backend = "emmeans")` to use the **emmeans** package or
8587# ' `options(modelbased_backend = "marginaleffects")` to set **marginaleffects**
8688# ' as default backend.
87- # ' @param transform Deprecated, please use `predict` instead.
89+ # ' @param transform A function applied to predictions and confidence intervals
90+ # ' to (back-) transform results, which can be useful in case the regression
91+ # ' model has a transformed response variable (e.g., `lm(log(y) ~ x)`). For
92+ # ' Bayesian models, this function is applied to individual draws from the
93+ # ' posterior distribution, before computing summaries. Can also be `TRUE`, in
94+ # ' which case `insight::get_transformation()` is called to determine the
95+ # ' appropriate transformation-function.
8896# ' @param verbose Use `FALSE` to silence messages and warnings.
8997# ' @param ... Other arguments passed, for instance, to [insight::get_datagrid()],
9098# ' to functions from the **emmeans** or **marginaleffects** package, or to process
93101# ' to control the (number of) representative values.
94102# ' - **marginaleffects**: Internally used functions are `avg_predictions()` for
95103# ' means and contrasts, and `avg_slope()` for slopes. Therefore, arguments
96- # ' for instance like `vcov`, `transform`, `equivalence` or `slope` can be
97- # ' passed to those functions.
104+ # ' for instance like `vcov`, `transform`, `equivalence`, `slope` or even
105+ # ' `newdata` can be passed to those functions.
98106# ' - **emmeans**: Internally used functions are `emmeans()` and `emtrends()`.
99107# ' Additional arguments can be passed to these functions.
100108# ' - Bayesian models: For Bayesian models, parameters are cleaned using
@@ -172,30 +180,39 @@ estimate_means <- function(model,
172180 by = " auto"
173181 predict = NULL ,
174182 ci = 0.95 ,
175- marginalize = " average"
176- backend = getOption(" modelbased_backend" " marginaleffects"
183+ estimate = " average"
177184 transform = NULL ,
185+ backend = getOption(" modelbased_backend" " marginaleffects"
178186 verbose = TRUE ,
179187 ... ) {
180- # # TODO: remove deprecation warning later
181- if (! is.null(transform )) {
182- insight :: format_warning(" Argument `transform` is deprecated. Please use `predict` instead."
183- predict <- transform
184- }
185-
186188 # validate input
187- marginalize <- insight :: validate_argument(
188- marginalize ,
189+ estimate <- insight :: validate_argument(
190+ estimate ,
189191 c(" average" " population" " specific"
190192 )
191193
192194 if (backend == " emmeans"
193195 # Emmeans ------------------------------------------------------------------
194- estimated <- get_emmeans(model , by = by , predict = predict , verbose = verbose , ... )
196+ estimated <- get_emmeans(
197+ model ,
198+ by = by ,
199+ predict = predict ,
200+ verbose = verbose ,
201+ ...
202+ )
195203 means <- .format_emmeans_means(estimated , model , ci = ci , verbose = verbose , ... )
196204 } else {
197205 # Marginalmeans ------------------------------------------------------------
198- estimated <- get_marginalmeans(model , by = by , predict = predict , ci = ci , marginalize = marginalize , verbose = verbose , ... ) # nolint
206+ estimated <- get_marginalmeans(
207+ model ,
208+ by = by ,
209+ predict = predict ,
210+ ci = ci ,
211+ estimate = estimate ,
212+ transform = transform ,
213+ verbose = verbose ,
214+ ...
215+ )
199216 means <- format(estimated , model , ... )
200217 }
201218
@@ -204,13 +221,13 @@ estimate_means <- function(model,
204221
205222 # Table formatting
206223 attr(means , " table_title" <- c(ifelse(
207- marginalize == " specific"
224+ estimate == " specific"
208225 " Model-based Predictions"
209226 " Estimated Marginal Means"
210227 ), " blue"
211228 attr(means , " table_footer" <- .table_footer(
212229 means ,
213- type = ifelse(marginalize == " specific" " predictions" " means"
230+ type = ifelse(estimate == " specific" " predictions" " means"
214231 by = info $ by ,
215232 model = model ,
216233 info = info
0 commit comments