Rename argument `marginalize` and its options

[strengejacke]

@mattansb @DominiqueMakowski

Oh, now I get it - this isn't about averaging really, averaging is sometimes used, but it's about what units are the estimates generated (and then possibly averaged across).

So how about:

marginalize = "specific" -> estimate_over = "individual" (for a single unit)
marginalize = "average" -> estimate_over = "average" (for an average unit / average across marginal means)
marginalize = "population" -> estimate_over = "population" (for average across all units in a sample)

Or estimate_for= / over=

Originally posted by @mattansb in #332 (comment)

[strengejacke]

I personally like this option:

• estimate_for = "individual" (for a single unit)
• estimate_for= "average" (for an average unit / average across marginal means)
• estimate_for = "population" (for average across all units in a sample)

(and we should probably mention in the docs that this argument only has an effect when there are non-focal factors - if we have no non-focal terms, results are the same (not for mixed models, but the grouping variable in the random effects can then be considered as "non-focal term"))

[strengejacke]

@bwiernik What do you think about possible argument names and their options as native speaker?

The above discussed options, which are/will become an argument in the estimate_means() and estimate_contrasts() functions, do following:

• estimate_for = "individual" for a single unit, returns results like you get from predict(newdata = ...).
• estimate_for= "average" for an average unit / average across marginal means, returns results like the emmeans-default, or marginaleffects with balanced grid
• estimate_for = "population" for average across all units in a sample, returns counterfactual predictions, i.e. like avg_predictions(variables = ...).

[mattansb]

