marginaleffects

name	marginaleffects
description	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.
license	CC-BY-4.0
metadata	{"source":"https://marginaleffects.com","maintainer":"vincentarelbundock"}
allowed-tools	Read, Grep, Glob

marginaleffects

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

• Author: Vincent Arel-Bundock (2026)
• Publisher: CRC Press
• Free online: https://marginaleffects.com (primary source with many case studies and vignettes)
• Print: https://routledge.com/9781032908724

Core framework: Five questions for every analysis

Every interpretation task can be decomposed into five disciplined questions:

1. Quantity: What estimand? (predictions, comparisons, slopes, or tests)
2. Predictors (Grid): Where to evaluate? (observed values, counterfactual scenarios, balanced grids)
3. Aggregation: Over whom? (unit-level, group means with by=, weighted averages)
4. Uncertainty: Which inference method? (delta method, robust SE, bootstrap, Bayesian)
5. Test: What hypothesis? (null tests, equivalence, pairwise contrasts)

Quick start

Chapter summaries: Read chapters/<chapter>.qmd Function reference: Read man/r/<function>.md or man/python/<function>.md

When to use this skill

• User asks about predictions, comparisons, slopes, or marginal effects
• User needs help choosing estimands (ATE, ATT, CATE, risk difference, odds ratio)
• User asks about marginaleffects function syntax or arguments
• User wants to interpret model results or test hypotheses
• User mentions counterfactual analysis, G-computation, or causal inference
• User references Model to Meaning chapters

Instructions

1. Classify the request:

   • Conceptual: Which estimand? How to interpret? → Use chapters/
   • Implementation: Function syntax, arguments, code → Use man/r/ or man/python/
   • Mixed: Start with conceptual framing, then provide code

2. Read the relevant source files:

   • Book chapters: chapters/framework.qmd, chapters/predictions.qmd, chapters/comparisons.qmd, chapters/slopes.qmd, chapters/hypothesis.qmd, etc.
   • R reference: man/r/predictions.md, man/r/comparisons.md, man/r/slopes.md, man/r/hypotheses.md, man/r/datagrid.md
   • Python reference: man/python/predictions.md, man/python/comparisons.md, man/python/slopes.md, man/python/hypotheses.md

3. Apply the five-question framework to organize your response:

   • Help user define the estimand (Quantity)
   • Clarify where to evaluate it (Grid)
   • Determine aggregation level (Aggregation)
   • Recommend uncertainty quantification (Uncertainty)
   • Specify hypothesis if testing (Test)

4. Provide concrete code examples using the correct function for their language (R or Python)

Available resources

Book chapters (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.

R function reference (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

Python function reference (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

Examples

Logit model example

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.

Best practices

• Ask about language preference: If the user hasn't specified R or Python, ask which they prefer before providing code examples
• Always frame responses using the five-question framework when appropriate
• Cite specific sections from summaries or manuals
• Mention get_dataset() when users need example data
• For mixed requests, start with conceptual framing then show implementation