pymargins.MarginsResult

class pymargins.MarginsResult(estimate: ndarray, std_error: ndarray, conf_int_lower: ndarray, conf_int_upper: ndarray, method: str, level: float, n_obs: int = 0, kappa: ndarray | None = None, delta_sim_disagreement: float | None = None, fallback_triggered: bool = False, fallback_reason: str | None = None, estimand_metadata: dict = <factory>, gradient: ndarray | None = None, draws: ndarray | None = None, draws_inf: ndarray | None = None, cov_params: ndarray | None = None, phi: Callable | None = None, phi_inv: Callable | None = None, session: Any | None = None, ci_method: str | None = None, bootstrap_extras: dict | None = None, resample_bank_id: str | None = None, n_boot_effective: int | None = None, n_boot_failed: int | None = None)

Container for marginal-effects estimates with inference and diagnostics.

Carries:

• The numerical outputs (estimate, SE, CI, p-value)

• Diagnostics (κ, simulation disagreement, fallback flag)

• Underlying machinery (gradient, draws) for composition with other results from the same session

Composability via arithmetic operators (+, -, *, /) supports building derived quantities from already-computed results, with proper joint inference using the shared Σ̂. Cross-session composition is forbidden; raises ValueError.

estimate

Point estimate(s) on the reporting scale (after phi).

Type:

array

std_error

Standard error(s) on the inference scale (before phi).

Type:

array

conf_int_lower, conf_int_upper

CI bounds on the reporting scale.

Type:

array

method

Inference method used: “delta”, “simulation”, “bootstrap”.

Type:

str

level

Confidence level.

Type:

float

n_obs

Number of observations contributing to the estimand.

Type:

int

kappa

Curvature diagnostic per estimand component.

Type:

array, optional

delta_sim_disagreement

Maximum relative disagreement between delta and simulation CIs, when both were computed.

Type:

float, optional

fallback_triggered

Whether the requested method (typically delta) was replaced by a fallback (typically simulation).

Type:

bool

fallback_reason

Why fallback occurred (e.g., “kappa=0.5>threshold=0.3”).

Type:

str, optional

estimand_metadata

Variable names, scenario labels, contrast specifications, at setting, etc., for output formatting.

Type:

dict

gradient

∇h at β̂ on the inference scale. Present for delta-method results; used for inter-call composition.

Type:

array, optional

draws

Estimand evaluations at simulated/bootstrapped β on the reporting scale (after phi). Present for simulation/bootstrap results.

Type:

array, optional

draws_inf

Estimand evaluations on the inference scale (before phi). Present for simulation/bootstrap results; used for recomputing CIs with alternative bootstrap methods.

Type:

array, optional

cov_params

Σ̂ frozen at the time the result was produced. Used by hypothesis tests and inter-call composition so that downstream operations are not affected by later mutation or re-fitting of the model wrapped by session.

Type:

array, optional

phi

Back-transform from inference scale to reporting scale. Captured at construction so reporting works even if the session is garbage collected.

Type:

callable, optional

phi_inv

Forward transform from reporting scale to inference scale. Captured at construction for the same reason as phi.

Type:

callable, optional

session

Reference to the originating session. Used to validate composability (same-session check). Σ̂ is read from cov_params rather than re-fetched from session.adapter to make results robust to model mutation and to make materialize() semantically clean.

Type:

Margins

ci_method

CI method used for bootstrap results: “percentile”, “basic”, “bca”, or “studentized”.

Type:

str, optional

bootstrap_extras

Method-specific data for recomputing CIs (e.g., BCa z0/a, studentized t-star draws).

Type:

dict, optional

n_boot_effective

Number of successful bootstrap replicates (may be less than n_boot if some replicates failed to refit).

Type:

int, optional

n_boot_failed

Number of bootstrap replicates that failed to refit.

Type:

int, optional

__init__(estimate: ndarray, std_error: ndarray, conf_int_lower: ndarray, conf_int_upper: ndarray, method: str, level: float, n_obs: int = 0, kappa: ndarray | None = None, delta_sim_disagreement: float | None = None, fallback_triggered: bool = False, fallback_reason: str | None = None, estimand_metadata: dict = <factory>, gradient: ndarray | None = None, draws: ndarray | None = None, draws_inf: ndarray | None = None, cov_params: ndarray | None = None, phi: Callable | None = None, phi_inv: Callable | None = None, session: Any | None = None, ci_method: str | None = None, bootstrap_extras: dict | None = None, resample_bank_id: str | None = None, n_boot_effective: int | None = None, n_boot_failed: int | None = None) → None

Methods

__init__(estimate, std_error, ...)
conf_int([level, simultaneous])	Recompute CI at a different confidence level.
contrast(C[, labels])	Apply a contrast matrix to a vector result.
from_disk(path)	Load a MarginsResult from disk.
influence()	Per-observation influence on the estimand (DFBETA sign).
joint_test([value, kind, null_scale])	Joint test H₀: all estimand components equal (vector-valued) value.
materialize()	Drop underlying machinery (gradient, draws, session) to reduce memory.
outcome(index)	Slice a multi-outcome result to a single outcome.
pairwise_contrasts([labels])	All pairwise differences between components of a vector result.
scaled(by[, units])	Cosmetic rescaling of the estimate and CI for reporting.
summary([stars, star_levels, float_fmt, ...])	Human-readable summary including diagnostics.
test([value, kind, alternative, null_scale])	Test H₀: estimand = value (per-component).
to_disk(path, *[, format])	Persist a materialized result to disk.
to_frame()	Return as a tidy DataFrame.
to_html([stars, star_levels, float_fmt, ...])	HTML table representation of the result.
to_latex([stars, star_levels, float_fmt, ...])	LaTeX tabular representation of the result.

Attributes

bootstrap_extras
ci_method
cov_params
delta_sim_disagreement
draws
draws_inf
fallback_reason
fallback_triggered
gradient
kappa
n_boot_effective
n_boot_failed
n_obs
phi
phi_inv
resample_bank_id
session
estimate
std_error
conf_int_lower
conf_int_upper
method
level
estimand_metadata