Yes, I like this (:

[bwiernik]

Not sure about "average" and "population". Thinking about it

[strengejacke]

We develop an R package that calculates estimated marginal means from statistical models. The results are estimates average values of the outcome for specified predictor levels (focal terms) and refer to a certain population. Based on how to marginalize, or average over those predictors that are not of interest (non-focal terms), the estimated average response value can either refer to a very specific individual, an average individual of the sample, or are counterfactual predictions that refer to a hypothesized population. How would you name a function argument that modulates this "averaging" or "marginalization", and how would you name the three described options?

[strengejacke]

(btw, the kids today call "Gemini" "fake chatGPT" - chatGPT is the name standing for gAI)

[strengejacke]

Here are the chatGPT results:

[strengejacke]

Aaaaaand scite.ai:

In the context of estimating expected values of the response for different target populations, it is essential to choose a function argument name that clearly reflects the entity for which the outcome is being estimated. This clarity is crucial for users to understand the functionality of the R package and to facilitate accurate application in statistical modeling.

In developing an R package that calculates estimated marginal means (EMMs) from statistical models, it is crucial to provide clear and intuitive naming conventions for function arguments and options. This not only enhances usability but also improves the clarity of the package's functionality. Below, I will propose a naming convention for the function argument that modulates the "averaging" or "marginalization" process, as well as the three distinct options for the type of marginalization.

Alternative Names for the Function Argument

1. target_population: This name emphasizes that the estimates are specific to a defined population group. It conveys the idea that the function will produce results tailored to the characteristics of this target population, which can be particularly useful in contexts such as epidemiology or social sciences where population characteristics are critical (Golgolnia, 2024).

2. estimation_entity: This term highlights the entity for which the outcome is being estimated, whether it be an individual, an average individual, or a counterfactual scenario. It is a broader term that encompasses various types of entities, making it flexible for different applications (Datta et al., 2020).

3. population_type: This option indicates that the argument will determine the type of population for which the expected values are calculated. It can help users quickly identify that the function is concerned with different population groups and their characteristics (Cousins et al., 2013).

4. response_context: This name suggests that the argument pertains to the context in which the response is being estimated. It implies that the estimates are influenced by the specific characteristics of the population or individual being considered (Andrade & Tedesco-Silva, 2020).

Naming the Three Options for Marginalization

For the three described options regarding how the estimated average response value is calculated, I propose the following names:

1. Individual: This option refers to marginalization that yields estimates for a very specific individual. It captures the idea that the estimates are tailored to the characteristics of a particular subject within the dataset. This could be represented in the function as individual.

2. Average: This option refers to marginalization that provides estimates for an average individual within the sample. This reflects the typical characteristics of the population from which the sample is drawn. This could be represented in the function as average.

3. Counterfactual: This option refers to marginalization that generates counterfactual predictions, which are estimates based on hypothesized populations or scenarios that may not be directly observed in the data. This could be represented in the function as counterfactual.

Summary of Proposed Naming Conventions

In summary, the proposed alternative names for the function argument that reflects the entity for which the outcome is estimated are:

• target_population: for specifying the population group.
• estimation_entity: for indicating the entity type for estimation.
• population_type: for denoting the type of population considered.
• response_context: for emphasizing the context of the response estimation.

Implementation Example

To illustrate how these naming conventions could be implemented in an R function, consider the following example:

calculate_emm <- function(model, focal_terms, target_population = c("individual", "average", "counterfactual")) {
target_population <- match.arg(target_population)

# Implementation of the EMM calculation based on the specified target population
if (target_population == "individual") {
# Code to calculate EMM for a specific individual
} else if (target_population == "average") {
# Code to calculate EMM for an average individual
} else if (target_population == "counterfactual") {
# Code to calculate EMM for a counterfactual scenario
}

# Return the calculated estimated marginal means
}

Conclusion

The proposed alternative names for the function argument are designed to enhance clarity and usability in the context of estimating expected values of the response for different target populations. By using descriptive names such as target_population, estimation_entity, population_type, and response_context, users of the R package will be better equipped to understand and utilize the functionality provided for estimating outcomes in statistical modeling. This approach aligns with best practices in software development and user interface design, ensuring that the package is both effective and user-friendly.

References:
Andrade, L. and Tedesco-Silva, H. (2020). Recycling of predictors used to estimate glomerular filtration rate: insight into lateral collinearity. Plos One, 15(2), e0228842. https://doi.org/10.1371/journal.pone.0228842
Cousins, G., Bennett, Z., Dillon, G., Smith, S., & Galvin, R. (2013). Adverse outcomes in older adults attending emergency department. European Journal of Emergency Medicine, 20(4), 230-239. https://doi.org/10.1097/mej.0b013e3283606ba6
Datta, A., Fiksel, J., Amouzou, A., & Zeger, S. (2020). Regularized bayesian transfer learning for population-level etiological distributions. Biostatistics, 22(4), 836-857. https://doi.org/10.1093/biostatistics/kxaa001
Golgolnia, T. (2024). Are we speaking the same language? terminology consistency in ebd. Herd Health Environments Research & Design Journal, 17(2), 77-96. https://doi.org/10.1177/19375867231225395

[mattansb]

I like case / typical / population for the 3 types (:

The counterfactual label is irrelevant here because they're all counterfactuals from my understanding of the implementation.

[strengejacke]

Not sure about "average" and "population". Thinking about it

What about

• estimate_for = "individual" or "case"
• estimate_for= "sample" or "typical"
• estimate_for = "counterfactual", "population", or "hypothetical"

[strengejacke]

I like case / typical / population for the 3 types (:

The counterfactual label is irrelevant here because they're all counterfactuals from my understanding of the implementation.

I think counterfactuals are only produces when variables argument is used (according to the documentation of marginaleffects), and the other two option return the same results as predict() or emmeans() - according to your arguments, every prediction would then be counterfactual?

[mattansb]

emmeans are always counterfactual, and marginaleffects comparisons and slopes are also always counterfactual, with predictions being counterfactual when the variables= argument is used, or when the passed newdata= is built to have counterfactual observations (to produce adjusted predictions) - which is what I understand modelbased is doing.

according to your arguments, every prediction would then be counterfactual?

Well, yes. A prediction is only not-counterfactual (or... factual) when using predict(model, newdata = olddata) (or predictions(model, newdata = olddata)`).

Another option is when the samples is perfectly balanced and fully factorial then all counterfactual predictions are represented in the factual predictions.