pymixef package

PyMixEF: mixed-effects statistics and pharmacometrics in Python.

The package is fully offline and emits no telemetry. Public capabilities carry explicit evidence/maturity labels; use iter_capabilities() or the CLI pymixef capabilities before relying on an experimental calculation path.

class pymixef.ApproximationSensitivityResult(table, fits, failures, baseline, settings, materiality)[source]

Bases: object

Cross-setting refit comparisons with explicit failure accounting.

Parameters:

  • table (DiagnosticTable)

  • fits (Mapping[str, FitResult])

  • failures (tuple[Mapping[str, Any], ...])

  • baseline (str)

  • settings (Mapping[str, Mapping[str, Any]])

  • materiality (Mapping[str, float])

table: DiagnosticTable
fits: Mapping[str, FitResult]
failures: tuple[Mapping[str, Any], ...]
baseline: str
settings: Mapping[str, Mapping[str, Any]]
materiality: Mapping[str, float]
property failed_scenarios: int

Number of settings whose fit failed or returned unusable output.

property successful_scenarios: int

Number of settings whose fit completed successfully.

to_dict()[source]

Return the comparison and scenario metadata without duplicating fits.

Return type:

dict[str, Any]

class pymixef.BootstrapResult(draws, failures, seed, resampling)[source]

Bases: object

Parameter draws, failure accounting, and interval calculations.

Parameters:

  • draws (DiagnosticTable)

  • failures (tuple[Mapping[str, Any], ...])

  • seed (int)

  • resampling (str)

draws: DiagnosticTable
failures: tuple[Mapping[str, Any], ...]
seed: int
resampling: str
property failed_replicates: int
intervals(level=0.95, *, method='percentile')[source]
Parameters:

  • level (float)

  • method (str)

Return type:

DiagnosticTable

property successful_replicates: int
to_dict()[source]
Return type:

dict[str, Any]

class pymixef.BoundaryRecord(parameter, value, boundary='zero', tolerance=None)[source]

Bases: object

One natural-scale parameter on or near a numerical boundary.

Parameters:

  • parameter (str)

  • value (float)

  • boundary (str)

  • tolerance (float | None)

parameter: str
value: float
boundary: str
tolerance: float | None
to_dict()[source]
Return type:

dict[str, Any]

class pymixef.ComparisonResult(table, compatibility, objective_difference, conventions)[source]

Bases: object

Aligned comparison plus its convention-compatibility report.

Parameters:
table: DiagnosticTable
compatibility: CompatibilityReport
objective_difference: float | None
conventions: Mapping[str, Any]
assert_within(tolerances)[source]
Parameters:

tolerances (Mapping[str, float])

Return type:

None

to_dict()[source]
Return type:

dict[str, Any]

write_report(path)[source]
Parameters:

path (str | Path)

Return type:

Path

exception pymixef.CompatibilityError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: PyMixEFError

Two scientific objects cannot safely be compared or translated.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'COMPATIBILITY-001'
class pymixef.ConvergenceReport(status, optimizer_terminated, optimizer_message='', iterations=None, objective_evaluations=None, gradient_evaluations=None, scaled_gradient_inf_norm=None, parameter_step_norm=None, hessian=<factory>, boundaries=(), conditional_mode_failures=0, ode_failures=0, warnings=(), engine_metrics=<factory>)[source]

Bases: object

Structured convergence contract shared by every estimator.

Parameters:

  • status (str)

  • optimizer_terminated (bool)

  • optimizer_message (str)

  • iterations (int | None)

  • objective_evaluations (int | None)

  • gradient_evaluations (int | None)

  • scaled_gradient_inf_norm (float | None)

  • parameter_step_norm (float | None)

  • hessian (HessianDiagnostics)

  • boundaries (tuple[BoundaryRecord, ...])

  • conditional_mode_failures (int)

  • ode_failures (int)

  • warnings (tuple[WarningRecord, ...])

  • engine_metrics (Mapping[str, Any])

