pymixef.ir module

Versioned, immutable intermediate representation for scientific models.

The IR records mathematical meaning independently of a formula parser or estimation backend. JSON is canonicalized for stable equality, hashing, and change-impact reports; pickle is intentionally not part of the persistence contract.

class pymixef.ir.CovarianceIR(structure, target='random-effects', dimension=None, index=None, group=None, options=<factory>, *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A covariance block attached to random effects or observations.

Parameters:

  • structure (str)

  • target (str)

  • dimension (int | None)

  • index (str | None)

  • group (str | None)

  • options (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]]])

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

structure: str
target: str
dimension: int | None
index: str | None
group: str | None
options: 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]]]
node_type: ClassVar[str] = 'covariance'
class pymixef.ir.DiffEntry(category, path, change, before, after)[source]

Bases: object

One atomic deterministic change between two model IR documents.

Parameters:

  • category (str)

  • path (str)

  • change (str)

  • before (Any)

  • after (Any)

category: str
path: str
change: str
before: Any
after: Any
to_dict()[source]
Return type:

dict[str, Any]

class pymixef.ir.EventIR(event_type, target=None, fields=<factory>, *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A canonical event declaration.

Parameters:

  • event_type (str)

  • target (str | None)

  • fields (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]]])

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

event_type: str
target: str | None
fields: 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]]]
node_type: ClassVar[str] = 'event'
class pymixef.ir.FixedEffectIR(name, expression, columns=(), *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A resolved fixed-effect term and its generated model-matrix columns.

Parameters:

  • name (str)

  • expression (str)

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

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

name: str
expression: str
columns: tuple[str, ...]
node_type: ClassVar[str] = 'fixed_effect'
class pymixef.ir.IRNode(*, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: object

Metadata common to all mathematical IR nodes.

Parameters:

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

dimensions: tuple[int | str, ...]
support: str
transform: str
unit: str | None
differentiability: str
dependencies: tuple[str, ...]
source_location: str | None
annotations: 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]]]
node_type: ClassVar[str] = 'node'
to_dict()[source]

Return a JSON-compatible representation including the node tag.

Return type:

dict[str, Any]

class pymixef.ir.LikelihoodIR(response, family='gaussian', link='identity', component='conditional', formulas=<factory>, *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

An observation likelihood component and its distributional predictors.

Parameters:

  • response (str)

  • family (str)

  • link (str)

  • component (str)

  • formulas (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]]])

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

response: str
family: str
component: str
formulas: 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]]]
node_type: ClassVar[str] = 'likelihood'
class pymixef.ir.ModelDiff(before_hash, after_hash, entries=())[source]

Bases: object

Serializable model change-impact report.

Parameters:

  • before_hash (str)

  • after_hash (str)

  • entries (tuple[DiffEntry, ...])

before_hash: str
after_hash: str
entries: tuple[DiffEntry, ...]
property equal: bool
property categories: tuple[str, ...]
to_dict()[source]
Return type:

dict[str, Any]

to_json(*, indent=None)[source]
Parameters:

indent (int | None)

Return type:

str

class pymixef.ir.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]]]
to_dict()[source]

Return a JSON-compatible schema-v1 document.

Return type:

dict[str, Any]

canonical_json()[source]

Return deterministic compact JSON used for identity and hashes.

Return type:

str

to_json(*, indent=None)[source]

Serialize the model to JSON.

Parameters:

indent (int | None)

Return type:

str

property semantic_hash: str

SHA-256 digest of the canonical mathematical representation.

property hash: str

Alias for semantic_hash.

semantically_equal(other)[source]

Whether two models have identical canonical scientific meaning.

Parameters:

other (object)

Return type:

bool

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

diff(other)[source]

Return a deterministic semantic change report.

Parameters:

other (ModelIR)

Return type:

ModelDiff

class pymixef.ir.OutputIR(name, expression, output_kind='prediction', *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A named model output or derived quantity.

Parameters:

  • name (str)

  • expression (str)

  • output_kind (str)

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

name: str
expression: str
output_kind: str
node_type: ClassVar[str] = 'output'
class pymixef.ir.ParameterIR(name, initial=None, bounds=None, fixed=False, role='parameter', *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

One parameter and its explicit optimizer-to-natural transform.

Parameters:

  • name (str)

  • initial (float | tuple[float, ...] | None)

  • bounds (tuple[float | None, float | None] | None)

  • fixed (bool)

  • role (str)

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

name: str
initial: float | tuple[float, ...] | None
bounds: tuple[float | None, float | None] | None
fixed: bool
role: str
node_type: ClassVar[str] = 'parameter'
class pymixef.ir.PredictorIR(name, expression, kind='derived', *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A safe, resolved predictor expression.

Parameters:

  • name (str)

  • expression (str)

  • kind (str)

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

name: str
expression: str
kind: str
node_type: ClassVar[str] = 'predictor'
class pymixef.ir.PriorIR(target, distribution, parameters=<factory>, *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A prior distribution explicitly attached to a parameter.

Parameters:

  • target (str)

  • distribution (str)

  • parameters (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]]])

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

target: str
distribution: str
parameters: 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]]]
node_type: ClassVar[str] = 'prior'
class pymixef.ir.RandomEffectIR(terms, group, correlated=True, covariance='unstructured', known_matrix=None, *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A random-effect block with explicit grouping and correlation semantics.

Parameters:

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

  • group (str)

  • correlated (bool)

  • covariance (str)

  • known_matrix (tuple[tuple[float, ...], ...] | None)

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

terms: tuple[str, ...]
group: str
correlated: bool
covariance: str
known_matrix: tuple[tuple[float, ...], ...] | None
node_type: ClassVar[str] = 'random_effect'
class pymixef.ir.StateEquationIR(state, rhs, equation_kind='ode', initial=0.0, *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A differential or algebraic state equation.

Parameters:

  • state (str)

  • rhs (str)

  • equation_kind (str)

  • initial (str | float)

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

state: str
rhs: str
equation_kind: str
initial: str | float
node_type: ClassVar[str] = 'state_equation'
class pymixef.ir.TransformIR(name, kind, options=<factory>, *, dimensions=(), support='real', transform='identity', unit=None, differentiability='differentiable', dependencies=(), source_location=None, annotations=<factory>)[source]

Bases: IRNode

A named transform node used by one or more parameters.

Parameters:

  • name (str)

  • kind (str)

  • options (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]]])

  • dimensions (tuple[int | str, ...])

  • support (str)

  • transform (str)

  • unit (str | None)

  • differentiability (str)

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

  • source_location (str | None)

  • annotations (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]]])

name: str
kind: str
options: 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]]]
node_type: ClassVar[str] = 'transform'
pymixef.ir.diff_models(before, after)[source]

Compare two model IR objects and classify every semantic change.

Parameters:
Return type:

ModelDiff

pymixef.ir.migrate_ir(document, *, target_version=MODEL_IR_SCHEMA_VERSION)[source]

Migrate a serialized IR through registered explicit forward edges.

Unknown versions and downgrade attempts are rejected rather than guessed. The input mapping is never mutated.

Parameters:

  • document (Mapping[str, Any])

  • target_version (str)

Return type:

dict[str, Any]

pymixef.ir.model_diff(before, after)

Compare two model IR objects and classify every semantic change.

Parameters:
Return type:

ModelDiff

pymixef.ir.register_ir_migration(from_version, to_version, migration, *, replace=False)[source]

Register one explicit forward migration edge.

Parameters:

  • from_version (str)

  • to_version (str)

  • migration (Callable[[dict[str, Any]], dict[str, Any]])

  • replace (bool)

Return type:

None

On this page
Show Source