Manual for the marginaleffects R and Python package, and guide to the book "Model to Meaning". Use when users ask about predictions, comparisons, slopes, marginal effects, average treatment effects (ATE/ATT/CATE), hypothesis testing, contrasts, counterfactuals, risk ratios, odds ratios, causal inference with G-computation, or need help with marginaleffects functions like predictions(), comparisons(), slopes(), hypotheses(), datagrid(), avg_predictions(), avg_comparisons(), avg_slopes(), or plot functions.
Primary source of information: https://marginaleffects.com Free book, case studies, and vignettes are available there.
Package manual for R and Python, plus a guide to the companion book.
Book: Model to Meaning: How to Interpret Statistical Models in R and Python
Every interpretation task can be decomposed into five disciplined questions:
by=, weighted averages)Chapter summaries: Read chapters/<chapter>.qmd
Function reference: Read man/r/<function>.md or man/python/<function>.md
Classify the request:
chapters/man/r/ or man/python/Read the relevant source files:
chapters/framework.qmd, chapters/predictions.qmd, chapters/comparisons.qmd, chapters/slopes.qmd, chapters/hypothesis.qmd, etc.man/r/predictions.md, man/r/comparisons.md, man/r/slopes.md, man/r/hypotheses.md, man/r/datagrid.mdman/python/predictions.md, man/python/comparisons.md, man/python/slopes.md, man/python/hypotheses.mdApply the five-question framework to organize your response:
Provide concrete code examples using the correct function for their language (R or Python)
chapters/)| File | Topic | Chapter focus |
|---|---|---|
framework.qmd | Five-question framework (start here) | Defines the five questions and core quantities (predictions, comparisons, slopes) for turning models into intuitive estimands. |
predictions.qmd | Predicted values and expected outcomes | Defines predictions, grids, aggregation, and tests with predictions()/avg_predictions(). |
comparisons.qmd | Counterfactual comparisons, ATE, ATT, risk ratios | Defines counterfactual comparisons, effect functions, grids, and aggregation with comparisons()/avg_comparisons(). |
slopes.qmd | Marginal effects, partial derivatives | Defines slopes as partial derivatives, conditional on predictors; uses slopes()/avg_slopes(). |
hypothesis.qmd | Hypothesis testing and equivalence | Null vs equivalence tests for any quantity using hypothesis and equivalence arguments. |
interactions.qmd | Interaction effects and effect modification | Interprets heterogeneity and nonlinearity with interactions and polynomials using predictions, comparisons, and slopes. |
categorical.qmd | Categorical predictors and contrasts | Applies the framework to categorical/ordinal outcomes with predictions and comparisons by outcome level. |
experiments.qmd | Experimental designs | ATE in experiments and factorial designs via avg_comparisons() and robust SEs. |
gcomputation.qmd | G-computation and causal inference | G-computation steps for ATE/ATT/ATU/CATE with counterfactual prediction grids. |
uncertainty.qmd | Inference methods (delta, bootstrap, Bayesian) | Delta method, bootstrap, simulation, conformal prediction, and robust/clustered standard errors via inferences()/vcov. |
mrp.qmd | Multilevel regression and poststratification | Multilevel models and poststratification with predictions and comparisons in mixed effects. |
ml.qmd | Machine learning models | Model auditing with predictions, comparisons, and slopes for ML frameworks. |
challenge.qmd | The interpretation challenge | Defines analysis goals, estimands, and why coefficients need transformation. |
man/r/)Core functions (includes avg_* variants): predictions.md, comparisons.md, slopes.md, hypotheses.md
Grids: datagrid.md
Plots: plot_predictions.md, plot_comparisons.md, plot_slopes.md
Utilities: posterior_draws.md, inferences.md, get_dataset.md
man/python/)Core: predictions.md, avg_predictions.md, comparisons.md, avg_comparisons.md, slopes.md, avg_slopes.md, hypotheses.md
Grids: datagrid.md
Plots: plot_predictions.md, plot_comparisons.md, plot_slopes.md
Model fitting: fit_statsmodels.md, fit_sklearn.md, fit_linearmodels.md
R:
library(marginaleffects)
# Fit logistic regression
mod <- glm(am ~ hp + wt, data = mtcars, family = binomial)
# Average marginal effects (slopes on probability scale)
avg_slopes(mod)
# Predicted probabilities at specific values
predictions(mod, newdata = datagrid(hp = c(100, 150, 200), wt = 3))
# Average treatment effect: compare hp = 150 vs hp = 100
avg_comparisons(mod, variables = list(hp = c(100, 150)))
# Risk ratio for a 50-unit increase in hp
avg_comparisons(mod, variables = list(hp = 50), comparison = "ratio")
Python:
import marginaleffects as me
import statsmodels.formula.api as smf
# Fit logistic regression
mod = smf.logit("am ~ hp + wt", data=me.get_dataset("mtcars")).fit()
# Average marginal effects
me.avg_slopes(mod)
# Predicted probabilities at specific values
me.predictions(mod, newdata=me.datagrid(mod, hp=[100, 150, 200], wt=3))
# Average treatment effect: compare hp = 150 vs hp = 100
me.avg_comparisons(mod, variables={"hp": [100, 150]})
User asks about choosing an estimand:
→ Read chapters/framework.qmd and chapters/comparisons.qmd, explain the five-question framework, recommend the appropriate quantity (e.g., avg_comparisons() for ATE).
User asks how to compute marginal effects:
→ Read man/r/slopes.md or man/python/slopes.md, provide syntax with relevant arguments.
User wants to test treatment effect heterogeneity:
→ Read chapters/comparisons.qmd for CATE concepts, then man/r/hypotheses.md for testing syntax with by= groups.
User asks about counterfactual grids:
→ Read chapters/framework.qmd (Predictors section) and man/r/datagrid.md for datagrid() usage.
get_dataset() when users need example data