status: str
optimizer_terminated: bool
optimizer_message: str
iterations: int | None
objective_evaluations: int | None
gradient_evaluations: int | None
scaled_gradient_inf_norm: float | None
parameter_step_norm: float | None
hessian: HessianDiagnostics
boundaries: tuple[BoundaryRecord, ...]
conditional_mode_failures: int
ode_failures: int
warnings: tuple[WarningRecord, ...]
engine_metrics: Mapping[str, Any]
classmethod assess(*, optimizer_terminated, gradient=None, hessian=None, gradient_tolerance=1e-4, boundaries=(), warnings=(), **metrics)[source]

Construct a report from common deterministic optimizer diagnostics.

Parameters:

  • optimizer_terminated (bool)

  • gradient (ndarray | None)

  • hessian (ndarray | None)

  • gradient_tolerance (float)

  • boundaries (Iterable[BoundaryRecord])

  • warnings (Iterable[WarningRecord | Mapping[str, Any]])

  • metrics (Any)

Return type:

ConvergenceReport

classmethod from_dict(value)[source]
Parameters:

value (Mapping[str, Any])

Return type:

ConvergenceReport

to_dict()[source]
Return type:

dict[str, Any]

property trustworthy: bool

Whether termination and numerical checks support routine interpretation.

exception pymixef.CovarianceError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: ValidationError

A covariance declaration or matrix is invalid.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'COV-INVALID-001'
exception pymixef.DataError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: ValidationError

Input data cannot be adapted without changing its meaning.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'DATA-INVALID-001'
exception pymixef.EngineCompatibilityError(message, *, suggested_engines=(), **kwargs)[source]

Bases: UnsupportedCapabilityError

The selected estimator cannot represent the compiled model.

Parameters:

  • message (str)

  • suggested_engines (list[str] | tuple[str, ...])

  • kwargs (Any)

Return type:

None

to_dict()[source]

Return a JSON-compatible diagnostic record.

Return type:

dict[str, Any]

class pymixef.ExecutionPlan(model, matrices, model_ir, source_data, engine, method, settings, validation)[source]

Bases: object

Deterministic compiled model, data audit, and engine settings.

Parameters:
model: Model
matrices: DesignMatrices
model_ir: ModelIR
source_data: Any
engine: str
method: str
settings: Mapping[str, Any]
validation: ValidationReport
explain()[source]
Return type:

str

fit()[source]
Return type:

FitResult

to_backend_data()[source]
Return type:

dict[str, Any]

validate()[source]
Return type:

ValidationReport

class pymixef.FitResult(model_ir, parameters, unconstrained_parameters, parameter_covariance, fitted_values, residuals, random_effects, objective, log_likelihood, method, engine, convergence, manifest, warnings=(), diagnostic_data=<factory>, extra=<factory>, result_schema_version='1.0.0')[source]

Bases: object

Result contract shared by frequentist, stochastic, and Bayesian engines.

Parameters:

  • model_ir (Any)

  • parameters (Mapping[str, float])

  • unconstrained_parameters (Mapping[str, float])

  • parameter_covariance (ndarray | None)

  • fitted_values (ndarray)

  • residuals (ndarray)

  • random_effects (Mapping[str, Any])

  • objective (float)

  • log_likelihood (float | None)

  • method (str)

  • engine (str)

  • convergence (ConvergenceReport)

  • manifest (RunManifest)

  • warnings (tuple[WarningRecord, ...])

  • diagnostic_data (Mapping[str, DiagnosticTable])

  • extra (Mapping[str, Any])

  • result_schema_version (str)

