marginaleffects

marginaleffects is a package available for both R and Python designed to simplify the interpretation of statistical and machine learning models. It provides a unified interface to compute:

• Predictions: Estimating outcomes based on model parameters.
• Comparisons: Calculating contrasts, risk ratios, and other comparative metrics.
• Slopes: Computing partial derivatives and marginal effects.
• Hypothesis Tests: Performing statistical tests on model components.

The package supports over 100 different classes of statistical and machine learning models.

The marginaleffects-r package is licensed under the GNU General Public License v3 (GPLv3).

Key takeaways for users:

• Permissions: You are explicitly permitted to run the unmodified program. You may make, run, and propagate covered works.
• Modifications: You may modify the work, but you must carry prominent notices stating that you modified it and providing a relevant date. Modified versions must be released under the same GPLv3 license.
• Distribution: You may convey verbatim copies or modified versions. If conveying in object code form, you must also provide the machine-readable Corresponding Source.
• No Warranty: The program is provided "AS IS" without warranty of any kind. The entire risk as to the quality and performance of the program is with you.

The data frames produced by marginaleffects contain internal attributes (accessible via components()) that store the original model and data. These are useful for post-processing but can consume significant memory.

Best Practices:

1. Avoid relying on internal attributes: The names and contents of attributes returned by components() are not part of the public API and may change without notice.
2. Clear memory: If memory usage becomes an issue, use the prune() function to remove these attributes, or set the global option options(marginaleffects_lean = TRUE) to prevent them from being stored.

The marginaleffects autodiff pipeline (using JAX) is designed to be a performance optimization that prioritizes correctness. It uses a 'lowering' mechanism to move recorded plans into a shared JAX pipeline.

Safety Guardrail: Every autodiff operation is protected by autodiff_try() (available in both Python and R). This function compares JAX estimates against the standard pipeline using a 1e-8 tolerance. If a mismatch is detected (e.g., due to a lowering bug), the system automatically reverts to finite differences and issues a warning. This ensures that autodiff provides a speedup when possible but never produces incorrect numbers.

To perform equivalence, non-inferiority, or non-superiority tests, use the equivalence argument.

Pass a list of two numeric floats: [lower_bound, upper_bound]. If None, equivalence tests are not performed.

The type argument determines the scale of predictions used for computations. Valid values depend on the model object; if an invalid value is provided, marginaleffects will return an error listing valid types (the first being the default).

The invlink(link) type

This is a special type available for some models, primarily in the predictions() function. It computes predictions on the link scale and then applies the inverse link function to backtransform them to the response scale.

Use cases:

• Ensuring confidence intervals stay within valid bounds (e.g., 0 to 1 for logit models).
• It is the default for predictions().
• It is available (but not default) for avg_predictions() or predictions() when using the by argument.

Note: An average of estimates with type="invlink(link)" is not always equivalent to an average of estimates with type="response".

The comparisons() and avg_comparisons() functions allow you to calculate the difference in predicted outcomes between different values of regressors. You can specify how these values are chosen using the newdata argument or by providing specific values via datagrid().

Common ways to specify newdata include:

• "mean": Contrasts at the mean of the predictors.
• "balanced": Contrasts between marginal means.
• datagrid(...): User-specified values for regressors.
• "unique" or "max": Special values used within datagrid() to represent unique values or maximum values of a variable.

# Contrasts at the mean
comparisons(mod, newdata = "mean")

# Contrasts between marginal means
comparisons(mod, newdata = "balanced")

# Contrasts at user-specified values
comparisons(mod, newdata = datagrid(am = 0, gear = tmp$gear))

The equivalence argument allows for hypothesis testing regarding the bounds $[a, b]$ of an estimate $\theta$ with standard error $\sigma_\theta$.

• Non-inferiority: Tests $H_0: \theta \leq a$ against $H_1: \theta > a$. The p-value is the upper-tail probability of $t = (\theta - a)/\sigma_\theta$.
• Non-superiority: Tests $H_0: \theta \geq b$ against $H_1: \theta < b$. The p-value is the lower-tail probability of $t = (\theta - b)/\sigma_\theta$.
• Equivalence (TOST): Uses Two One-Sided Tests. The p-value is the maximum of the non-inferiority and non-superiority p-values.

These tests use the equivalence argument to perform Two One-Sided Tests (TOST) or directional tests.

Arguments

• equivalence: A numeric vector of length 2 representing the bounds $[a, b]$.

Test Logic

• Non-inferiority: Tests if $\theta > a$. Null hypothesis $H_0: \theta \leq a$.
• Non-superiority: Tests if $\theta < b$. Null hypothesis $H_0: \theta \geq b$.
• Equivalence (TOST): The p-value is the maximum of the non-inferiority and non-superiority p-values.

Note: For Bayesian models, this reports the proportion of posterior draws in the interval and the ROPE (Region of Practical Equivalence).

# Equivalence test with bounds 17 and 18
p <- predictions(mod, newdata = "median")
hypotheses(p, equivalence = c(17, 18))

# Equivalence test on average slopes
mfx <- avg_slopes(mod, variables = "hp")
hypotheses(mfx, equivalence = c(-.1, .1))