How pymargins differs from marginaleffects and margins

This page is for users coming from the R marginaleffects package or Stata’s margins command. The mathematics is the same — the implementations converge because the math forces them to. The differences are in posture.

1. Session pre-commitment

marginaleffects and margins let you choose vcov, scale, level, and aggregation per call. pymargins makes those choices session- level. The constructor is the methods section; switching any of them requires a new session.

This is more rigid by design. See The session pre-commitment.

2. The κ fallback

Both R and Stata always do the delta method. They do not tell you when the delta method is suspect.

pymargins computes Skovgaard’s relative curvature κ as a routine diagnostic and auto-falls-back to simulation when κ exceeds the session threshold. The fallback is loud — every result records the realized inference method and the reason it was used. See The κ curvature diagnostic.

3. JAX-native autodiff

marginaleffects uses numerical derivatives. pymargins is built on JAX: exact gradients (and exact Hessians for κ) for any model whose predict can be expressed in JAX, and a custom-JVP bridge for models where it cannot. See Gradient backend: autodiff vs wrapped-FD vs FD.

4. Inference scale as a first-class object

marginaleffects offers type= (link / response) and a couple of hard-coded transforms. pymargins takes phi, phi_inv as arbitrary JAX callables; the same chain-rule machinery handles log-RR, Fisher-z, lift, or any user-defined scale. See Inference scale (phi / phi_inv).

5. Design-based survey inference

pymargins does complex-survey inference natively. Declare the design once with a SurveyDesign (sampling weights, PSUs/clusters, strata, and an optional finite-population correction) and pass it to the constructor:

from pymargins import Margins, SurveyDesign
d = SurveyDesign(weights=w, psu=psu, strata=strat)
m = Margins(fit, survey_design=d, weights=w)
m.dydx("x")   # design-weighted AME with Taylor-linearization SE

The point estimate is design-weighted and the standard error is the stratified, clustered Taylor-linearization sandwich — the same quantity R’s survey::svyglm + marginaleffects produce, matched numerically. Because the design-based covariance flows through the same frozen-cov chokepoint as every other vcov, the delta and simulation paths are both design-based with no extra wiring; the bootstrap path resamples PSUs within strata. See Survey designs — weights, strata, and clusters.

6. Narrower scope

pymargins does adjusted predictions, slopes, contrasts, and differentiable compositions. It does not do:

• model averaging,

• counterfactual prediction with model re-solving,

• post-estimation likelihood transformations.

If you need those, marginaleffects has broader coverage and a gentler learning curve, and it is the right tool.

API mapping for R users

If you are coming from marginaleffects, the conceptual mapping is:

marginaleffects (R)	pymargins (Python)	Notes
predictions()	m.predict()	Adjusted predictions (AAP / APM / APR)
slopes()	m.dydx()	Marginal effects (AME / MEM / MER)
comparisons()	m.contrasts()	Linear contrasts with joint covariance
avg_predictions()	m.predict(at="overall")	AAP is the default at
avg_slopes()	m.dydx(at="overall")	AME is the default at
svydesign() + svyglm()	Margins(survey_design=SurveyDesign(...))	Design-based survey SEs (linearization or stratified bootstrap)
plot_predictions()	m.predict(...) + to_frame() + matplotlib	See Plotting predictions and effects
hypotheses()	m.evaluate()	Nonlinear compositions
type = "link"	phi_inv scale	pymargins commits to one scale per session
type = "response"	phi back-transform	CI endpoints are back-transformed automatically

When to pick which

Need	Tool
Broad model coverage, fast iteration	marginaleffects
Audit trail and pre-registration	pymargins
Curvature-aware fallback	pymargins
Custom inference scales	pymargins
Complex-survey design-based SEs	both (numerically agreed)
Stata-style replications	both (numerically agreed)