model_ir: Any
parameters: Mapping[str, float]
unconstrained_parameters: Mapping[str, float]
parameter_covariance: ndarray | None
fitted_values: ndarray
residuals: ndarray
random_effects: Mapping[str, Any]
objective: float
log_likelihood: float | None
method: str
engine: str
convergence: ConvergenceReport
manifest: RunManifest
warnings: tuple[WarningRecord, ...]
diagnostic_data: Mapping[str, DiagnosticTable]
extra: Mapping[str, Any]
result_schema_version: str
diagnostic(name)[source]
Parameters:

name (str)

Return type:

DiagnosticTable

classmethod from_dict(value)[source]
Parameters:

value (Mapping[str, Any])

Return type:

FitResult

classmethod load(path, *, verify_integrity=True, require_sidecar=False)[source]

Load an archived result and verify its hash sidecar when available.

Legacy or externally produced JSON may omit the sidecar. Set require_sidecar=True when the calling workflow requires an integrity record. Integrity verification can be disabled only explicitly.

Parameters:

  • path (str | Path)

  • verify_integrity (bool)

  • require_sidecar (bool)

Return type:

FitResult

property n_observations: int
prediction(*, mode='conditional')[source]

Return an explicitly named prediction mode for the analysis rows.

Parameters:

mode (str)

Return type:

ndarray

residual_diagnostics(*, observed=None, variance=None)[source]
Parameters:

  • observed (Sequence[float] | None)

  • variance (Sequence[float] | float | None)

Return type:

DiagnosticTable

save(path)[source]

Save the full result as versioned JSON; never pickle.

Parameters:

path (str | Path)

Return type:

Path

simulate(*, n_replicates=1, seed=None, parameter_uncertainty='none', random_effects=True, residual_error=True, output='numpy', design=None)[source]

Simulate from archived Gaussian calculations or a backend simulator.

The arguments follow PyMixEF’s public simulation contract. A backend may archive a callable simulator for an in-memory result, but archival reloads use the standardized Gaussian fallback only when its assumptions are explicit.

Parameters:

  • n_replicates (int)

  • seed (int | None)

  • parameter_uncertainty (str)

  • random_effects (bool)

  • residual_error (bool)

  • output (str)

  • design (Any)

Return type:

ndarray | DiagnosticTable

property success: bool

A compatibility convenience; inspect convergence for real detail.

summary()[source]

Return a concise text summary separating estimates and convergence.

Return type:

str

to_dict()[source]
Return type:

dict[str, Any]

vpc(*, data=None, independent=None, bins='adaptive', prediction_corrected=False, simulations=1000, seed=None)[source]
Parameters:

  • data (Sequence[float] | None)

  • independent (Sequence[float] | None)

  • bins (str | int | Sequence[float])

  • prediction_corrected (bool)

  • simulations (int)

  • seed (int | None)

Return type:

DiagnosticTable

class pymixef.Fixed(expression)[source]

Bases: object

Fixed-effects expression in the safe formula grammar.

Parameters:

expression (str)

expression: str
exception pymixef.FormulaError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: ValidationError

A formula is syntactically invalid, unsafe, or semantically ambiguous.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'FORMULA-SYNTAX-001'
class pymixef.GroupInfluenceResult(table, failures, group_column, requested_groups)[source]

Bases: object

Delete-whole-group refits with optional approximation comparisons.

Parameters:

  • table (DiagnosticTable)

  • failures (tuple[Mapping[str, Any], ...])

  • group_column (str)

  • requested_groups (int)

table: DiagnosticTable
failures: tuple[Mapping[str, Any], ...]
group_column: str
requested_groups: int
property failed_groups: int

Number of grouping levels whose full refit failed.

property successful_groups: int

Number of grouping levels with a completed full refit.

to_dict()[source]

Return the table, failures, and group-level accounting.

Return type:

dict[str, Any]

class pymixef.HessianDiagnostics(positive_definite=None, min_eigenvalue=None, max_eigenvalue=None, condition_number=None, effective_rank=None)[source]

Bases: object

Definiteness and conditioning summary for an observed Hessian.

