API reference

pymargins — expert-mode marginal effects for Python.

Quick reference

Wrap a fitted model in a Margins session, declare your analytical posture (scale, vcov, level, at), then compute predictions, slopes, and contrasts via the session’s methods:

from pymargins import Margins
m = Margins.log_scale(fitted_glm, vcov="HC3")
rr = m.contrasts(
    scenarios=[
        {"atexog": {"treatment": "treated"}},
        {"atexog": {"treatment": "control"}},
    ],
    contrasts=[+1, -1],
)

Public API

• Margins — main session class

• MarginsResult — output of predict/dydx/contrasts/evaluate

• TestResult — output of result.test() and result.joint_test()

• DiagnosticResult — output of m.diagnose()

• VariableInfo — per-variable metadata used by adapters

• register_adapter — register a custom adapter for auto-detection

Internal modules (prefixed with _) hold the numerical kernels and engine; end users should not import from these directly.

Adapter authors writing a custom adapter subclass one of the base shapes re-exported above (ModelAdapter, GLMAdapter, etc.) plus the make_*_jvp_wrapper gradient helpers, and register it with register_adapter. The concrete built-in adapters are available, lazily, from the public pymargins.adapters module — you rarely need them since Margins(model) auto-detects the right one; import explicitly only to override detection or select a non-default scale.

Session

Margins(model, *, phi, phi_inv, vcov, ...)

Wrapper around a fitted model exposing marginal-effects analysis.

Results

MarginsResult(estimate, std_error, ...)	Container for marginal-effects estimates with inference and diagnostics.
TestResult(statistic, pvalue, df, ...)	Output of a hypothesis test on a MarginsResult.
DiagnosticResult(kappa_min, kappa_median, ...)	Output of session-level kappa diagnostic.

Scenario helpers

pairwise(variable, values, *[, label_fmt])	Build two scenarios and a [+1, -1] contrast for a pairwise comparison.
reference(variable, levels, *[, ref_level, ...])	Build reference-level contrasts: each level vs a common baseline.
at_levels(variable, *, levels[, label_fmt])	Build one scenario per level of a categorical/binary variable.
grid(*[, label_fmt])	Cartesian product of variable values into a scenario list.
did(treatment, time, *[, treated_level, ...])	Build scenarios and contrast weights for a difference-in-differences design.
diff(n)	Return a standard pairwise difference contrast vector.
all_pairwise(variables, values_list, *[, ...])	Build all scenario combinations for a factorial design and return named pairwise contrasts for each stratum.

Adapter interface

ModelAdapter()	Abstract base class for model adapters.
GLMAdapter()	Base adapter for any model with prediction μ = g⁻¹(Xβ + offset).
LinearPredictionAdapter()	Base for models whose prediction is exactly Xβ (no link function).
WrappedFDAdapter()	Base for models with smooth predict but no exposed analytical derivative.
BootstrapOnlyAdapter()	Base for non-parametric / algorithmic models with no meaningful Σ̂.
VariableInfo(name, var_type[, levels, ...])	Per-variable metadata used for at=typical averaging, contrast validation, and warning generation.
register_adapter(adapter_class, *[, ...])	Register an adapter class for auto-detection.

Concrete adapters

You rarely need these — Margins(model) auto-detects the right adapter for standard statsmodels / linearmodels / lifelines results. Import a concrete adapter from pymargins.adapters only when you need a non-default scale that shares a result class with another adapter (e.g. LifelinesCoxPHSurvivalAdapter for survival probability vs the auto-detected LifelinesCoxPHAdapter for hazard ratio), when wrapping a framework with no native inference (SklearnBootstrapAdapter), or when constructing an adapter explicitly to override auto-detection or pass extra arguments such as training_data=.

pymargins.adapters — public access to concrete model adapters.

You rarely need anything here. Margins(model) auto-detects the right adapter for standard statsmodels / linearmodels / lifelines results. Import a concrete adapter only when:

1. You need a non-default scale that shares a result class with another adapter and therefore cannot be auto-detected — e.g. LifelinesCoxPHSurvivalAdapter (survival probability) vs the auto-detected LifelinesCoxPHAdapter (hazard ratio).

2. You are wrapping a framework with no native inference, such as scikit-learn via SklearnBootstrapAdapter.

3. You want to construct an adapter explicitly to pass extra arguments (e.g. training_data=) or to override auto-detection.

To write a custom adapter, subclass one of the base shapes exported from the top-level package (ModelAdapter, GLMAdapter, LinearPredictionAdapter, WrappedFDAdapter, BootstrapOnlyAdapter) and register it with pymargins.register_adapter(). See docs/howto/custom_adapter.md.

Imports here are lazy (PEP 562): referencing an adapter triggers the import of its module and the corresponding optional third-party dependency, so import pymargins stays cheap and does not require statsmodels, lifelines, linearmodels, or scikit-learn to be installed.

Gradient helpers (for adapter authors)

make_predict_with_fd_jvp(predict_native[, ...])	Wrap a non-JAX predict function as a JAX primitive with FD-based JVP.
make_glm_jvp_wrapper(family)	Wrap a GLM prediction with a custom JVP using the link's analytical derivative.
GradientBackend
InferenceMethod

Matching

PysmatchClient(matcher, treatment_col[, ...])

Wrap a fitted pysmatch.Matcher for use with Margins.