mixle.data.structure module

Sample structure – the exchangeability tag carried by every DataSource.

seq_encode(data, num_chunks=C) partitions a dataset by striding – chunk i is data[i::C] – which silently reorders observations. That is correct only when the records are exchangeable. This module makes the intended joint structure explicit so partitioning is justified rather than assumed, and so a model can be checked against the data it is handed:

  • IID – independent & identically distributed records.

  • EXCHANGEABLE – the joint law is permutation-invariant (de Finetti): order is irrelevant

    but latent coupling is allowed (mixtures, Dirichlet-process models, …).

  • PARTIALLY_EXCHANGEABLE (by) – exchangeable within groups keyed by by (hierarchical /

    grouped / panel data): groups must stay intact on a partition.

  • SEQUENTIAL – each record is a whole ordered sequence (HMM / Markov / Hawkes / AR); the

    records are mutually exchangeable, so they may be strided, but a record is never split internally (the encoder owns the within-record order).

The first three (and SEQUENTIAL, whose records are atomic) may stride records freely; only PARTIALLY_EXCHANGEABLE constrains partitioning – groups are distributed whole. The default for an un-annotated dataset is EXCHANGEABLE, which is exactly today’s striding behavior, so nothing changes until a user opts in by tagging a source.

class SampleStructure(kind, by=None)[source]

Bases: object

The joint structure of a dataset’s records (an exchangeability class).

Parameters:
kind: str
by: str | Callable[[Any], Any] | None = None
property strides_records: bool

True if records may be strided/shuffled across partitions (everything but grouped data).

group_key(record)[source]

Return the group key of record for partial exchangeability (else None).

Parameters:

record (Any)

Return type:

Any

partially_exchangeable(by)[source]

Return a PARTIALLY_EXCHANGEABLE structure grouped by field name or key function by.

Parameters:

by (str | Callable[[Any], Any])

Return type:

SampleStructure

supported_structures(model)[source]

Return the SampleStructure kinds a model/estimator can consume (by capability + name).

Parameters:

model (Any)

Return type:

frozenset[str]

check_model_structure(model, structure, *, strict=False)[source]

Warn (or, if strict, raise) when a model cannot consume a source’s sample structure.

Catches the silent footgun: a source tagged SEQUENTIAL handed to an i.i.d. leaf (“did you mean an HMM?”), or grouped data handed to a model that ignores groups. A no-op when compatible.

Parameters:

  • model (Any)

  • structure (SampleStructure)

  • strict (bool)

Return type:

None