Parameters:

  • positive_definite (bool | None)

  • min_eigenvalue (float | None)

  • max_eigenvalue (float | None)

  • condition_number (float | None)

  • effective_rank (int | None)

positive_definite: bool | None
min_eigenvalue: float | None
max_eigenvalue: float | None
condition_number: float | None
effective_rank: int | None
classmethod from_matrix(matrix, *, relative_tolerance=1e-8)[source]
Parameters:

  • matrix (ndarray)

  • relative_tolerance (float)

Return type:

HessianDiagnostics

to_dict()[source]
Return type:

dict[str, Any]

exception pymixef.IRValidationError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: ValidationError

A model IR violates the versioned schema’s semantic invariants.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'IR-VALIDATION-001'
exception pymixef.IRVersionError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: PyMixEFError

A serialized model IR uses an unsupported or unsafe schema version.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'IR-VERSION-001'
class pymixef.Maturity(*values)[source]

Bases: StrEnum

Evidence tier attached to every public capability.

EXPERIMENTAL = 'experimental'
STABLE = 'stable'
REFERENCE_VALIDATED = 'reference-validated'
REGULATED_WORKFLOW_SUPPORT = 'regulated-workflow-support'
class pymixef.Model(response=None, fixed=None, random=(), family=<factory>, residual=None, formula=None, zero_inflation=None, dispersion=None, shape=None, priors=<factory>, metadata=<factory>)[source]

Bases: object

Backend-neutral scientific model.

Construct with a formula through from_formula(), or provide Response, Fixed, and Random declarations directly.

Parameters:

  • response (Response | str | None)

  • fixed (Fixed | str | None)

  • random (Sequence[Random])

  • family (Family)

  • residual (Any)

  • formula (str | None)

  • zero_inflation (str | None)

  • dispersion (str | None)

  • shape (str | None)

  • priors (Mapping[str, Any])

  • metadata (Mapping[str, Any])

response: Response | str | None
fixed: Fixed | str | None
random: Sequence[Random]
family: Family
residual: Any
formula: str | None
zero_inflation: str | None
dispersion: str | None
shape: str | None
priors: Mapping[str, Any]
metadata: Mapping[str, Any]
compile(data, *, engine=None, method=None, missing='drop', **settings)[source]
Parameters:

  • data (Any)

  • engine (str | None)

  • method (str | None)

  • missing (str)

  • settings (Any)

Return type:

ExecutionPlan

explain(data=None, *, engine=None, method=None, missing='drop')[source]
Parameters:

  • data (Any | None)

  • engine (str | None)

  • method (str | None)

  • missing (str)

Return type:

str

fit(data, *, engine=None, method=None, missing='drop', **settings)[source]
Parameters:

  • data (Any)

  • engine (str | None)

  • method (str | None)

  • missing (str)

  • settings (Any)

Return type:

FitResult

formula_text()[source]
Return type:

str

classmethod from_formula(formula, *, family=None, residual=None, zero_inflation=None, dispersion=None, shape=None, priors=None, metadata=None)[source]
Parameters:

  • formula (str)

  • family (Family | None)

  • residual (Any)

  • zero_inflation (str | None)

  • dispersion (str | None)

  • shape (str | None)

  • priors (Mapping[str, Any] | None)

  • metadata (Mapping[str, Any] | None)

Return type:

Model

property specification: FormulaSpec
to_ir(*, engine=None, method=None)[source]

Compile data-independent semantics into the shared versioned IR.

Parameters:

  • engine (str | None)

  • method (str | None)

Return type:

ModelIR

validate(*, engine=None, method=None)[source]
Parameters:

  • engine (str | None)

  • method (str | None)

Return type:

ValidationReport

class pymixef.ModelIR(schema_version='1.0.0', name=None, source=None, formula=None, response=None, family='gaussian', fixed_effects=(), random_effects=(), predictors=(), likelihoods=(), covariance_structures=(), state_equations=(), events=(), parameters=(), transforms=(), priors=(), outputs=(), data_schema=<factory>, estimator=<factory>, metadata=<factory>)[source]

Bases: object

Complete backend-neutral scientific model graph.

Parameters:

  • schema_version (str)

  • name (str | None)

  • source (str | None)

  • formula (str | None)

  • response (str | None)

  • family (str)

  • fixed_effects (tuple[FixedEffectIR, ...])

  • random_effects (tuple[RandomEffectIR, ...])

  • predictors (tuple[PredictorIR, ...])

  • likelihoods (tuple[LikelihoodIR, ...])

  • covariance_structures (tuple[CovarianceIR, ...])

  • state_equations (tuple[StateEquationIR, ...])

  • events (tuple[EventIR, ...])

  • parameters (tuple[ParameterIR, ...])

  • transforms (tuple[TransformIR, ...])

  • priors (tuple[PriorIR, ...])

  • outputs (tuple[OutputIR, ...])

  • data_schema (Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON], ...] | Mapping[str, None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON]]])

  • estimator (Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON], ...] | Mapping[str, None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON]]])

  • metadata (Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON], ...] | Mapping[str, None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON]]])

schema_version: str
name: str | None
source: str | None
formula: str | None
response: str | None
family: str
fixed_effects: tuple[FixedEffectIR, ...]
random_effects: tuple[RandomEffectIR, ...]
predictors: tuple[PredictorIR, ...]
likelihoods: tuple[LikelihoodIR, ...]
covariance_structures: tuple[CovarianceIR, ...]
state_equations: tuple[StateEquationIR, ...]
events: tuple[EventIR, ...]
parameters: tuple[ParameterIR, ...]
transforms: tuple[TransformIR, ...]
priors: tuple[PriorIR, ...]
outputs: tuple[OutputIR, ...]
data_schema: Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON], ...] | Mapping[str, None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON]]]
estimator: Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON], ...] | Mapping[str, None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON]]]
metadata: Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON], ...] | Mapping[str, None | bool | int | float | str | tuple[FrozenJSON, ...] | Mapping[str, FrozenJSON]]]
canonical_json()[source]

Return deterministic compact JSON used for identity and hashes.

Return type:

str

diff(other)[source]

Return a deterministic semantic change report.

Parameters:

other (ModelIR)

Return type:

ModelDiff

classmethod from_dict(document, *, migrate=True)[source]

Validate, optionally migrate, and construct a model IR document.

Parameters:

  • document (Mapping[str, Any])

  • migrate (bool)

Return type:

ModelIR

classmethod from_json(document, *, migrate=True)[source]

Load a model from a JSON string or bytes.

Parameters:

  • document (str | bytes)

  • migrate (bool)

Return type:

ModelIR

property hash: str

Alias for semantic_hash.

property semantic_hash: str

SHA-256 digest of the canonical mathematical representation.

semantically_equal(other)[source]

Whether two models have identical canonical scientific meaning.

Parameters:

other (object)

Return type:

bool

to_dict()[source]

Return a JSON-compatible schema-v1 document.

Return type:

dict[str, Any]

to_json(*, indent=None)[source]

Serialize the model to JSON.

Parameters:

indent (int | None)

Return type:

str

class pymixef.PatternMixtureResult(data, response, imputed_column, stratified_by, records, source_fingerprint)[source]

Bases: object

Adjusted completed data paired with a row-level sensitivity audit.

Parameters:

  • data (ColumnarData)

  • response (str)

  • imputed_column (str | None)

  • stratified_by (tuple[str, ...])

  • records (tuple[PatternMixtureRecord, ...])

  • source_fingerprint (str)

data: ColumnarData
response: str
imputed_column: str | None
stratified_by: tuple[str, ...]
records: tuple[PatternMixtureRecord, ...]
source_fingerprint: str
property adjusted_rows: int

Number of explicitly imputed response values adjusted.

to_dict()[source]

Return serializable metadata without duplicating the full adjusted data.

Return type:

dict[str, Any]

exception pymixef.PluginError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: PyMixEFError

A plugin registration or discovery operation failed.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'PLUGIN-ERROR-001'
exception pymixef.PyMixEFError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: Exception

Base class for all expected PyMixEF failures.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'PYMIXEF-ERROR-001'
to_dict()[source]

Return a JSON-compatible diagnostic record.

Return type:

dict[str, Any]

class pymixef.Random(expression, group, covariance='unstructured', correlated=None)[source]

Bases: object

One structured random-effects declaration.

Parameters:

  • expression (str)

  • group (str)

  • covariance (str)

  • correlated (bool | None)

expression: str
group: str
covariance: str
correlated: bool | None
class pymixef.RandomStreamManager(seed, namespace='pymixef')[source]

Bases: object

Create order-independent NumPy Philox streams from a recorded root seed.

Parameters:

  • seed (int)

  • namespace (str)

seed: int
namespace: str
generator(component, *, replicate=0, chain=0)[source]
Parameters:

  • component (str)

  • replicate (int)

  • chain (int)

Return type:

Generator

replicates(component, count)[source]
Parameters:

  • component (str)

  • count (int)

Return type:

Iterable[Generator]

to_dict()[source]
Return type:

dict[str, object]

class pymixef.ReproducibilityClass(*values)[source]

Bases: StrEnum

Numerical reproducibility guarantee declared by an engine.

BITWISE = 'bitwise'
DETERMINISTIC_TOLERANCE = 'deterministic-with-tolerance'
STOCHASTIC_MONTE_CARLO = 'stochastic-with-monte-carlo-error'
class pymixef.Response(name, unit=None)[source]

Bases: object

Explicit response declaration for the structured builder.

Parameters:

  • name (str)

  • unit (str | None)

name: str
unit: str | None
class pymixef.RunManifest(manifest_schema_version, package_version, created_at_utc, model_ir_hash, data_hash, engine, method, settings, seeds, reproducibility_class, environment, elapsed_seconds=None, output_hashes=<factory>, source=<factory>, convergence=<factory>, warnings=())[source]

Bases: object

Complete, serializable description of a PyMixEF execution.

Parameters:

  • manifest_schema_version (str)

  • package_version (str)

  • created_at_utc (str)

  • model_ir_hash (str)

  • data_hash (str)

  • engine (str)

  • method (str)

  • settings (Mapping[str, Any])

  • seeds (Mapping[str, int])

  • reproducibility_class (str)

  • environment (Mapping[str, Any])

  • elapsed_seconds (float | None)

  • output_hashes (Mapping[str, str])

  • source (Mapping[str, Any])

  • convergence (Mapping[str, Any])

  • warnings (tuple[Mapping[str, Any], ...])

manifest_schema_version: str
package_version: str
created_at_utc: str
model_ir_hash: str
data_hash: str
engine: str
method: str
settings: Mapping[str, Any]
seeds: Mapping[str, int]
reproducibility_class: str
environment: Mapping[str, Any]
elapsed_seconds: float | None
output_hashes: Mapping[str, str]
source: Mapping[str, Any]
convergence: Mapping[str, Any]
warnings: tuple[Mapping[str, Any], ...]
classmethod capture(*, model_ir, data, engine, method, settings=None, seeds=None, reproducibility_class=ReproducibilityClass.DETERMINISTIC_TOLERANCE, elapsed_seconds=None, source=None, convergence=None, warnings=())[source]
Parameters:

  • model_ir (Any)

  • data (Any)

  • engine (str)

  • method (str)

  • settings (Mapping[str, Any] | None)

  • seeds (Mapping[str, int] | None)

  • reproducibility_class (ReproducibilityClass | str)

  • elapsed_seconds (float | None)

  • source (Mapping[str, Any] | None)

  • convergence (Mapping[str, Any] | None)

  • warnings (Sequence[Mapping[str, Any]])

Return type:

RunManifest

classmethod from_dict(value)[source]
Parameters:

value (Mapping[str, Any])

Return type:

RunManifest

to_dict()[source]
Return type:

dict[str, Any]

with_outputs(outputs)[source]

Return an immutable copy carrying hashes of named result components.

Parameters:

outputs (Mapping[str, Any])

Return type:

RunManifest

exception pymixef.UnsupportedCapabilityError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: PyMixEFError

No selected engine can execute a requested scientific capability.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'ENGINE-UNSUPPORTED-001'
exception pymixef.ValidationError(message, *, code=None, remediation=None, details=None, source_location=None)[source]

Bases: PyMixEFError

A model failed deterministic semantic validation.

Parameters:

  • message (str)

  • code (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any] | None)

  • source_location (str | None)

Return type:

None

default_code = 'MODEL-VALIDATION-001'
class pymixef.WarningRecord(code, severity, message, component=None, remediation=None, details=<factory>)[source]

Bases: object

Machine-readable scientific or numerical warning.

Parameters:

  • code (str)

  • severity (str)

  • message (str)

  • component (str | None)

  • remediation (str | None)

  • details (Mapping[str, Any])

code: str
severity: str
message: str
component: str | None
remediation: str | None
details: Mapping[str, Any]
to_dict()[source]
Return type:

dict[str, Any]

pymixef.approximation_sensitivity(fit_function, scenarios, *, materiality, baseline=None)[source]

Refit named approximation settings and compare aligned outputs.

fit_function receives an independent deep copy of one settings mapping per scenario. The baseline must succeed; other failures are retained with scenario, exception type, and message. Successful fits must expose the same parameter names and an aligned parameter covariance matrix. The tidy result reports parameter, standard-error, and objective changes relative to the baseline.

materiality must define nonnegative thresholds named parameter_relative, standard_error_relative, and objective_absolute. Per-row flags preserve the caller’s scientific decision rule instead of embedding an undocumented universal threshold.

This callback-based contract supports sensitivity analyses such as Laplace optimizer tolerances, MMRM covariance/degree-of-freedom choices, or ODE solver tolerances without embedding engine-specific assumptions.

Parameters:

  • fit_function (Callable[[Mapping[str, Any]], FitResult])

  • scenarios (Mapping[str, Mapping[str, Any]])

  • materiality (Mapping[str, float])

  • baseline (str | None)

Return type:

ApproximationSensitivityResult

pymixef.bootstrap(fit_function, data, *, n_replicates, seed, cluster=None, checkpoint=None, resume=True)[source]

Run a nonparametric row or cluster bootstrap with restartable checkpoints.

Parameters:

  • fit_function (Callable[[Mapping[str, ndarray]], FitResult])

  • data (Any)

  • n_replicates (int)

  • seed (int)

  • cluster (str | None)

  • checkpoint (str | Path | None)

  • resume (bool)

Return type:

BootstrapResult

pymixef.change_impact(paths)[source]

Classify changed paths and recommend a conservative validation subset.

This static policy only reports test targets; it does not inspect diffs or execute the recommended tests.

Parameters:

paths (Iterable[str | PathLike[str]])

Return type:

dict[str, Any]

pymixef.create_validation_bundle(result, path, *, analysis_data=None, include_data=False, additional_files=())[source]

Create a deterministic, self-describing validation evidence archive.

Raw analysis data is excluded by default. Set include_data=True only after confirming that the destination may contain the supplied data.

Parameters:

  • result (FitResult)

  • path (str | Path)

  • analysis_data (Any | None)

  • include_data (bool)

  • additional_files (Sequence[str | Path])

Return type:

Path

pymixef.diff_models(before, after)[source]

Compare two model IR objects and classify every semantic change.

Parameters:
Return type:

ModelDiff

pymixef.fit(formula, *, data, family=None, residual=None, method=None, engine=None, inference=None, zero_inflation=None, dispersion=None, shape=None, missing='drop', **settings)[source]

Fit a formula or prebuilt model through static compatibility dispatch.

Parameters:

  • formula (str | Model)

  • data (Any)

  • family (Family | None)

  • residual (Any)

  • method (str | None)

  • engine (str | None)

  • inference (str | None)

  • zero_inflation (str | None)

  • dispersion (str | None)

  • shape (str | None)

  • missing (str)

  • settings (Any)

Return type:

FitResult

pymixef.get_capability(identifier)[source]

Look up a capability by stable requirement identifier.

Parameters:

identifier (str)

Return type:

Capability

pymixef.group_influence(fit_function, data, *, group, baseline=None, approximation=None)[source]

Measure influence by deleting complete grouping levels and refitting.

fit_function receives a column mapping and must return a fit-like object with parameters, finite objective, convergence, and an archived fixed_effect_rank in convergence engine metrics or result extras; parameter_covariance is optional. If baseline is omitted, the callback first fits the full data. Every subsequent callback receives all rows except one complete grouping level—individual rows are never deleted in isolation.

An optional approximation(group_value, baseline) callback can return approximate delete-group parameter estimates. The result then records the approximation error beside the full-refit change, making the approximation auditable rather than silently substituting it for a refit.

Parameters:

  • fit_function (Callable[[Mapping[str, ndarray]], Any])

  • data (Any)

  • group (str)

  • baseline (Any | None)

  • approximation (Callable[[Any, Any], Mapping[str, float]] | None)

Return type:

GroupInfluenceResult

pymixef.iter_capabilities(*, implemented=None, stage=None, maturity=None)[source]

Filter the immutable capability registry.

Parameters:

  • implemented (bool | None)

  • stage (str | None)

  • maturity (Maturity | None)

Return type:

Iterable[Capability]

pymixef.load(*, verify_integrity=True, require_sidecar=False)

Load an archived result and verify its hash sidecar when available.

Legacy or externally produced JSON may omit the sidecar. Set require_sidecar=True when the calling workflow requires an integrity record. Integrity verification can be disabled only explicitly.

Parameters:

  • verify_integrity (bool)

  • require_sidecar (bool)

Return type:

FitResult

pymixef.pattern_mixture_adjust(data, *, response, imputed, delta, by=None)[source]

Apply an audited delta adjustment only to explicitly imputed responses.

This is a controlled pattern-mixture data transformation, not an imputation algorithm. Callers first complete the response under their primary missing-at-random procedure, then identify those imputed cells with imputed. A scalar delta applies one response-scale shift. A mapping requires by and supplies a shift for every selected stratum; with multiple by columns, mapping keys are tuples in the same order.

Observed response values and every non-response column are preserved exactly. The returned records retain source row identities, the base imputed value, applied shift, and adjusted value.

Parameters:

  • data (Any)

  • response (str)

  • imputed (str | ArrayLike)

  • delta (float | Mapping[Any, float])

  • by (str | Sequence[str] | None)

Return type:

PatternMixtureResult

pymixef.random_streams(seed, *, namespace='pymixef')[source]

Construct a named counter-based stream manager.

Parameters:

  • seed (int)

  • namespace (str)

Return type:

RandomStreamManager

pymixef.render_report(result, path)[source]

Render a result as Markdown, HTML, PDF, or Word.

PDF and Word require the optional report dependencies. All formats are generated from the same immutable Markdown content.

Parameters:
Return type:

Path

pymixef.traceability_matrix()[source]

Return the built-in public traceability matrix.

Return type:

tuple[TraceabilityRecord, …]

pymixef.verify_validation_bundle(path)[source]

Verify internal hashes and return the archived manifest.

Parameters:

path (str | Path)

Return type:

dict[str, Any]

Subpackages

Submodules

On this page
Show Source