mixle.dist module ¶

seq_encode(data, encoder=None, estimator=None, model=None, num_chunks=1, chunk_size=None)[source]

Sequence encode a sequence of iid observations from a distribution corresponding to ‘encoder’.

Takes data of type Union[Sequence[T], pyspark.rdd.RDD], where the data type of the DataSequenceEncoder object’s corresponding distribution is type T.

If not RDD, returns a List[Tuple[int, T1]], with each list entry being a tuple containing the number of observations in the sequence (chunk_size), and an encoded sequence of the observations having type T1. The list has length num_chunks.

RDD version with receive the Tuple of chunk_size and encoded data of type T1 for each corresponding node.

Parameters:

data (Union[Sequence[T], pyspark.rdd.RDD]) – Sequence of iid observations of data type consistent with ‘encoder’.
encoder (Optional[DataSequenceEncoder]) – A DataSequenceEncoder object for sequence encoding iid sequences.
estimator (Optional[ParameterEstimator]) – An estimator to create DataSequenceEncoder from.
model (Optional[SequenceEncodableProbabilityDistribution]) – A distribution to create DataSequenceEncoder from.
num_chunks (int) – Number of chunks to split the data into. Useful for distributed data sets.
chunk_size (Optional[int]) – Approximate size of chunks to determine num_chunks above.

Returns:

Encoded data ready for vectorized seq_* methods.

Return type:

pyspark.rdd.RDD | list[tuple[int, Any]]

seq_log_density(enc_data, estimate)[source]

Vectorized evaluation of ‘estimate’ log-density for each observation in enc_data.

If ‘estimate’ is input as a List of numpy arrays. Each list entry corresponds to the seq_log_density calls of all the encoded data for each List entry of estimate.

If ‘estimate’ is a single SequenceEncodableProbabilityDistribution instance. The log_density of every observation in the ‘enc_data’ data set is returned as a list.

Parameters:

enc_data (Union[List[Tuple[int, T]], 'pyspark.rdd.RDD']) – Sequence encoded data of format matching output of seq_encode() function.
estimate (SequenceEncodableProbabilityDistribution) – Distribution to use for log_density evaluations. Must be consistent with enc_data.

Returns:

List[np.ndarray[float]] or List[float] depending on input.

Return type:

list[np.ndarray]

seq_log_density_sum(enc_data, estimate)[source]

Vectorized evaluation of total count and total log-density over encoded data.

The returned pair contains the observation count represented by enc_data and the sum of log_density over those encoded observations.

Parameters:

enc_data (Union[List[Tuple[int, T]], 'pyspark.rdd.RDD']) – Sequence encoded data of format matching output of seq_encode() function.
estimate (SequenceEncodableProbabilityDistribution) – Distribution to use for log_density evaluations. Must be consistent with enc_data.

Returns:

Tuple of sum of total obs, and sum of log_density of estimate at all encoded data observations.

Return type:

tuple[float, float]

log_density(data, model)[source]

Per-observation log-density of ‘model’ over raw (unencoded) ‘data’.

Convenience wrapper that encodes ‘data’ with the model’s own encoder, evaluates the vectorized seq_log_density, and returns a single flat numpy array aligned to the input order – the common need that otherwise requires the seq_encode / seq_log_density / np.concatenate boilerplate. For a distributed RDD the densities are collected to the driver in partition order.

Parameters:

data (Union[Sequence[T], pyspark.rdd.RDD]) – Raw iid observations of data type consistent with ‘model’.
model (SequenceEncodableProbabilityDistribution) – Distribution to score the observations under.

Returns:

np.ndarray of per-observation log-densities.

Return type:

np.ndarray

density(data, model)[source]

Per-observation density of ‘model’ over raw (unencoded) ‘data’.

Exponentiated companion to log_density(); returns a flat numpy array of densities aligned to the input order.

Parameters:

data (Union[Sequence[T], pyspark.rdd.RDD]) – Raw iid observations of data type consistent with ‘model’.
model (SequenceEncodableProbabilityDistribution) – Distribution to score the observations under.

Returns:

np.ndarray of per-observation densities.

Return type:

np.ndarray

load_models(x)[source]

Reconstruct a model or collection of models from dump_models() JSON.

Parameters:: x (str)

dump_models(x, *, verify=True)[source]

Serialize a stats model or collection of models to safe strict JSON.

The JSON is read back through load_models() before it is returned, and a failure is raised here rather than handed to whoever later tries to load it. Encoding on its own does not establish that: the encoder accepts any registered class’s __dict__, while the decoder also requires that state to reconstruct through the class’s own constructor. Families whose estimator pins a fit annotation onto the fitted object, and families whose state names a parameter differently from the constructor’s, encode cleanly and then refuse to load – so without this check dump_models returns text that load_models cannot read, and the bill arrives in another process on another day.

mixle.propose() (and mixle.Model) return a Model wrapper, not a stats model: pass model.fitted, the fitted distribution it wraps, rather than the wrapper itself, which is not registered for serialization and is refused with a SerializationError naming register_serializable_callable (a detour meant for user callables, not for this).

Pass verify=False for text wanted to inspect rather than to reload; the JSON is byte-identical either way and only the read back is skipped. It is the way to get at the parameters of a model whose family has no working decoder yet, since the written state is complete even when the reader refuses it.

Parameters:: verify (bool)
Return type:: str

class DistributionEnumerator(dist)[source]

Bases: ABC

Lazy iterator over the support of dist in non-increasing probability order.

Yields (value, log_prob) pairs, possibly infinitely many. Contract:

Each support value is yielded exactly once (deduplication is the enumerator’s responsibility).
log_prob equals dist.log_density(value) up to float round-off (~1e-10), and the sequence of log_probs is non-increasing up to the same tolerance.
Values with zero probability are skipped, never yielded.
Ties are broken deterministically by insertion order; no further guarantee.

Parameters:: dist (SequenceEncodableProbabilityDistribution)

top_k(k)[source]

Return the k most probable (value, log_prob) pairs (fewer if the support is smaller).

Parameters:: k (int)
Return type:: list[tuple[Any, float]]

top_p(p, max_items=None)[source]

Return the smallest descending-probability prefix whose total probability reaches p.

The nucleus / minimal high-probability set: because values are yielded in non-increasing probability order, the returned prefix is a minimum-size set of outcomes whose summed mass is >= p (e.g. p=0.95 gives a 95%-coverage support set – the discrete analogue of nucleus sampling). Accumulation stops as soon as the cumulative probability reaches p.

max_items caps how many values are pulled so an infinite or heavy-tailed support cannot run away. A cap is mandatory when the support has no known finite cardinality. The returned list-compatible NucleusResult reports whether the target was reached, the accumulated mass, and whether a cap stopped the search.

Parameters:

p (float) – Target cumulative probability in [0, 1].
max_items (Optional[int]) – Hard cap on the number of values pulled.

Returns:

A list-compatible nucleus result with termination provenance.

Return type:

NucleusResult

quantized_index(max_bits, bin_width_bits=1.0)[source]

Precompute a bounded bit-quantized index over this enumeration.

The index groups values by floor((-log2 p(x)) / bin_width_bits), includes only values with -log2 p(x) <= max_bits, and returns exact log probabilities for indexed values. Building the index consumes this enumerator.

Parameters:

max_bits (float) – Maximum information content in bits to index.
bin_width_bits (float) – Width of each quantized probability bin in bits.

Returns:

mixle.enumeration.algorithms.QuantizedEnumerationIndex.

rank(value)[source]

Rank and cumulative probability of value in the descending-probability order.

Returns a DensityRankResult with .rank (0-based count of strictly-more-probable outcomes; None if only the sampling estimate was used) and .cumulative_probability (G(value) = P(p(Y) >= p(value))). Exact head enumeration where the support is countable, with a Monte-Carlo fallback for the deep tail.

Parameters:: value (Any)

seek(index)[source]

The value at descending-probability index (0-based) – the inverse of rank().

Returns a CountDPSeekResult carrying the value and a provable [rank_lower, rank_upper] bracket. Uses the structural count-DP for decomposable families, so arbitrarily deep indices are reachable without enumerating the prefix.

Parameters:: index (int)

seek_certified(index)[source]

The value at descending index with a GUARANTEED bracket on its TRUE marginal rank.

Unlike seek() – whose bracket bounds only the tropical rank for a marginal family (mixture/HMM) – this widens the rank window by the family’s tropical_displacement_bits and divides out the component over-count, so the returned MarginalSeekResult [true_rank_lower, true_rank_upper] provably contains #{u : log p(u) > log p(value)}. It pins the rank exactly (.exact) for decomposable / provably-disjoint families and for shallow indices, and otherwise returns the certified provable envelope. For a decomposable family it agrees with seek().

Parameters:: index (int)

cumulative(value)[source]

G(value) = P(p(Y) >= p(value)) – total mass of outcomes at least as probable as value.

Returns a CumulativeProbabilityResult with .probability plus explicit certification (.exact, .dropped_upper) of what that figure rests on.

Parameters:: value (Any)

nucleus_size(p)[source]

Size of top_p() (the minimal >= p-mass set) WITHOUT materializing it.

Returns a CountDPTopPResult with a provable size bracket, from the structural count-DP – usable when the nucleus is far too large to list.

Parameters:: p (float)

from_index(start, stop=None)[source]

Iterate (value, log_prob) in descending-probability order starting at structural start.

Yields the same stream as iterating a fresh enumerator but beginning at index start (and ending before stop if given). A fresh underlying enumeration is used, so this does not consume self. (Decomposable families admit a direct structural jump via the count-budget index; the current implementation skips the best-first prefix – the structural fast path is a WS-3 performance follow-up.)

Parameters:

start (int)
stop (int | None)

exception EnumerationError(dist, path='', reason='')[source]

Bases: NotImplementedError

Raised when a distribution (or a child of a combinator) cannot enumerate its support.

The path argument identifies the offending child within a combinator, e.g. ‘CompositeDistribution.dists[1]’.

Parameters:

dist (Any)
path (str)
reason (str)

Return type:

None

class NucleusResult(items, *, target_probability, cumulative_probability, reached_target, capped, exhausted)[source]

Bases: list[tuple[Any, float]]

List-compatible nucleus prefix with explicit termination provenance.

Parameters:

items (list[tuple[Any, float]])
target_probability (float)
cumulative_probability (float)
reached_target (bool)
capped (bool)
exhausted (bool)

exception KeyValidationError[source]

Bases: ValueError

Raised when keyed sufficient-statistic sites are incompatible.

A key denotes an equality constraint across model sites. Sites sharing a key must therefore have the same accumulator family and compatible estimator settings before their sufficient statistics are pooled.

validate_estimator_keys(estimator)[source]

Validate keyed estimator and accumulator sites before EM folds stats.

The validator catches the classic keying footgun: two different families, or two sites with incompatible estimator settings, accidentally sharing the same key string. Validation is intentionally protocol-level and best-effort; a family can still perform stricter checks in its own factory if needed.

Parameters:: estimator (ParameterEstimator)
Return type:: None

encoded_nbytes(x)[source]

Return an approximate byte size for nested encoded array payloads.

Encoders mostly return arrays or tuples/lists/dicts of arrays. The helper keeps accounting structural and deterministic; Python object overhead is included only for scalar leaves where no array-native byte count exists.

Parameters:: x (Any)
Return type:: int

scale_suff_stat(x, c)[source]

Return x with numeric sufficient-statistic leaves multiplied by c.

Parameters:

x (Any)
c (float)

Return type:

class EncodedData(count, payload, engine, nbytes, encoder=None)[source]

Bases: object

A one-chunk encoded payload with planner-visible metadata.

Parameters:

count (int)
payload (Any)
engine (ComputeEngine)
nbytes (int)
encoder (DataSequenceEncoder | None)

classmethod from_payload(payload, count, encoder=None, engine=None)[source]

Wrap an already encoded payload with count, engine, and byte metadata.

Parameters:

payload (Any)
count (int)
encoder (DataSequenceEncoder | None)
engine (ComputeEngine | None)

Return type:

EncodedData

classmethod from_data(data, encoder, engine=None)[source]

Encode raw data once and attach planner-visible metadata.

Parameters:

data (Any)
encoder (DataSequenceEncoder)
engine (ComputeEngine | None)

Return type:

EncodedData

as_seq_chunk()[source]

Return the legacy (count, encoded_payload) chunk tuple.

Return type:: tuple[int, Any]

class ResidentEncodedPayload(host_payload, engine_payload)[source]

Bases: object

Pair a host encoding with a resident engine encoding for one chunk.

Parameters:

host_payload (Any)
engine_payload (Any)

as_encoded_data(payload, count, encoder=None, engine=None)[source]

Wrap an existing encoded payload with count, engine, and byte metadata.

Parameters:

payload (Any)
count (int)
encoder (DataSequenceEncoder | None)
engine (ComputeEngine | None)

Return type:

EncodedData

move_encoded_payload(payload, engine)[source]

Move numeric encoded arrays into engine while preserving object fields.

Encoders remain backend-agnostic and produce their historical Python/NumPy payloads. Orchestrators can call this exactly once after encoding a shard so scoring kernels see resident engine arrays. Object/string arrays and non-array Python metadata stay on the host because many distribution encodings intentionally carry labels, maps, or structural metadata.

Parameters:

payload (Any)
engine (ComputeEngine)

Return type:

class DistributionCapabilities(engine_ready=('numpy',), kernel_status='generic', numpy_only_reason=None)[source]

Bases: object

Runtime capability metadata for a distribution family.

Parameters:

engine_ready (tuple[str, ...])
kernel_status (str)
numpy_only_reason (str | None)

supports_engine(engine)[source]

Return whether this metadata allows execution on engine.

Parameters:: engine (Any)
Return type:: bool

property is_permanently_numpy_only: bool: Return true for families intentionally excluded from tensor engines.

capabilities_for(x)[source]

Return registered capabilities for a distribution instance or class.

Parameters:: x (Any)
Return type:: DistributionCapabilities

numpy_only_distribution_types()[source]

Return families intentionally kept on the NumPy execution path.

This excludes transitional legacy_numpy families: those may gain backend declarations later. The returned families have permanent distribution-owned reasons explaining why generic tensor engines are not a good fit.

Return type:: tuple[type[Any], …]

register_capabilities(dist_type, capabilities)[source]

Parameters:

dist_type (type[Any])
capabilities (DistributionCapabilities)

Return type:

None

registered_capability_types()[source]

Return distribution classes with explicitly registered capabilities.

Return type:: tuple[type[Any], …]

supported_engines(x)[source]

Return engine names supported by a distribution instance or class.

Parameters:: x (Any)
Return type:: tuple[str, …]

class DistributionDeclaration(name, distribution_type, parameters, statistics, support, children=(), child_roles=(), differentiable=True, exponential_family=None, legacy_sufficient_statistics=None)[source]

Bases: object

Metadata needed by generated kernels and future autograd paths.

Parameters:

name (str)
distribution_type (type[Any])
parameters (tuple[ParameterSpec, ...])
statistics (tuple[StatisticSpec, ...])
support (str)
children (tuple[DistributionDeclaration, ...])
child_roles (tuple[str, ...])
differentiable (bool)
exponential_family (ExponentialFamilySpec | None)
legacy_sufficient_statistics (Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None)

parameter_values(dist)[source]

Extract declared parameter values from a distribution instance.

Parameters:: dist (Any)
Return type:: dict[str, Any]

statistic_values(suff_stat)[source]

Map a legacy accumulator value into declared statistic names.

Parameters:: suff_stat (Any)
Return type:: dict[str, Any]

property parameter_names: tuple[str, ...]: Return declared parameter names in storage order.

property statistic_names: tuple[str, ...]: Return declared sufficient-statistic names in accumulator order.

property has_exponential_family: bool: Return whether generated exponential-family scoring is available.

class ExponentialFamilySpec(sufficient_statistics, natural_parameters, log_partition, base_measure=None, sufficient_statistics_from_params=None, base_measure_from_params=None, legacy_sufficient_statistics=None, analytic_mean_parameters=None, log_partition_from_natural=None, fixed_base=True, runtime_scoring=True)[source]

Bases: object

Conditional exponential-family pieces for generated scalar scoring.

Parameters:

sufficient_statistics (Callable[[Any, Any], tuple[Any, ...]])
natural_parameters (Callable[[dict[str, Any], Any], tuple[Any, ...]])
log_partition (Callable[[dict[str, Any], Any], Any])
base_measure (Callable[[Any, Any], Any] | None)
sufficient_statistics_from_params (Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None)
base_measure_from_params (Callable[[Any, dict[str, Any], Any], Any] | None)
legacy_sufficient_statistics (Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None)
analytic_mean_parameters (Callable[[dict[str, Any], Any], Any] | None)
log_partition_from_natural (Callable[[Any, Any], Any] | None)
fixed_base (bool)
runtime_scoring (bool)

runtime_scoring: bool = True

Whether the generated exp-family form may drive runtime scoring (scalar + stacked + numba).

Set False when the canonical <eta, T(x)> dot form is numerically unsafe as a runtime scorer even though the family is a valid exponential family. The motivating case is the categorical: eta = log(p) has -inf entries for zero-probability categories, so the generic dot product hits 0 * -inf = NaN for observations of other categories (its own seq_log_density avoids this by indexing). With runtime_scoring=False the family keeps its backend_* scoring path while to_exponential_family still exposes the canonical map (valid where p > 0).

class ParameterSpec(name, constraint='real', differentiable=True)[source]

Bases: object

A fitted distribution parameter used by scoring.

Constraints are interpreted by generic generated/scoring utilities. In addition to scalar constraints such as positive and vector/matrix constraints such as simplex_vector, row_simplex_matrix, and column_simplex_matrix, greater_than:<parameter> marks a coupled ordered bound.

Parameters:

name (str)
constraint (str)
differentiable (bool)

class StatisticSpec(name, kind='moment', additive=True, scales=True)[source]

Bases: object

A sufficient-statistic entry produced by accumulation.

Parameters:

name (str)
kind (str)
additive (bool)
scales (bool)

exception BackendCapabilityUnavailableError[source]

Bases: BackendScoringError

Raised only when neither a backend hook nor generated scorer exists.

exception BackendScoringError[source]

Bases: NotImplementedError

Compatibility base for an explicit backend-scoring capability decline.

backend_log_density_sum(dist, enc, engine=NUMPY_ENGINE)[source]

Return the total log likelihood for one encoded payload.

Parameters:

dist (Any)
enc (Any)
engine (ComputeEngine)

Return type:

backend_seq_component_log_density(dist, enc, engine=NUMPY_ENGINE)[source]

Return component log densities when a distribution exposes them.

Parameters:

dist (Any)
enc (Any)
engine (ComputeEngine)

Return type:

backend_seq_log_density(dist, enc, engine=NUMPY_ENGINE)[source]

Return per-row log densities using engine and distribution-local math.

Parameters:

dist (Any)
enc (Any)
engine (ComputeEngine)

Return type:

declaration_issues(x)[source]

Return structural issues in a distribution declaration.

This is intentionally schema-level validation: it checks names, constraints, child roles, and callable exponential-family pieces without importing or special-casing concrete distribution implementations.

Parameters:: x (Any)
Return type:: tuple[str, …]

declaration_for(x)[source]

Return a declaration for a distribution instance or class, if present.

Parameters:: x (Any)
Return type:: DistributionDeclaration | None

declared_distribution_types()[source]

Return classes that currently have declarations.

Return type:: Iterable[type[Any]]

exception GeneratedKernelCompilationError[source]

Bases: RuntimeError

A declared generated kernel failed to trace or compile unexpectedly.

generated_log_density_diagnostics(x, encoded_symbols=None)[source]

Trace a generated scalar log-density formula with the symbolic engine.

The returned dictionary contains the symbolic expression string, referenced data/parameter symbols, operation counts, and expression depth. This is an author-facing inspection tool for declaration-generated kernels; it does not select or execute a runtime backend.

Parameters:

x (Any)
encoded_symbols (Sequence[str] | None)

Return type:

generated_log_density(dist, enc, engine)[source]

Return per-row log densities from declaration-owned scoring metadata.

This is the single-distribution counterpart of generated_stacked_log_density. It gives generic kernels an engine-aware fallback before they drop to legacy NumPy seq_log_density methods, and it stays fully metadata-driven: no caller imports or switches on concrete distribution implementations.

Parameters:

dist (Any)
enc (Any)
engine (Any)

Return type:

generated_stacked_available(dist_type)[source]

Return true when declarations can generate stacked leaf scoring.

Parameters:: dist_type (type[Any])
Return type:: bool

generated_stacked_log_density(enc, params, engine)[source]

Return an (n, k) log-density matrix from declaration-stacked params.

Parameters:

enc (Any)
params (dict[str, Any])
engine (Any)

Return type:

generated_stacked_params(dists, engine)[source]

Stack declared distribution parameters for generated homogeneous-mixture scoring.

The generated path is intentionally conservative: it supports scalar, vector, or matrix per-component parameters that can be broadcast over per-row encoded fields. Non-differentiable support metadata such as integer bounds must still be shared across components unless a family keeps an explicit backend_stacked_* route.

Parameters:

dists (Sequence[Any])
engine (Any)

Return type:

generated_stacked_preferred(dist_type)[source]

Return true when a family explicitly opts into declaration-generated scoring.

Parameters:: dist_type (type[Any])
Return type:: bool

generated_stacked_strategy(dist_type)[source]

Describe the declaration-generated stacked scoring route for a family.

Parameters:: dist_type (type[Any])
Return type:: str

generated_sufficient_statistics(dist, enc, weights, engine)[source]

Return legacy sufficient statistics from declaration-owned row stats.

This is the single-distribution analogue of generated_stacked_sufficient_statistics. It performs row-wise sufficient-statistic algebra on the active engine, then converts only the small legacy payload back across the boundary for the existing estimator M-step.

Parameters:

dist (Any)
enc (Any)
weights (Any)
engine (Any)

Return type:

tuple[Any, …]

generated_sufficient_statistics_available(x)[source]

Return true when a declaration can generate single-distribution stats.

Parameters:: x (Any)
Return type:: bool

generated_numba_log_density(dist, enc)[source]

Return per-row log densities from a declaration-generated numba loop.

The generated loop evaluates the exponential-family form base(x) + T(x) dot eta(theta) - A(theta). Distribution declarations still own the statistical metadata; this helper only lowers the row fold to a nopython scalar loop.

Parameters:

dist (Any)
enc (Any)

Return type:

generated_numba_log_density_available(x)[source]

Return true when declarations can emit a generated numba leaf scorer.

Exponential-family leaves use the stacked exp-family loop; other leaves with a backend_log_density_from_params hook whose per-row formula lowers cleanly to a numba scalar loop (single encoded array, supported ops, scalar parameters) use the generic symbolic-to-numba compiler in _build_generic_numba_kernel().

Parameters:: x (Any)
Return type:: bool

generated_numba_stacked_log_density(enc, params)[source]

Return an (n, k) score matrix from a declaration-generated numba loop.

Parameters:

enc (Any)
params (dict[str, Any])

Return type:

generated_numba_stacked_available(x)[source]

Return true when declarations can emit a generated stacked numba scorer.

Parameters:: x (Any)
Return type:: bool

generated_stacked_sufficient_statistics(enc, weights, params, engine)[source]

Return component-stacked legacy sufficient statistics from declarations.

Parameters:

enc (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

generated_stacked_sufficient_statistics_available(x)[source]

Return true when a declaration can generate resident stacked stats.

Parameters:: x (Any)
Return type:: bool

register_declaration(declaration)[source]

Validate and atomically register one declaration.

Re-registering the same declaration is idempotent. A different declaration for an already registered type is rejected instead of silently changing generated execution semantics process-wide.

Parameters:: declaration (DistributionDeclaration)
Return type:: None

statistic_layout_issues(x, suff_stat)[source]

Return issues mapping a legacy sufficient-statistic payload to a declaration.

This validates the top-level statistic_values(...) arity and, when a declaration exposes child roles, recursively validates child statistic payloads for tuple/list/map-shaped entries. It stays schema-driven and does not import concrete distribution implementations.

Parameters:

x (Any)
suff_stat (Any)

Return type:

tuple[str, …]

validate_declaration(x)[source]

Return a declaration or raise ValueError with schema issues.

Parameters:: x (Any)
Return type:: DistributionDeclaration

validate_statistic_layout(x, suff_stat)[source]

Return a declaration or raise ValueError with statistic-layout issues.

Parameters:

x (Any)
suff_stat (Any)

Return type:

DistributionDeclaration

class RecordDistribution(fields, dists=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Product distribution over mapping records with a fixed field set.

Parameters:

fields (Any)
dists (Sequence[SequenceEncodableProbabilityDistribution] | None)

compute_capabilities()[source]: Return engine support inherited from all child distributions.

compute_declaration()[source]: Return a child-role declaration for generated metadata consumers.

density(x)[source]

Return probability density/mass for one mapping record.

Parameters:: x (Mapping[Any, Any])
Return type:: float

log_density(x)[source]

Return summed child log densities for one mapping record.

Parameters:: x (Mapping[Any, Any])
Return type:: float

seq_log_density(x)[source]

Return per-row log densities for encoded record fields.

Parameters:: x (tuple[Any, ...])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Return per-row log densities using backend-aware child scorers.

Parameters:

x (tuple[Any, ...])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child parameters for homogeneous named-record mixtures.

Parameters:

dists (Sequence[RecordDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of record log densities.

Parameters:

x (tuple[Any, ...])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy named-record sufficient statistics.

Parameters:

x (tuple[Any, ...])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

seq_ld_lambda()[source]

Return legacy sequence log-density callables for this distribution.

Return type:: list[Any]

support_size()[source]

Product of field support sizes (None if any field is infinite).

Return type:: int | None

sampler(seed=None)[source]

Return a sampler that draws mapping records field-by-field.

Parameters:: seed (int | None)
Return type:: RecordSampler

estimator(pseudo_count=None)[source]

Return a record estimator with child estimators from each field.

Parameters:: pseudo_count (float | None)
Return type:: RecordEstimator

decomposition()[source]: Record fields are independent: split along the field (factor) axis, sufficient stats SUM-reduce.

dist_to_encoder()[source]

Return a data encoder for this record field/source layout.

Return type:: RecordDataEncoder

enumerator()[source]

Creates RecordEnumerator iterating mapping records in descending joint probability order.

Return type:: RecordEnumerator

conditional_enumerator(given)[source]

Enumerate complete records consistent with the fixed fields in given.

given is a mapping {source: value} pinning a subset of fields (the canonical most-probable-completion / imputation query: complete missing fields, best first). Because the fields are independent, P(record | given) is proportional to the joint P(record), so descending order over the free fields is also descending conditional order. Each yielded value is a complete record with the fixed fields merged back in, and its log_prob is the full joint log_density (the enumerator contract: lp == dist.log_density(value)) – the fixed fields enter as a constant offset, which only shifts every score by the same amount.

Raises ValueError if given names a field this record does not have.

Parameters:: given (Mapping[Any, Any])
Return type:: RecordConditionalEnumerator

structural_fine_bucket(value, quantizer)[source]

Sum of child structural buckets – mirrors the count index’s child convolution.

Like CompositeDistribution.structural_fine_bucket(), but fields are addressed by source name rather than tuple position.

Return type:: int

quantized_count_index(quantizer, max_fine_bucket)[source]

Structural count index: the additive law – the carrier’s n-ary product over fields.

Identical reduction to CompositeDistribution.quantized_count_index() (the joint histogram is the convolution of the per-field histograms in the witness-retaining count semiring); the only difference is that the unranked structural tuple is relabelled into a mapping record keyed by source, so witnesses match what the model actually scores.

Parameters:: max_fine_bucket (int)

class RecordEstimator(fields, estimators=None)[source]

Bases: ParameterEstimator

Estimator for independent named fields.

Parameters:

fields (Any)
estimators (Sequence[ParameterEstimator] | None)

accumulator_factory()[source]

Return a factory for record sufficient-statistic accumulators.

Return type:: RecordAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate each child field and return a fitted record distribution.

Parameters:

nobs (float | None)
suff_stat (tuple[Any, ...])

Return type:

RecordDistribution

DictRecordDistribution: alias of RecordDistribution

DictRecordEstimator: alias of RecordEstimator

field(name, source=None)[source]

Declare a named model field and the input key/column it reads.

field('x') reads input key 'x' and names the model field 'x'. A record is a normalized product law, so every modeled field and every source key must be unique; repeated views belong in an explicit factor model rather than this generative record wrapper.

Parameters:

name (Any)
source (Any)

Return type:

record(fields)[source]

Create a RecordDistribution from a field-to-distribution mapping.

Parameters:: fields (Mapping[Any, SequenceEncodableProbabilityDistribution])
Return type:: RecordDistribution

record_estimator(fields)[source]

Create a RecordEstimator from a field-to-estimator mapping.

Parameters:: fields (Mapping[Any, ParameterEstimator])
Return type:: RecordEstimator

exception EngineNotSupportedError[source]

Bases: ValueError

Raised when no kernel can safely evaluate a distribution on an engine.

class Kernel[source]

Bases: ABC

Evaluation kernel for a fitted distribution.

abstractmethod score(enc)[source]

Return per-row log densities for an encoded observation batch.

Parameters:: enc (Any)
Return type:: Any

component_scores(enc)[source]

Return per-row, per-component log densities where meaningful.

Parameters:: enc (Any)
Return type:: Any

abstractmethod accumulate(enc, weights)[source]

Return sufficient statistics in the legacy estimator format.

Parameters:

enc (Any)
weights (Any)

Return type:

abstractmethod refresh(dist)[source]

Refresh kernel parameters after an EM M-step without rebuilding structure.

Parameters:: dist (SequenceEncodableProbabilityDistribution)
Return type:: None

class KernelFactory[source]

Bases: ABC

Factory that builds a Kernel for a distribution and engine.

abstractmethod build(dist, engine, estimator=None)[source]

Return a kernel for dist on engine.

estimator is optional for pure scoring and required for kernels that need to emit sufficient statistics for an M-step.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

Return type:

Kernel

class GenericKernel(dist, engine=NUMPY_ENGINE, estimator=None)[source]

Bases: Kernel

Fallback kernel over distribution-owned backend hooks or existing seq_* methods.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

score(enc)[source]

Return per-row log densities using backend hooks when available.

Parameters:: enc (Any)
Return type:: Any

component_scores(enc)[source]

Return per-row component log densities for mixture-like models.

Parameters:: enc (Any)
Return type:: Any

accumulate(enc, weights)[source]

Accumulate weighted sufficient statistics in estimator-owned format.

Parameters:

enc (Any)
weights (Any)

Return type:

refresh(dist)[source]

Replace the fitted distribution while preserving kernel structure.

Parameters:: dist (SequenceEncodableProbabilityDistribution)
Return type:: None

class GenericKernelFactory[source]

Bases: KernelFactory

Guaranteed fallback factory for distributions that support the engine.

build(dist, engine, estimator=None)[source]

Build a generic kernel or fail fast when the engine is unsupported.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

Return type:

GenericKernel

class NumbaKernel(dist, engine=NUMPY_ENGINE, estimator=None)[source]

Bases: Kernel

Kernel adapter over the existing fused-numba CompiledMixture path.

This kernel intentionally uses the columnar encoding returned by encode(data) rather than the legacy dist_to_encoder().seq_encode payload. That keeps the high-performance path explicit while giving it the same score/accumulate/refresh surface as other engines.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

encode(data)[source]

Encode raw observations into the fused columnar kernel format.

Parameters:: data (Any)
Return type:: Any

score(enc)[source]

Return per-row log densities from the fused numba mixture kernel.

Parameters:: enc (Any)
Return type:: ndarray

component_scores(enc)[source]

Return per-row, per-component log densities from the fused kernel.

Parameters:: enc (Any)
Return type:: ndarray

accumulate(enc, weights)[source]

Use fused posteriors plus row weights to produce legacy statistics.

Parameters:

enc (Any)
weights (Any)

Return type:

refresh(dist)[source]

Refresh parameters after an M-step without rebuilding the compiled object.

Parameters:: dist (SequenceEncodableProbabilityDistribution)
Return type:: None

class GeneratedNumbaKernel(dist, engine=NUMPY_ENGINE, estimator=None)[source]

Bases: Kernel

Generated numba kernel from declaration exponential-family metadata.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

encode(data)[source]

Encode raw observations with the distribution’s ordinary encoder.

Parameters:: data (Any)
Return type:: Any

score(enc)[source]

Return per-row log densities from declaration-generated numba code.

Parameters:: enc (Any)
Return type:: ndarray

component_scores(enc)[source]

Return generated component scores for homogeneous generated mixtures.

Parameters:: enc (Any)
Return type:: ndarray

accumulate(enc, weights)[source]

Accumulate generated sufficient statistics for leaves or mixtures.

Parameters:

enc (Any)
weights (Any)

Return type:

posteriors(enc)[source]

Return normalized mixture posterior weights for generated mixtures.

Parameters:: enc (Any)
Return type:: ndarray

refresh(dist)[source]

Refresh the distribution and regenerated component metadata.

Parameters:: dist (SequenceEncodableProbabilityDistribution)
Return type:: None

class NumbaKernelFactory[source]

Bases: KernelFactory

Factory for generated declaration numba kernels with legacy fused fallback.

build(dist, engine, estimator=None)[source]

Prefer generated numba kernels, then fused kernels, then stacked fallback.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

Return type:

Kernel

class GeneratedNumbaKernelFactory(fallback=None)[source]

Bases: KernelFactory

Default-safe factory that prefers declaration-generated numba kernels.

Unlike NumbaKernelFactory, this never selects the fused CompiledMixture adapter (whose columnar encoding is incompatible with the legacy seq_encode payloads that the engine estimation path feeds kernels) and never raises: when a generated numba scorer is unavailable, or the engine is not numpy, it defers to a guaranteed fallback (the generic kernel). That makes it safe to register as a default on the kernel dispatch path while still accelerating mixtures of declared exponential-family leaves on the numpy engine.

Parameters:: fallback (KernelFactory | None)

build(dist, engine, estimator=None)[source]

Build a generated numba kernel on numpy when available, else fall back.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

Return type:

Kernel

class ComponentShardLayout(indices)[source]

Bases: object

Explicit global component indices represented by one local payload.

Parameters:: indices (tuple[int, ...])

property contiguous: bool: Return whether the indices form one ascending contiguous interval.

property ranges: tuple[tuple[int, int], ...]: Return minimal half-open ranges preserving local component order.

legacy_selection()[source]

Return the old start integer when contiguous, explicit indices otherwise.

Return type:: int | tuple[int, …]

class StackedComponentParams(component_type, strategy, params)[source]

Bases: object

A generic route for homogeneous component scoring.

Parameters:

component_type (type[Any])
strategy (str)
params (Any)

class StackedMixtureResidentStats(component_counts, component_stats, engine, component_type)[source]

Bases: object

Engine-resident sufficient statistics for a homogeneous mixture.

Parameters:

component_counts (Any)
component_stats (Any)
engine (ComputeEngine)
component_type (type[Any])

value()[source]

Return sufficient statistics in the legacy MixtureEstimator format.

Return type:: Any

local_value()[source]

Return this rank’s explicitly indexed component-stat payload.

DTensor-backed model-parallel runs should run component M-steps on the local component shard and all-reduce only scalar mixture-weight totals. This method therefore prefers DTensor to_local() chunks over full_tensor(). A contiguous shard retains the legacy integer start; a non-contiguous shard returns its global-index tuple. Every resident statistic tensor must expose the same component layout as the counts.

Return type:: tuple[int | tuple[int, …], Any]

estimate(estimator)[source]

Estimate a distribution after converting to the legacy estimator protocol.

Parameters:: estimator (ParameterEstimator)
Return type:: Any

estimate_component_shard(estimator, total_count=None)[source]

Run the component-local part of a mixture M-step for this shard.

Component distributions are independent given posterior sufficient statistics. Mixture weights only need the scalar global total count (or fixed weights), so a model-parallel orchestrator can call this on each shard after an all-reduce of that scalar instead of gathering all component statistics to the driver.

Parameters:

estimator (ParameterEstimator)
total_count (float | None)

Return type:

StackedMixtureShardEstimate

class StackedMixtureShardEstimate(component_indices, components, weights, total_count)[source]

Bases: object

Component-local M-step result for a homogeneous mixture shard.

Parameters:

component_indices (tuple[int, ...])
components (tuple[Any, ...])
weights (ndarray)
total_count (float)

property component_start: int: Lowest selected index (legacy contiguous-shard compatibility).

property component_stop: int: Exclusive upper bound (legacy contiguous-shard compatibility).

property component_ranges: tuple[tuple[int, int], ...]: Minimal half-open global ranges owned by this result.

class StackedMixtureKernel(dist, engine, estimator=None)[source]

Bases: Kernel

Homogeneous mixture kernel with stacked component parameters.

The mixture mechanics live here: component matrix scoring, row-wise logsumexp, posterior weights, and legacy sufficient-stat dispatch. The leaf family still owns the actual component log-density math through backend_stacked_params and backend_stacked_log_density.

Parameters:

dist (Any)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

encode(data)[source]

Encode raw observations with the mixture’s ordinary encoder.

Parameters:: data (Any)
Return type:: Any

component_scores(enc)[source]

Return unweighted component log densities with shape (n, k).

Parameters:: enc (Any)
Return type:: Any

score(enc)[source]

Return row log densities after adding mixture log weights.

Parameters:: enc (Any)
Return type:: Any

posteriors(enc)[source]

Return posterior component weights for each encoded row.

Parameters:: enc (Any)
Return type:: Any

property has_resident_accumulate: bool: Return true when the leaf family can accumulate sufficient stats on the engine.

resident_accumulate(enc, weights)[source]

Return engine-resident mixture sufficient statistics.

The mixture owns only the posterior mechanics. Leaf families own the sufficient-statistic algebra through backend_stacked_sufficient_statistics.

Parameters:

enc (Any)
weights (Any)

Return type:

StackedMixtureResidentStats

accumulate(enc, weights)[source]

Return mixture sufficient statistics in the legacy estimator format.

Parameters:

enc (Any)
weights (Any)

Return type:

refresh(dist)[source]

Refresh stacked parameters after an M-step without changing structure.

Parameters:: dist (SequenceEncodableProbabilityDistribution)
Return type:: None

class StackedMixtureKernelFactory(fallback=None)[source]

Bases: KernelFactory

Factory for homogeneous mixtures with distribution-owned stacked math.

Parameters:: fallback (KernelFactory | None)

build(dist, engine, estimator=None)[source]

Build a stacked mixture kernel when safe, otherwise use fallback.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine)
estimator (ParameterEstimator | None)

Return type:

Kernel

stacked_component_log_density(enc, route, engine)[source]

Evaluate a route returned by stacked_component_params.

Parameters:

enc (Any)
route (StackedComponentParams)
engine (ComputeEngine)

Return type:

stacked_component_params(dists, engine)[source]

Return a generic stacked-scoring route for homogeneous components.

Generated declaration-backed routes are attempted first. Families with object lookups, table layouts, derived parameters, or wrapper structure can keep explicit backend_stacked_* hooks and still compose through this single dispatcher.

Parameters:

dists (Sequence[Any])
engine (ComputeEngine)

Return type:

StackedComponentParams

stacked_component_strategy(dist_type)[source]

Describe how homogeneous mixture component scoring will be dispatched.

Parameters:: dist_type (type[Any])
Return type:: str

estimate_component_shard_value(estimator, component_selection, value, total_count=None)[source]

Estimate the component-local part of a mixture M-step from an explicit shard value.

Parameters:

estimator (ParameterEstimator)
component_selection (int | Sequence[int] | ComponentShardLayout)
value (tuple[Any, tuple[Any, ...]])
total_count (float | None)

Return type:

StackedMixtureShardEstimate

tie_component_shard_values(estimator, shard_values)[source]

Apply mixle key tying to component-sharded mixture statistics.

MixtureAccumulator.key_merge / key_replace assume a full component vector is materialized on one worker. Component-sharded model-parallel runs instead hold ranges [component_start, component_stop). This helper applies the same key protocol to those local ranges by materializing only the component accumulators owned by each shard.

Parameters:

estimator (ParameterEstimator)
shard_values (Sequence[tuple[int | Sequence[int] | ComponentShardLayout, tuple[Any, tuple[Any, ...]]]])

Return type:

tuple[tuple[int | tuple[int, …], tuple[ndarray, tuple[Any, …]]], …]

register_kernel_factory(dist_type, factory)[source]

Parameters:

dist_type (type[Any])
factory (KernelFactory)

Return type:

None

kernel_for(dist, engine=None, estimator=None)[source]

Build the best registered kernel for dist and engine.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
engine (ComputeEngine | None)
estimator (ParameterEstimator | None)

Return type:

Kernel

class BernoulliDistribution(p, name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Bernoulli distribution over {False, True} with success probability p.

Parameters:

p (float)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Bernoulli kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Bernoulli distributions.

static exp_family_sufficient_statistics(x, engine)[source]

Return Bernoulli sufficient statistics for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Bernoulli sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Bernoulli natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Bernoulli log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

set_prior(prior)[source]

Attach a Beta parameter prior and precompute conjugate-prior expectations.

With a Beta(a, b) prior on the success probability p this caches the digamma terms so that expected_log_density evaluates the variational Bayes expectation E_q[log p(x | p)] via E[log p] = digamma(a) - digamma(a+b) and E[log(1-p)] = digamma(b) - digamma(a+b). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | p)] under the Beta prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (bool | int)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (bool | int)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (bool | int)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

static backend_log_density_from_params(x, p, engine)[source]

Engine-neutral Bernoulli log-mass from explicit parameters.

Parameters:

x (Any)
p (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Bernoulli parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[BernoulliDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Bernoulli log masses.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Bernoulli sufficient statistics using engine-resident arrays.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

support_size()[source]

The two outcomes {0, 1}.

Return type:: int

to_fisher(**kwargs)[source]: Return the Bernoulli’s count-family Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x) over {0, 1}.

Parameters:: x (float)
Return type:: float

skewness()[source]

Skewness (1-2p)/sqrt(p(1-p)).

Return type:: float

kurtosis()[source]

Excess kurtosis (1-6p(1-p))/(p(1-p)).

Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) over {0, 1}.

Parameters:: q (float)
Return type:: float

entropy()[source]

Shannon entropy -p log p - (1-p) log(1-p) (nats).

Return type:: float

mode()[source]

Mode (0 if p<1/2 else 1).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: BernoulliSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: BernoulliEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: BernoulliDataEncoder

enumerator()[source]

Return an enumerator over the distribution support when available.

Return type:: BernoulliEnumerator

class BernoulliEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate a Bernoulli distribution from weighted success counts.

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Return an accumulator factory for Bernoulli sufficient statistics.

Return type:: BernoulliAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s success probability under the Beta prior (ELBO global term).

Parameters:: model (BernoulliDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate the Bernoulli success probability from weighted counts.

The distribution is defined on the open interval (0, 1), so a sample that is all successes or all failures – whose maximum-likelihood p is exactly 1 or 0 – is clamped _P_BOUNDARY (1e-12) away from the endpoint. When that clamp binds it is reported on the returned model through numerical_repairs() as bernoulli-p-clamped(...), and so through fit_provenance().repairs; an ordinary fit whose p is already interior records nothing.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

BernoulliDistribution

class BernoulliEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate False/True in descending probability order.

Parameters:: dist (BernoulliDistribution)

class BetaDistribution(a, b, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Beta distribution with positive shape parameters a and b.

Parameters:

a (float)
b (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Beta kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Beta distributions.

static exp_family_sufficient_statistics(x, engine)[source]

Return Beta sufficient statistics for generated scoring.

Scoring needs only log_x and log1m_x (the two natural-parameter partners). The encoder emits the full (log_x, log1m_x, x, x**2) tuple for the M-step, while the symbolic generator supplies just the two scoring symbols from backend_log_density_from_params; indexing the leading two works for both arities.

Parameters:

x (tuple[Any, Any, Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Beta sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any, Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Beta natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Beta log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

get_parameters()[source]

Return the (a, b) shape pair.

Lets a BetaDistribution serve as a conjugate prior (on a Bernoulli/Geometric/Binomial success probability) under the unified Bayesian estimation protocol.

Return type:: tuple[float, float]

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray, ndarray, ndarray])
Return type:: ndarray

static backend_log_density_from_params(log_x, log1m_x, a, b, engine)[source]

Engine-neutral Beta log-density from encoded logs and parameters.

Parameters:

log_x (Any)
log1m_x (Any)
a (Any)
b (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any, Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Beta parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[BetaDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Beta log densities.

Parameters:

x (tuple[Any, Any, Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

to_fisher(**kwargs)[source]: Return this distribution’s own Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy ln B(a,b) - (a-1)psi(a) - (b-1)psi(b) + (a+b-2)psi(a+b).

Return type:: float

mode()[source]

Mode (a-1)/(a+b-2) for a,b>1; boundary otherwise.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: BetaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: BetaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: BetaDataEncoder

class BetaEstimator(pseudo_count=None, suff_stat=None, delta=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate beta shape parameters from weighted log-moment statistics.

Parameters:

pseudo_count (float | None)
suff_stat (Sequence[float] | None)
delta (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Beta sufficient statistics.

Return type:: BetaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Beta shape parameters from weighted sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float, float, float])

Return type:

BetaDistribution

class LaplaceDistribution(mu, b, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Laplace distribution with location mu and scale b > 0.

Parameters:

mu (float)
b (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Laplace kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Laplace distributions.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

static backend_log_density_from_params(x, mu, b, engine)[source]

Engine-neutral Laplace log-density from explicit parameters.

Parameters:

x (Any)
mu (Any)
b (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Laplace parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[LaplaceDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Laplace log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return per-component raw weighted observations using engine-resident arrays.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[tuple[Any, Any], …]

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy 1 + log(2b).

Return type:: float

skewness()[source]

Skewness (0).

Return type:: float

kurtosis()[source]

Excess kurtosis (3).

Return type:: float

mode()[source]

Mode (= the location mu).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: LaplaceSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: LaplaceEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: LaplaceDataEncoder

class LaplaceEstimator(pseudo_count=None, suff_stat=None, min_scale=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Exact weighted-MLE estimator for Laplace location and scale.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_scale (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Laplace raw-observation statistics.

Return type:: LaplaceAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location and scale by the exact weighted MLE.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

LaplaceDistribution

class LogisticDistribution(loc=0.0, scale=1.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Logistic distribution with location loc and scale > 0.

Parameters:

loc (float)
scale (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated logistic kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for logistic distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Logistic sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

static backend_log_density_from_params(x, loc, scale, engine)[source]

Engine-neutral logistic log-density from explicit parameters.

Parameters:

x (Any)
loc (Any)
scale (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked logistic parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[LogisticDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of logistic log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy log(scale) + 2.

Return type:: float

skewness()[source]

Skewness (0).

Return type:: float

kurtosis()[source]

Excess kurtosis (6/5).

Return type:: float

mode()[source]

Mode (= the location loc).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: LogisticSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: LogisticEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: LogisticDataEncoder

class LogisticEstimator(pseudo_count=None, suff_stat=None, min_scale=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Moment estimator for logistic location and scale.

The likelihood MLE has no closed-form M-step. The EM estimator uses the identities mean=loc and var=pi^2 scale^2 / 3; torch gradient MLE can refine both parameters when exact likelihood optimization is desired.

The variance moment is formed from shift-anchored statistics whenever the accumulated sufficient statistics carry that payload (see LogisticAccumulator), which makes the fit shift-equivariant: estimating on x + c returns loc + c with scale unchanged. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones restored from an older serialization – the historical raw path is used, bit-identically.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_scale (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for logistic moment statistics.

Return type:: LogisticAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location and scale from weighted moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

LogisticDistribution

class LogSeriesDistribution(p, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Logarithmic (log-series) distribution on k = 1, 2, … with shape parameter p in (0, 1).

Parameters:

p (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated log-series kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for log-series distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row (count, k) sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)[source]

Return the log-series sufficient statistic T(k) = (k,).

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the log-series natural parameter eta = log(p).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the log-series log partition A = log(-log(1 - p)).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return the log-series base measure log h(k) = -log(k) (independent of p, fixed base).

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

static exp_family_from_natural(eta)[source]

Return the log-series with natural parameter eta = log(p) (so p = exp(eta)).

Parameters:: eta (Any)
Return type:: LogSeriesDistribution

static backend_log_density_from_params(k, log_k, log_p, log_norm, engine)[source]

Engine-neutral log-series log-mass from explicit parameters (linear in k and log k).

Parameters:

k (Any)
log_k (Any)
log_p (Any)
log_norm (Any)
engine (Any)

Return type:

density(x)[source]

Return the probability mass at a single observation.

Parameters:: x (int)
Return type:: float

log_density(x)[source]

Return the log-mass at a single positive integer (or -inf off support).

Parameters:: x (int)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-mass values for sequence-encoded (k, log k) observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-mass for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[LogSeriesDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of log-series log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

mean()[source]

Mean E[X] = -p / ((1-p) log(1-p)).

Return type:: float

variance()[source]

Variance Var[X] = -p (p + log(1-p)) / ((1-p)^2 log(1-p)^2).

Return type:: float

entropy()[source]

Shannon entropy in nats, by exact summation of the standard series.

The log-series entropy -sum_k p_k log p_k has no closed form (Fisher, Corbet & Williams, 1943). The series is summed from k = 1 up to this distribution’s own quantile at 1 - 1e-16 (plus a safety margin), beyond which the remaining tail mass is far below double rounding.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x), support x >= 1.

Summed directly in bounded blocks (the series has no closed form); past _SERIES_CAP terms one minus the Euler-Maclaurin tail mass stands in, exact to double rounding by then and never below the partial sum at the cap, so the result is monotone in x and within [0, 1].

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the smallest k with P(X <= k) >= q.

Summed directly in bounded blocks, never through scipy’s generic discrete ppf. That search brackets the answer by doubling an upper bound until cdf(bound) >= q, and the summed CDF can saturate one ULP short of a q this close to one (numpy’s SIMD exp and log round the last bit differently per CPU: the sum reached q = 1 - 1e-16 at k = 5210 on arm64 and emulated x86-64 and never did on AVX-512 hosted CI runners), so the bound doubled without limit and the vectorized CDF sums grew until the 16 GB runner was OOM-killed – through entropy(), which calls this at exactly that q. Here a block whose terms no longer move the running sum, or the term cap, ends the scan, and the Euler-Maclaurin tail mass answers for whatever lies beyond: the smallest k past the scan whose tail mass is at most 1 - q.

Parameters:: q (float)
Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: LogSeriesSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: LogSeriesEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: LogSeriesDataEncoder

enumerator()[source]

Return an enumerator over k = 1, 2, … in descending probability order.

Return type:: LogSeriesEnumerator

class LogSeriesEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the log-series shape p (inverts the mean -> p relation).

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for log-series count statistics.

Return type:: LogSeriesAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the shape parameter by inverting the weighted mean.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

LogSeriesDistribution

class BinomialDistribution(p, n, min_val=None, name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Binomial distribution over min_val + {0, ..., n} with success probability p.

Parameters:

p (float)
n (int)
min_val (int | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for generated Binomial density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Binomial distribution.

static exp_family_sufficient_statistics(x, engine)[source]

Return Binomial sufficient statistics from encoded observations.

The parameter-dependent support shift is handled by exp_family_sufficient_statistics_from_params when generated scoring supplies the declaration-stacked parameter bundle.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics_from_params(x, params, engine)[source]

Return Binomial sufficient statistics for generated scoring.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Binomial natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Binomial log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return the observation-only Binomial base measure.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
engine (Any)

Return type:

static exp_family_base_measure_from_params(x, params, engine)[source]

Return Binomial support/base measure for generated scoring.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
params (dict[str, Any])
engine (Any)

Return type:

set_prior(prior)[source]

Attach a Beta parameter prior and precompute conjugate-prior expectations.

With a Beta(a, b) prior on the success probability p this caches (E[log p], E[log(1-p)]) = (digamma(a) - digamma(a+b), digamma(b) - digamma(a+b)) so that expected_log_density evaluates the variational Bayes expectation E_q[log p(x | p)]. Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | p)] under the Beta prior.

Uses the cached digamma expectations of log p and log(1-p); falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (int)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray, ndarray, int, int])
Return type:: ndarray

density(x)[source]

Returns the probability mass of integer value x.

If x is not an integer between [0,n) or [min_val, n-1-min_val), density is 0.0.

Parameters:: x (int) – Integer value for density evaluation.
Returns:: Probability mass of x for binomial(n,p) with min_val=min_val. 0.0 if x is not in support.
Return type:: float

log_density(x)[source]

Returns the log-probability mass of integer value x.

If x is not an integer between [0,n) or [min_val, n-1-min_val), log-density is -inf.

Parameters:: x (int) – Integer value for density evaluation.
Returns:: Log-probability mass of x for binomial(n,p) with min_val=min_val. -inf if x is not in support.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density for sequence encoded data.

Input value x must be obtained from a call to BinomialDataEncoder.seq_encode(data). Returns numpy array of log-density evaluated at all observations contained in encoded data x.

Parameters:: x (Tuple[np.ndarray, np.ndarray, np.ndarray, int, int]) – containing unique values in x, indices of ux to reconstruct x, numpy array of x, min value of x, and max value of x.
Returns:: Numpy array of log-density evaluated at all observations contained in encoded data x.
Return type:: ndarray

static backend_log_density_from_params(vals, n, p, min_val, engine)[source]

Engine-neutral binomial log-density from explicit parameters.

Parameters:

vals (Any)
n (Any)
p (Any)
min_val (int | None)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked binomial parameters for a homogeneous mixture kernel.

A stacked binomial mixture requires components to share the same trial count and shifted support. Mixtures with heterogeneous supports fall back to the generic kernel.

Parameters:

dists (Sequence[BinomialDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of binomial log densities.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return stacked Binomial sufficient statistics using estimator-owned support bounds.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

support_size()[source]

n + 1 outcomes min_val + {0, ..., n}.

Return type:: int

to_fisher(**kwargs)[source]: Return the Binomial’s count-family Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x) over min_val + {0..n}.

Parameters:: x (float)
Return type:: float

skewness()[source]

Skewness (1-2p)/sqrt(npq).

Return type:: float

kurtosis()[source]

Excess kurtosis (1-6pq)/(npq).

Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) over min_val + {0..n} (via scipy binom).

Parameters:: q (float)
Return type:: float

mode()[source]

Mode min_val + floor((n+1)p).

Return type:: float

sampler(seed=None)[source]

Returns BinomialSampler for generating samples from BinomialDistribution(n,p,min_val).

Parameters:

Optional[int] (seed) – Used to set seed on random number generator for sampling.
seed (int | None)

Returns:

BinomialSampler for BinomialDistribution with seed.

Return type:

BinomialSampler

estimator(pseudo_count=None)[source]

Creates a BinomialEstimator for estimating parameters of BinomialDistribution.

Parameters:: pseudo_count (Optional[float]) – If set, inflates counts for currently set sufficient statistic (p).
Returns:: BinomialEstimator object.
Return type:: BinomialEstimator

dist_to_encoder()[source]

Create the encoder for sequence-encoded binomial observations.

Returns:: BinomialDataEncoder object.
Return type:: BinomialDataEncoder

enumerator()[source]

Returns BinomialEnumerator iterating the support in descending probability order.

Return type:: BinomialEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index by walking the binomial mode outward.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over finite binomial supports.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over two binomial supports.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class BetaBinomialDistribution(n, a, b, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Beta-binomial distribution over {0, ..., n} with shape parameters a, b > 0.

Parameters:

n (int)
a (float)
b (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability mass at a single count x.

Parameters:: x (int)
Return type:: float

log_density(x)[source]

Return the log probability mass at x (-inf outside {0, ..., n} or non-integer – a fractional count is not a valid beta-binomial outcome).

Parameters:: x (int)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-mass for an array of counts (-inf outside {0, ..., n} or non-integer – a fractional count is not a valid beta-binomial outcome).

Parameters:: x (ndarray)
Return type:: ndarray

support_size()[source]

n + 1 outcomes {0, ..., n}.

Return type:: int

cdf(x)[source]

Cumulative distribution function P(X <= x): a log-space partial sum of the pmf over {0..n}.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) over {0..n}: the smallest count whose cdf reaches q (search on the cdf).

Parameters:: q (float)
Return type:: float

enumerator()[source]

Returns BetaBinomialEnumerator iterating the support in descending probability order.

Return type:: BetaBinomialEnumerator

sampler(seed=None)[source]

Return a sampler for drawing counts from this distribution.

Parameters:: seed (int | None)
Return type:: BetaBinomialSampler

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for a, b at the fixed number of trials n.

Parameters:: pseudo_count (float | None)
Return type:: BetaBinomialEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: BetaBinomialDataEncoder

class BetaBinomialEstimator(n, pseudo_count=None, suff_stat=None, min_conc=1.0e-6, max_conc=1.0e8, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for the beta-binomial shape parameters.

Parameters:

n (int)
pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_conc (float)
max_conc (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for beta-binomial moments.

Return type:: BetaBinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate beta-binomial shape parameters from weighted moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

BetaBinomialDistribution

class BinomialEstimator(max_val=None, min_val=0, pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate Binomial probability and support parameters from sufficient statistics.

Parameters:

max_val (int | None)
min_val (int | None)
pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Create a BinomialAccumulatorFactory from estimator member variables.

Returns:: BinomialAccumulatorFactory
Return type:: BinomialAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s success probability under the Beta prior (ELBO global term).

Parameters:: model (BinomialDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a binomial distribution from accumulated sufficient statistics.

nobs is accepted for estimator API consistency but is not used. The sufficient statistic is (count, sum, min_val, max_val). When a prior statistic and pseudo_count are present, they shrink the empirical success probability toward the estimator’s prior probability.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, int | None, int | None])

class BinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate bounded Binomial support values in descending probability order.

Parameters:: dist (BinomialDistribution)

class CategoricalDistribution(pmap=MISSING, default_value=0.0, name=None, keys=None, prob_map=MISSING, prior=None, scoring_only=False)[source]

Bases: SequenceEncodableProbabilityDistribution

Categorical distribution over hashable labels.

Parameters:

pmap (dict[Any, float])
default_value (float)
name (str | None)
keys (str | None)
prob_map (dict[Any, float])
prior (SequenceEncodableProbabilityDistribution | None)
scoring_only (bool)

classmethod compute_capabilities()[source]: Return compute-backend metadata for categorical scoring.

classmethod compute_declaration()[source]: Return the symbolic declaration for categorical probability maps.

static exp_family_sufficient_statistics(x, engine)[source]

Return a shape-only fallback; category-aware statistics come from ..._from_params.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics_from_params(x, params, engine)[source]

Return the one-hot label indicator T(x) of shape (n, K) (zeros for off-support labels).

Categories are ordered canonically by sorted(pmap, key=repr) so the columns line up with exp_family_natural_parameters().

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the natural parameter eta = log(pmap) over categories in canonical key order.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the log partition A = 0 (normalization is carried by eta = log p).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure_from_params(x, params, engine)[source]

Return log h(x) = 0 on the support (a key of pmap) and -inf for off-support labels.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

get_prior()[source]

Return the conjugate parameter prior over the category-probability simplex (or None).

Return type:: SequenceEncodableProbabilityDistribution | None

set_prior(prior)[source]

Attach a parameter prior and precompute conjugate-prior expectations.

With a DictDirichlet(alpha) prior over the category probabilities this caches the variational expected log-probabilities E[log p_k] = digamma(alpha_k) - digamma(sum_k alpha_k) for each key of pmap so that expected_log_density(x) = E[log p_x] - log(1 + default_value). A scalar alpha is treated as a symmetric Dirichlet of dimension len(pmap). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x)] under the DictDirichlet prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (Any)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

density(x)[source]

Density evaluation of CategoricalDistribution.

p_mat(x) = p_i, if x in pmap.keys(), else p_mat(x) = default_value.

With default_value > 0 and a pmap that does not cover the full label space, this is a smoothed scoring function, not a normalized probability measure – see the default_value note on __init__().

Parameters:: x (Any) – Evaluate CategoricalDistribution density value at x.
Returns:: float density value at x
Return type:: float

density_semantics()[source]

Report what log_density actually returns, derived from the parameters.

This keys off is_normalized_probability, so an object whose numbers do not describe a law does not claim to be one (MXR-080-1841). Three shapes report LIKELIHOOD_FACTOR:

scoring_only, the author’s declaration that this is an evaluation-only factor,
default_value != 0 open-world smoothing, which spreads mass over every unseen label and so has no finite total,
a pmap that does not sum to one – including the empty pmap, whose total is zero.

An earlier revision returned EXACT for the last two, because _owned_generative_components refuses LIKELIHOOD_FACTOR and mixtures, HMMs and segment models in this repository are all built from categoricals of exactly those shapes: a component that won zero responsibility this iteration, the explicit no-evidence state fitted on all-empty sequences, and deliberately unnormalized components. Labelling them honestly made them non-composable, so the label was bent instead. That was the wrong half to bend: composition inconvenience cannot turn a non-law into an exact law.

The composition layer now decides admissibility for itself, by asking a factor whether it differs from a law only by scale (see composable_as_component and _owned_generative_components), so both questions get a truthful answer.

composable_as_component()[source]

Whether a latent model may use this factor as a component (MXR-080-1841).

A mixture, HMM or segment model normalizes responsibilities across components, so a component that differs from a law by a positive constant scale is absorbed into its own mixing weight and leaves the E-step unchanged; a zero-mass component simply wins no responsibility. A categorical is a lookup over a discrete support, so an unnormalized or empty pmap is exactly such a scaled law and stays admissible.

scoring_only is not: it is an author’s declaration that the object is not generative at all, and a declaration is not something the composition layer may reason its way around.

Return type:: bool

log_density(x)[source]

Log-Density evaluation of CategoricalDistribution.

log(p_mat(x)) = log(p_i), if x in pmap.keys(), else log(p_mat(x)) = log(default_value).

Parameters:: x (Any) – Evaluate CategoricalDistribution density value at x.
Returns:: Log-density of Categorical distribution evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density for sequence encoded data.

Input value x must be obtained from a call to CategoricalDataEncoder.seq_encode(data). Returns numpy array of log-density evaluated at all observations contained in encoded data x.

Parameters:: x (tuple[ndarray, ndarray]) – (Tuple[np.ndarray,np.ndarray]): Tuple of numpy indices for unique categories, and numpy array unique objects that index xs maps to.
Returns:: Numpy array of log-density evaluated at all observations contained in encoded data x.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral log-density for encoded object categories.

The object-to-index lookup remains Python-side at the encoding boundary; the selected log-probability vector is an engine tensor, so simplex-map parameters can still participate in autograd.

Parameters:

x (tuple[ndarray, ndarray])
engine (Any)

Return type:

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked categorical probabilities for shared finite supports.

Parameters:

dists (Sequence[CategoricalDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of categorical log densities.

Parameters:

x (tuple[ndarray, ndarray])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return per-component legacy count maps from engine-resident posterior weights.

Parameters:

x (tuple[ndarray, ndarray])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[dict[Any, float], …]

support_size()[source]

Number of categories in the support.

Return type:: int

to_fisher(**kwargs)[source]: Return the categorical’s one-hot Fisher view (generic fallback for default-augmented maps).

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional random seed.
Returns:: A configured CategoricalSampler.
Return type:: CategoricalSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s support.

Parameters:: pseudo_count (float | None) – Optional smoothing count applied to current probabilities.
Returns:: A CategoricalEstimator.
Return type:: CategoricalEstimator

dist_to_encoder()[source]

Return an encoder for categorical observations.

Return type:: CategoricalDataEncoder

enumerator()[source]

Return an enumerator over support labels in descending probability order.

Return type:: CategoricalEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index directly from the finite support map.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view for finite categorical maps.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view for two finite categorical maps.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class ChineseRestaurantProcessDistribution(alpha, n, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

CRP distribution over partitions of n items with concentration alpha > 0.

Parameters:

alpha (float)
n (int)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability of the partition encoded by label vector x.

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

Return the Ewens log-probability of the partition that label vector x induces.

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Return the Ewens log-probability for a list of partition label vectors.

Parameters:: x (list[ndarray])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler that draws partitions by the sequential CRP rule.

Parameters:: seed (int | None)
Return type:: ChineseRestaurantProcessSampler

estimator(pseudo_count=None)[source]

Return a maximum-likelihood estimator for the concentration alpha at fixed n.

Parameters:: pseudo_count (float | None)
Return type:: ChineseRestaurantProcessEstimator

dist_to_encoder()[source]

Return the data encoder (passes label vectors through).

Return type:: ChineseRestaurantProcessDataEncoder

class ChineseRestaurantProcessEstimator(n, alpha_min=1.0e-6, alpha_max=1.0e6, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the CRP concentration via the monotone expected-blocks equation.

Parameters:

n (int)
alpha_min (float)
alpha_max (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for CRP sufficient-statistic accumulators.

Return type:: ChineseRestaurantProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the CRP concentration from the observed mean block count.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

ChineseRestaurantProcessDistribution

class CategoricalEstimator(pseudo_count=None, suff_stat=None, default_value=False, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimator for categorical probability maps from weighted label counts.

Parameters:

pseudo_count (float | None)
suff_stat (dict[Any, float] | None)
default_value (bool)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

get_prior()[source]

Return the conjugate parameter prior over the category-probability simplex (or None).

Return type:: SequenceEncodableProbabilityDistribution | None

set_prior(prior)[source]

Set the conjugate parameter prior over the category-probability simplex.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

model_log_density(model)[source]

Log-density of the model probability map under the DictDirichlet prior (ELBO global term).

Parameters:: model (CategoricalDistribution)
Return type:: float

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: CategoricalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a CategoricalDistribution from suff_stat value.

If default_value is True, we estimate a default value from the suff_stat counts. Else, it is set to 0.0.

pseudo_count is used to averaged over the number of levels and added to the corresponding counts.

If suff_stat member value is None, estimate for CategoricalDistribution is formed from the suff_stat passed. Otherwise, the suff_stat member value is combined with the suff_stat values passed to estimate.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.estimate.
suff_stat (Dict[Any, float]) – Dict with categories as keys and counts as values from accumulated data.

Returns:

CategoricalDistribution estimated from passed in suff_stat value and sufficient statistic member variable: (if it is not None).

Return type:

CategoricalDistribution

class CategoricalEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerator over finite categorical support in descending probability order.

Parameters:: dist (CategoricalDistribution)

class MultinomialDistribution(dist, len_dist=NullDistribution(), len_normalized=False, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Multinomial distribution over count vectors.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
len_dist (SequenceEncodableProbabilityDistribution | None)
len_normalized (bool)
name (str | None)

compute_capabilities()[source]: Declare generated-compute support inherited from value and length children.

compute_declaration()[source]: Return the generated-compute declaration for the categorical multinomial.

to_exponential_family(engine=None)[source]

Return the multinomial exponential-family view, or None.

A multinomial over an exponential-family element is itself an exponential family with the shared element eta and the count-weighted sufficient statistic T(x) = sum_j c_j T_0(v_j). This holds only when the trial count is not separately modeled (len_dist is Null) and the density is not length-normalized (those break the single-exp-family form); it also requires the value element to be an exponential family. Otherwise returns None.

Parameters:: engine (Any)

density(x)[source]

Returns the density of multinomial evaluated at observation x.

See log_density() for details.

Parameters:: x (Sequence[Tuple[T, float]]) – Tuples of observed multinomial values and success s.t. success sum to number of trials.
Returns:: Density evaluated at x.
Return type:: float

log_density(x)[source]

Returns the log-density of multinomial evaluated at observation x.

Let P_dist(V_k) be a distribution for a countable set of discrete observations of values V_k of type T. Denote

p_k = P_dist(V_k),

as the probability of success for value V_k. Then sum_{k=0}^{inf} p_k = 1. Let x = (x_0, x_1,….,x_{n-1}) be a multinomial observation for ‘n’ trials, where each x_i = (V_j, n_j) for some value V_j in the observation space and n_j is the associated number of success for the value. (note: sum n_j = n). Then, denoting p_j = p_mat(V_j), the normalized count-vector log mass is:

log(p_mat(x)) = log(n!) - sum_j log(n_j!) + sum_j n_j * log(p_j) + log(P_len(n)),

where P_len(n) is a distribution for the number of trials in the multinomial having support on the non-negative integers.

Parameters:: x (Sequence[Tuple[T, float]]) – Tuples of observed multinomial values and success s.t. success sum to number of trials.
Returns:: Log-density evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluated of log-density for an encoded sequence of iid multinomial observations.

See log_density() for details on the log-density function for MultinomialDistribution.

Arg ‘x’ is a tuple of size 7 containing:: x[0] (ndarray[int]): Observation index of sequence values. x[1] (ndarray[float]): Trial size for each observation. x[2] (ndarray[float]): Non-zero trial size indices. x[3] (T1): Sequence encoded flattened list of values from x. x[4] (Optional[T2]): Sequence encoded flatted list of trial sizes. x[5] (np.ndarray[float]): Flattened array of counts for values. x[6] (ndarray[float]): Flattened array of trial sizes.

Parameters:: x – See above for details.
Returns:: Numpy array of the log-density at each encoded observation of x.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded count-vector observations.

Parameters:: engine (Any)
Return type:: Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child routes for homogeneous multinomial mixtures.

Parameters:

dists (Sequence[MultinomialDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of multinomial log densities.

Parameters:

x (tuple[Any, ...])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy multinomial sufficient statistics.

Parameters:

x (tuple[Any, ...])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

to_fisher(**kwargs)[source]: Structural Fisher view for the multinomial bag.

sampler(seed=None)[source]

Return a sampler for iid multinomial bags.

Parameters:: seed (int | None) – Optional random seed.
Returns:: A configured MultinomialSampler.
Return type:: MultinomialSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from the value and length models.

Parameters:: pseudo_count (float | None) – Optional smoothing count for child estimators.
Returns:: A configured MultinomialEstimator.
Return type:: MultinomialEstimator

dist_to_encoder()[source]

Return an encoder for sparse multinomial observations.

Return type:: MultinomialDataEncoder

enumerator()[source]

Returns MultinomialEnumerator iterating (value, count)-pair lists in descending probability order.

Return type:: MultinomialEnumerator

class MultinomialEstimator(estimator, len_estimator=NullEstimator(), len_dist=None, len_normalized=False, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate a categorical multinomial from value and length sufficient statistics.

Parameters:

estimator (ParameterEstimator)
len_estimator (ParameterEstimator | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
len_normalized (bool | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: MultinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a multinomial distribution from aggregated sufficient statistics.

Parameters:

nobs (float | None) – Number of observations represented by suff_stat.
suff_stat (tuple[SS1, SS2 | None]) – Tuple of value-model and trial-count sufficient statistics.

Returns:

A fitted multinomial distribution.

Return type:

MultinomialDistribution

class MultinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Reserved exact enumerator for categorical multinomials.

Construction currently fails closed because arbitrary category distributions do not expose the finite, unique support manifest required to enumerate normalized count-vector probabilities.

Parameters:: dist (MultinomialDistribution)

class CompositeDistribution(dists, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Product distribution over heterogeneous component variables.

Parameters:

dists (Sequence[SequenceEncodableProbabilityDistribution])
prior (Sequence[SequenceEncodableProbabilityDistribution] | None)

compute_capabilities()[source]: Return compute-backend metadata shared by all component distributions.

property count: int: Number of components, derived from the canonical immutable child tuple.

get_prior()[source]

Return the joint prior as the list of per-component child priors (in component order).

Return type:: list[SequenceEncodableProbabilityDistribution | None]

set_prior(prior)[source]

Distribute per-component parameter priors to the wrapped child distributions.

CompositeDistribution owns no parameters of its own; the joint prior factors over the independent components. prior=None is a no-op (children keep their existing priors, leaving the MLE path byte-identical); otherwise prior must be a sequence of exactly count child priors that are pushed to the children via their own set_prior.

Parameters:: prior (Sequence[SequenceEncodableProbabilityDistribution | None] | None)
Return type:: None

expected_log_density(x)[source]

Prior-expected log-density: sum of the component expected_log_density values at x.

Parameters:: x (tuple[Any, ...])
Return type:: float

seq_expected_log_density(x)[source]

Vectorized prior-expected log-density: sum of the component seq_expected_log_density values.

Parameters:: x (E)
Return type:: ndarray

compute_declaration()[source]: Return the symbolic declaration for the product of component distributions.

marginal(indices)[source]

The marginal sub-composite over the given component indices.

Because the components are independent, the marginal of a subset of coordinates is just the sub-product over those coordinates, in the caller’s requested order. Indices must be unique, integer, in range, and non-empty. Used (with condition()) by MixtureDistribution.conditional to score the observed coordinates of a partial observation.

Parameters:: indices (Sequence[int])
Return type:: CompositeDistribution

condition(observed)[source]

The conditional sub-composite over the UNobserved components given observed.

observed maps a component index to its (present) value. Since the components are independent, conditioning leaves the unobserved factors unchanged – the conditional is the sub-product over the coordinates not in observed (the observed values do not enter). This is the per-component piece that makes MixtureDistribution.conditional return the posterior/imputation over the missing fields of a partial observation.

Parameters:: observed (Mapping[int, Any])
Return type:: CompositeDistribution

density(x)[source]

Evaluates density of CompositeDistribution for single observation tuple x.

p_mat(x) = p_mat(x_0 | dist_0)*p_mat(x_1 | dist_1)*…*p_mat(x_{n-1} | dist_{n-1}),

where dist_k is the k^{th} element of member variable dists and is consistent with data type type(x[k]).

Parameters:: x (Tuple[Any, ...]) – Tuple of length = len(dists), the k^{th} data type must be consistent with dists[k].
Returns:: Density as float.
Return type:: float

density_semantics()[source]: Return joined density semantics over all component distributions.

log_density(x)[source]

Evaluates log-density of CompositeDistribution for single observation tuple x.

log(p_mat(x)) = log(p_mat(x_0 | dist_0)) + log(p_mat(x_1 | dist_1)) + … + log(p_mat(x_{n-1} | dist_{n-1})),

where dist_k is the k^{th} element of member variable dists and is consistent with data type type(x[k]).

Parameters:: x (Tuple[Any, ...]) – Tuple of length = len(dists), the k^{th} data type must be consistent with dists[k].
Returns:: Log-density as float.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log density for Tuple of dist encoded data.

Each entry of x is an encoded sequence, encoded by the DataSequenceEncoder of dist[k].dist_to_encoder().

Note: len(x) == len(dists). :param x: Tuple of length = len(dists), with k^{th} entry given by encoded sequence of dist[k]’s. :type x: E

Returns:: np.ndarray of log_density evaluated at all encoded data points.
Parameters:: x (E)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density by composing child distributions.

Parameters:

x (E)
engine (Any)

Return type:

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child parameters for homogeneous composite mixtures.

Parameters:

dists (Sequence[CompositeDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of composite log densities.

Parameters:

x (E)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy composite sufficient statistics.

Parameters:

x (E)
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

support_size()[source]

Product of child support sizes (None if any child is infinite).

Return type:: int | None

to_fisher(**kwargs)[source]: Structural Fisher view (product of child views).

to_exponential_family(engine=None)[source]

Return the product exponential-family view, or None.

A composite is an exponential family iff every child is: the canonical pieces concatenate (eta, T) and add (A, log h). Returns None when any child is not a (single) exponential family.

Parameters:: engine (Any)

sampler(seed=None)[source]

Return a sampler that samples each component independently.

Parameters:: seed (Optional[int]) – Seed to set for sampling with RandomState.
Returns:: CompositeSampler object.
Return type:: CompositeSampler

estimator(pseudo_count=None)[source]

Return a composite estimator built from the component estimators.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics in estimation.
Returns:: CompositeEstimator object.
Return type:: CompositeEstimator

decomposition()[source]: Composite factors are independent: split along the factor axis, sufficient stats SUM-reduce.

dist_to_encoder()[source]

Return a tuple encoder assembled from the component encoders.

Passes ‘encoders’, which is a list of DataSequenceEncoders for each component of the CompositeDistribution.

Returns:: CompositeDataEncoder object.
Return type:: CompositeDataEncoder

enumerator()[source]

Creates CompositeEnumerator iterating tuples in descending joint probability order.

Return type:: CompositeEnumerator

conditional_enumerator(given)[source]

Enumerate complete tuples consistent with the fixed positions in given, best-first.

given is a mapping {position: value} pinning a subset of coordinates (most-probable completion / imputation). Because the components are independent, descending order over the free coordinates is descending conditional order; each yielded tuple has the fixed positions filled in and carries the full joint log_density (the fixed positions are a constant offset). Raises ValueError for an out-of-range position.

Parameters:: given (Mapping[int, Any])
Return type:: CompositeConditionalEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded index with a DP over additive quantized child costs.

Each child item is assigned an integer cost ceil(bits/bin_width_bits). The composite cost is the sum of those integer costs, so the bin counts are a convolution of child cost-bin counts. Items are unranked lazily from the child bin offsets when requested; the returned log probability is still the exact joint log-density.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

LazyQuantizedEnumerationIndex

structural_fine_bucket(value, quantizer)[source]

Sum of child structural buckets – mirrors the count index’s child convolution.

Return type:: int

quantized_count_index(quantizer, max_fine_bucket)[source]

Structural count index: the ADDITIVE law – the carrier’s n-ary product over children.

The complete log density is the sum of independent child log densities, so the joint count histogram is the times/product (convolution) of the child histograms in the witness-retaining count semiring (mixle.enumeration.quantization.semiring). Children are consumed by their counts and lazy unranker – never drained – so a child with astronomically large support (e.g. a Sequence) composes without being materialized. Swapping the carrier (e.g. a tropical one) would reuse this same reduction.

Parameters:: max_fine_bucket (int)

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an aligned cross-bin view for compatible composite distributions.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an aligned cross-bin view for two compatible composite distributions.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class CompositeEstimator(estimators, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimator that fits each independent component distribution from its own statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
keys (str | None)
prior (Sequence[Any] | None)

property count: int: Number of child estimators, derived from the canonical immutable tuple.

get_prior()[source]

Return the joint prior as the list of per-component child estimator priors (in order).

Return type:: list[Any]

set_prior(prior)[source]

Distribute per-component parameter priors to the child estimators.

prior=None is a no-op (children keep their existing priors). Otherwise prior must be a sequence of exactly count priors pushed to the children via their own set_prior.

Parameters:: prior (Sequence[Any] | None)
Return type:: None

model_log_density(model)[source]

Sum the child estimators’ model_log_density on the corresponding child models (ELBO global term).

Parameters:: model (CompositeDistribution)
Return type:: float

accumulator_factory()[source]

Return an accumulator factory assembled from the child estimators.

Return type:: CompositeAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a CompositeDistribution from an aggregated sufficient statistics Tuple for a given number of: observations (nobs).

Parameters:

nobs (Optional[float]) – Weighted number of observations used to form suff_stat.
suff_stat (SS) – Tuple of sufficient statistics for each ParameterEstimator of estimators.

Returns:

CompositeDistribution estimated from argument aggregated sufficient statistics (suff_stat), from a given: number of observation (nobs).

Return type:

CompositeDistribution

class CompositeEnumerator(dist)[source]

Bases: DistributionEnumerator

Best-first enumerator over the Cartesian product of component supports.

Parameters:: dist (CompositeDistribution)

class ConditionalDistribution(dmap, default_dist=NullDistribution(), given_dist=NullDistribution(), name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

ConditionalDistribution models pairs (x0, x1) with density P_cond(x1 | x0) * P_given(x0), where the conditional distributions are looked up from a dictionary keyed by x0.

Parameters:

dmap (dict[Any, SequenceEncodableProbabilityDistribution] | list[SequenceEncodableProbabilityDistribution])
default_dist (SequenceEncodableProbabilityDistribution | None)
given_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
keys (str | None)
prior (tuple[dict[Any, Any], Any, Any] | None)

get_prior()[source]

Return the joint prior as (per_branch_priors, default_prior, given_prior).

per_branch_priors is a dict keyed like dmap of each conditional branch’s prior.

Return type:: tuple[dict[Any, Any], Any, Any]

set_prior(prior)[source]

Distribute per-branch priors to the conditional branches, default, and given distributions.

prior=None is a no-op (children keep their existing priors, leaving the MLE path byte-identical). Otherwise prior is (per_branch_priors, default_prior, given_prior): each dmap branch prior is pushed to the matching child via set_prior, and the default/given priors are pushed to default_dist/given_dist.

Parameters:: prior (tuple[dict[Any, Any], Any, Any] | None)
Return type:: None

expected_log_density(x)[source]

Prior-expected log-density: selected branch expected_log_density + given term.

Mirrors log_density: unmatched conditioning values with no default score -inf.

Parameters:: x (tuple[T0, T1])
Return type:: float

seq_expected_log_density(x)[source]

Vectorized prior-expected log-density mirroring seq_log_density.

Parameters:: x (E0)
Return type:: ndarray

compute_capabilities()[source]: Declare generated-compute support joined across branch, default, and given models.

density_semantics()[source]: Classify a conditional kernel without a given law as a likelihood factor.

compute_declaration()[source]: Return the generated-compute declaration for the conditional distribution.

density(x)[source]

Evaluates density of ConditionalDistribution at Tuple x.

Calls log_density() and returns the exponentiated result. See log_density() for details.

Parameters:: x (Tuple[T0, T1]) – T0 data type much match keys of dmap, T1 much match value of dmap distribution for key value.
Returns:: Density of ConditionalDistribution at Tuple x
Return type:: float

log_density(x)[source]

Evaluate log-density of ConditionalDistribution at Tuple x.

Log-density:: log(P(x)) = log(P_cond(x[1] | x[0])) + log(P_given(x[0])), where log(P_cond(x[1] | x[0])) is defined from dmap, and log(P_given(x[0])) is defined from given_dist.

Note: Log-density is evaluated to -np.inf, if x[0] not in dmap and default_dist is NullDistribution().

Parameters:: x (Tuple[T0, T1]) – T0 data type much match keys of dmap, T1 much match value of dmap distribution for key value.
Returns:: Log-density of ConditionalDistribution at Tuple x.
Return type:: float

seq_log_density(x)[source]

Arkouda vectorized evaluation of the log-density on sequence encoded data x.

x Tuple of length 5:

x[0] (int): length of x (i.e. total observations).
x[1] (Tuple[T0]): Unique conditional values in data.
x[2] (Tuple[E0,...]): Tuple of encoded data sequences for each given key.
x[3] (Tuple[ak.pdarray,...]): Tuple containing idxs for observation corresponding to x[1] values.
x[4] (Optional[Encoded[T0]]): If the given_encoder is not the NullDataEncoder, the
    observed conditional values of data type T0 are sequence encoded by given_encoder. Else return None.

Parameters:: x (E0) – See above for details.
Returns:: Numpy array of log-density evaluated at each encoded data point.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for grouped conditional encodings.

Parameters:

x (E0)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child routes for homogeneous conditional mixtures.

Parameters:

dists (Sequence[ConditionalDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of conditional log densities.

Parameters:

x (E0)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return versioned per-component conditional sufficient statistics.

Parameters:

x (E0)
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[ConditionalStatistics, …]

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

sampler(seed=None)[source]

Create a sampler for this conditional distribution.

Parameters:: seed (Optional[int]) – Seed for the sampler’s random number generator.
Returns:: ConditionalDistributionSampler configured from this distribution.
Return type:: ConditionalDistributionSampler

conditional_sampler(seed=None)[source]

Return a sampler that can draw values for caller-supplied given values.

Parameters:: seed (int | None)
Return type:: ConditionalDistributionSampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this conditional distribution.

Used to estimate a ConditionalDistribution from data observations.

Parameters:: pseudo_count (Optional[float]) – Used to inflate the sufficient statistics of ConditionalDistribution.
Returns:: ConditionalDistributionEstimator with estimators for the branch, default, and given distributions.
Return type:: ConditionalDistributionEstimator

dist_to_encoder()[source]

Create a data encoder for conditional-distribution observations.

Return type:: ConditionalDistributionDataEncoder

enumerator()[source]

Creates a ConditionalDistributionEnumerator iterating (given, value) pairs in descending joint probability order.

Requires an enumerable given distribution and enumerable conditional distributions; raises EnumerationError otherwise.

Returns:: ConditionalDistributionEnumerator object.
Return type:: ConditionalDistributionEnumerator

class ConditionalDistributionEstimator(estimator_map, default_estimator=NullEstimator(), given_estimator=NullEstimator(), name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

ConditionalDistributionEstimator estimates a ConditionalDistribution from aggregated sufficient statistics.

Parameters:

estimator_map (dict[T0, ParameterEstimator])
default_estimator (ParameterEstimator | None)
given_estimator (ParameterEstimator | None)
name (str | None)
keys (str | None)
prior (tuple[dict[Any, Any], Any, Any] | None)

get_prior()[source]

Return the joint prior as (per_branch_priors, default_prior, given_prior) from child estimators.

Return type:: tuple[dict[Any, Any], Any, Any]

set_prior(prior)[source]

Distribute per-branch priors to the child estimators (branches, default, given).

prior=None is a no-op. Each branch prior is pushed to the matching estimator via set_prior; default/given priors go to the default/given estimators.

Parameters:: prior (tuple[dict[Any, Any], Any, Any] | None)
Return type:: None

model_log_density(model)[source]

Sum each branch’s estimator model_log_density plus the default and given terms.

Parameters:: model (ConditionalDistribution)
Return type:: float

accumulator_factory()[source]

Return an accumulator factory for the given, branch, and default estimators.

Return type:: ConditionalDistributionAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a ConditionalDistribution from aggregated data.

Calls the estimate() member function of each ParameterEstimator instance for estimator_map, default_estimator, and given_estimator.

Input suff_stat if a Tuple of size three containing sufficient statistics compatible with each respective ParameterEstimator. Entry one of the Tuple must be a dict with keys of data type T0, matching the data type for the given distribution.

Return the conditional distribution estimated from the sufficient statistics in suff_stat.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency.
suff_stat (ConditionalStatistics) – See description above.

Returns:

ConditionalDistribution object.

Return type:

ConditionalDistribution

class ConditionalDistributionEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates (given, value) pairs of a ConditionalDistribution in descending joint probability order.

Parameters:: dist (ConditionalDistribution)

class ConditionalStatistics(schema_version, branches, default_nobs, default, given_nobs, given)[source]

Bases: NamedTuple

Versioned sufficient statistics for a fixed conditional branch layout.

Parameters:

schema_version (int)
branches (tuple[ConditionalBranchStatistics, ...])
default_nobs (float)
default (Any | None)
given_nobs (float)
given (Any | None)

schema_version: int: Alias for field number 0

branches: tuple[ConditionalBranchStatistics, ...]: Alias for field number 1

default_nobs: float: Alias for field number 2

default: Any | None: Alias for field number 3

given_nobs: float: Alias for field number 4

given: Any | None: Alias for field number 5

class ConditionalBranchStatistics(key, nobs, statistic)[source]

Bases: NamedTuple

One branch’s effective count and child sufficient statistic.

Parameters:

key (Any)
nobs (float)
statistic (Any)

key: Any: Alias for field number 0

nobs: float: Alias for field number 1

statistic: Any: Alias for field number 2

exception NonGenerativeConditionalError[source]

Bases: TypeError

Raised when a conditional factor without a given law is asked to generate pairs.

ConditionalEstimator: alias of ConditionalDistributionEstimator

ConditionalEnumerator: alias of ConditionalDistributionEnumerator

class ChowLiuTreeDistribution(parents, marginal_dists, conditional_dists, default_dists=None, feature_order=None, parent_values=None, name=None, keys=None, pseudo_count=None, mi_pseudo_count=None, default_policy='marginal')[source]

Bases: SequenceEncodableProbabilityDistribution

Chow-Liu tree over fixed-position fields with generic conditional models.

parents[i] gives the parent feature of feature i; exactly one entry must be None and is treated as the root. The root uses its marginal distribution. Non-root features use conditional_dists[i][freeze(x[parent])] when present, otherwise default_dists[i] if one was supplied.

Parameters:

parents (Sequence[int | None])
marginal_dists (Sequence[SequenceEncodableProbabilityDistribution])
conditional_dists (Sequence[dict[Hashable, SequenceEncodableProbabilityDistribution] | None])
default_dists (Sequence[SequenceEncodableProbabilityDistribution | None] | None)
feature_order (Sequence[int] | None)
parent_values (Sequence[dict[Hashable, Any]] | None)
name (str | None)
keys (str | None)
pseudo_count (Any)
mi_pseudo_count (float | None)
default_policy (str)

compute_capabilities()[source]: Describe backend support shared by the tree’s component distributions.

compute_declaration()[source]: Return a composite compute declaration for tree marginals and conditionals.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (Sequence[Any])
Return type:: float

conditional_dist(child, parent_value)[source]

Return the conditional distribution associated with a child and parent assignment.

Parameters:

child (int)
parent_value (Any)

Return type:

SequenceEncodableProbabilityDistribution | None

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (Sequence[Any])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (Sequence[Sequence[Any]])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral grouped scoring for fixed Chow-Liu tree factors.

Parameters:

x (Sequence[Sequence[Any]])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: ChowLiuTreeSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: ChowLiuTreeEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: ChowLiuTreeDataEncoder

enumerator()[source]

Return an enumerator over the distribution support when available.

Return type:: ChowLiuTreeEnumerator

class ChowLiuStatistics(total_weight, num_features, marginal_counts, marginal_values, joint_counts, marginal_stats, conditional_stats)[source]

Bases: NamedTuple

Versioned, tuple-compatible generic Chow–Liu sufficient statistics.

Parameters:

total_weight (float)
num_features (int)
marginal_counts (list[dict[Hashable, float]])
marginal_values (list[dict[Hashable, Any]])
joint_counts (dict[tuple[int, int], dict[tuple[Hashable, Hashable], float]])
marginal_stats (tuple[Any, ...])
conditional_stats (dict[tuple[int, int], dict[Hashable, Any]])

total_weight: float: Alias for field number 0

num_features: int: Alias for field number 1

marginal_counts: list[dict[Hashable, float]]: Alias for field number 2

marginal_values: list[dict[Hashable, Any]]: Alias for field number 3

joint_counts: dict[tuple[int, int], dict[tuple[Hashable, Hashable], float]]: Alias for field number 4

marginal_stats: tuple[Any, ...]: Alias for field number 5

conditional_stats: dict[tuple[int, int], dict[Hashable, Any]]: Alias for field number 6

property schema_version: int: Return the serialized statistic schema version.

class ChowLiuTreeEstimator(estimators, root=0, pseudo_count=None, mi_pseudo_count=None, default_policy='marginal', keys=None, name=None)[source]

Bases: ParameterEstimator

Estimate a generic Chow-Liu tree from fixed-length tuple observations.

Structure learning uses empirical mutual information over observed field values, so it is best suited to finite/enumerable or intentionally discretized coordinates. Once an edge is chosen, the child conditional distribution for each parent value is estimated with that child’s supplied estimator.

Parameters:

estimators (Sequence[ParameterEstimator | SequenceEncodableProbabilityDistribution])
root (int)
pseudo_count (float | None)
mi_pseudo_count (float | None)
default_policy (str)
keys (str | None)
name (str | None)

accumulator_factory()[source]

Return an accumulator factory for Chow-Liu structure and parameter statistics.

Return type:: ChowLiuTreeAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the Chow-Liu tree structure and all node distributions.

Parameters:

nobs (float | None)
suff_stat (ChowLiuStatistics)

Return type:

ChowLiuTreeDistribution

class ChowLiuTreeEnumerator(dist)[source]

Bases: DistributionEnumerator

Finite-support enumerator for a ChowLiuTreeDistribution.

Parameters:: dist (ChowLiuTreeDistribution)

class DiracLengthMixtureDistribution(len_dist, p, v=0, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Mixture between a fixed length and a learned length distribution.

Parameters:

p (float) – Probability of being drawn from length distribution. Must be between 0 and 1.
len_dist (SequenceEncodableProbabilityDistribution) – Distribution with support on non-negative integers.
name (Optional[str]) – Optional distribution name.
v (int)

p

Probability of being drawn from length distribution. Must be between 0 and 1.

Type:: float

len_dist

Distribution with support on non-negative integers.

Type:: SequenceEncodableProbabilityDistribution

name

Optional distribution name.

Type:: Optional[str]

compute_capabilities()[source]: Declare generated-compute support inherited from the length distribution.

compute_declaration()[source]: Return the generated-compute declaration for the Dirac-length mixture.

density(x)[source]

Evaluate density of length Dirac mixture distribution at observation x.

See log_density() for details.

Parameters:: x (int) – Integer value.
Returns:: Density at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of length Dirac mixture distribution at observation x.

log(P(x)) = log( p*P_1(x) + (1-p)*Delta_{v}(x) ),

Parameters:: x (int) – Integer value.
Returns:: log-density at x.
Return type:: float

component_log_density(x)[source]

Log-density of each mixture component (length distribution, dirac at v) at x.

Parameters:: x (int) – Integer value.
Returns:: Numpy array of the two component log-densities.
Return type:: ndarray

posterior(x)[source]

Posterior probability of each mixture component given observation x.

Parameters:: x (int) – Integer value.
Returns:: Numpy array of the two component posterior probabilities (sums to one).
Return type:: ndarray

seq_component_log_density(x)[source]

Vectorized component log-densities at sequence encoded input x.

Parameters:: x (E) – Sequence encoded data from DiracLengthMixtureDataEncoder.
Returns:: Numpy array of shape (len(x), 2) of component log-densities.
Return type:: ndarray

seq_log_density(x)[source]

Vectorized evaluation of the mixture log-density at sequence encoded input x.

Parameters:: x (E) – Sequence encoded data from DiracLengthMixtureDataEncoder.
Returns:: Numpy array of log-density (float) of len(x).
Return type:: ndarray

backend_seq_component_log_density(x, engine)[source]

Engine-neutral component log densities for encoded length/dirac mixtures.

Parameters:

x (tuple[int, ndarray, ndarray, E0])
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral mixture log-density for encoded length/dirac observations.

Parameters:

x (tuple[int, ndarray, ndarray, E0])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for shared-dirac length mixtures.

Parameters:

dists (Sequence[DiracLengthMixtureDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of length/dirac mixture log densities.

Parameters:

x (tuple[int, ndarray, ndarray, E0])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy (component_counts, length_stat) statistics.

Parameters:

x (tuple[int, ndarray, ndarray, E0])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

seq_posterior(x)[source]

Vectorized component posterior probabilities at sequence encoded input x.

Parameters:: x (E) – Sequence encoded data from DiracLengthMixtureDataEncoder.
Returns:: Numpy array of shape (len(x), 2) of component posteriors.
Return type:: ndarray

sampler(seed=None)[source]

Create a DiracLengthMixtureSampler from parameters of this distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: DiracLengthMixtureSampler object.
Return type:: DiracLengthMixtureSampler

estimator(pseudo_count=None)[source]

Create a DiracLengthMixtureEstimator with matching dirac value v.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: DiracLengthMixtureEstimator object.
Return type:: DiracLengthMixtureEstimator

dist_to_encoder()[source]

Returns a DiracLengthMixtureDataEncoder for encoding sequences of iid integer observations.

Return type:: DiracLengthMixtureDataEncoder

enumerator()[source]

Returns a DiracLengthMixtureEnumerator iterating the union of the length-distribution support and the dirac point v in descending probability order.

Return type:: DiracLengthMixtureEnumerator

class DiracLengthMixtureEstimator(estimator, v=0, fixed_p=None, suff_stat=None, pseudo_count=None, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

Estimate Dirac-length mixture distributions.

Parameters:

estimator (ParameterEstimator) – Estimator for the length distribution.
v (int) – Dirac location.
fixed_p (Optional[float]) – Hold the length-distribution weight p fixed at this value.
suff_stat (Optional[float]) – Prior value of p used with pseudo_count for regularization.
pseudo_count (Optional[float]) – Used to inflate the component count statistics.
name (Optional[str]) – Optional name assigned to estimated distributions.
keys (Tuple[Optional[str], Optional[str]]) – Keys for the mixture weights and component statistics.

estimator

Estimator for the length distribution.

Type:: ParameterEstimator

v

Dirac location.

Type:: int

pseudo_count

Used to inflate the component count statistics.

Type:: Optional[float]

suff_stat

Prior value of p used with pseudo_count for regularization.

Type:: Optional[float]

keys

Keys for the mixture weights and component statistics.

Type:: Tuple[Optional[str], Optional[str]]

name

Optional name assigned to estimated distributions.

Type:: Optional[str]

fixed_p_vec

Fixed component weights [p, 1-p] when fixed_p is given.

Type:: Optional[np.ndarray]

accumulator_factory()[source]

Returns a DiracLengthMixtureAccumulatorFactory consistent with this estimator.

Return type:: DiracLengthMixtureAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a DiracLengthMixtureDistribution from accumulated sufficient statistics.

Parameters:

nobs (Optional[float]) – Weighted number of observations.
suff_stat (Tuple[np.ndarray, SS0]) – Component counts and length-distribution statistics.

Returns:

DiracLengthMixtureDistribution object.

Return type:

DiracLengthMixtureDistribution

class DiracLengthMixtureEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates the union of the length-distribution support and the dirac point v.

The model is a two-component mixture: the length distribution with weight p and a dirac delta at v with weight 1-p. The dirac component contributes the trivial single-point stream [(v, 0.0)]. Supports may overlap (the length distribution can also emit v), so candidates are de-duplicated and re-scored exactly with the mixture log-density.

Parameters:: dist (DiracLengthMixtureDistribution)

class DirichletDistribution(alpha, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Dirichlet distribution over probability vectors, with concentration parameters alpha.

Parameters:

alpha (list[float] | ndarray)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare backend support for Dirichlet generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Dirichlet distribution.

get_parameters()[source]

Return the concentration vector alpha.

Lets a DirichletDistribution serve as a conjugate prior (on a Categorical/Mixture weight simplex) under the unified Bayesian estimation protocol.

Return type:: ndarray

cross_entropy(dist)[source]

Cross entropy -E_self[log dist(x)] for a Dirichlet argument.

Accepts another DirichletDistribution (full concentration vector) or a SymmetricDirichletDistribution (scalar concentration broadcast to this distribution’s dimension). Both arise as the conjugate prior/posterior over the same simplex during variational Bayes (e.g. the ELBO global term in DPM).

Parameters:: dist (SequenceEncodableProbabilityDistribution)
Return type:: float

entropy()[source]

Returns the differential entropy in nats.

Return type:: float

density(x)[source]

Evaluate the density of a dirichlet observation.

See log_density() for details.

Parameters:: x (Union[List[float], np.ndarray]) – A single dirichlet observation.
Returns:: Density evaluated at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of a dirichlet observation.

The log-density of a Dirichlet with dim = K, is given by

log(p_mat(x)) = -log(Const) + sum_{k=0}^{K-1} (alpha_k -1)*log(x_k), for sum_k x_k = 1.0,

else -inf. In above

log(Const) = sum_{k=0}^{K-1} log(Gamma(alpha_k)) - log(Gamma(sum_{k=0}^{K-1} alpha_k)).

Parameters:: x (Union[List[float], np.ndarray]) – A single dirichlet observation.
Returns:: Log-density evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of the log-density at a sequence-encoded input x.

Parameters:: x (Tuple[np.ndarray, np.ndarray, np.ndarray]) – Encoded data from DirichletDataEncoder.seq_encode(), a tuple of (log of observations, observations, squared observations).
Returns:: Numpy array containing the log-density of each encoded observation. Rows that are not on the simplex (a negative or non-finite entry, or a row that doesn’t sum to one) score -inf, mirroring log_density – the encoder’s clipped log representation alone can’t distinguish a genuine near-zero coordinate from a negative one, so validation reads the accompanying raw observations instead.
Return type:: ndarray

static backend_log_density_from_params(log_x, alpha, log_const, engine)[source]

Engine-neutral Dirichlet log-density from encoded log observations.

Parameters:

log_x (Any)
alpha (Any)
log_const (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded Dirichlet observations.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for equal-dimensional Dirichlet mixtures.

Parameters:

dists (Sequence[DirichletDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Dirichlet component log densities.

Parameters:

x (tuple[Any, Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked legacy Dirichlet sufficient statistics.

Parameters:

x (tuple[Any, Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

to_fisher(**kwargs)[source]: Return the Dirichlet’s log-coordinate Fisher view (generic fallback for degenerate alpha).

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional random seed.
Return type:: DirichletSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution.

When pseudo_count is provided, the normalized concentration vector regularizes the estimate.

Parameters:: pseudo_count (float | None) – Optional weight for the current normalized concentration vector.
Return type:: DirichletEstimator

dist_to_encoder()[source]

Create the encoder for iid Dirichlet observations.

Return type:: DirichletDataEncoder

class DirichletEstimator(dim=None, pseudo_count=None, suff_stat=None, delta=1.0e-8, keys=None, use_mpe=False, name=None)[source]

Bases: ParameterEstimator

Estimator for Dirichlet concentration parameters.

Parameters:

dim (int | None)
pseudo_count (float | None)
suff_stat (ndarray | None)
delta (float | None)
keys (str | None)
use_mpe (bool)
name (str | None)

accumulator_factory()[source]

Create a Dirichlet accumulator factory from this estimator’s settings.

Return type:: DirichletAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a Dirichlet distribution from aggregated sufficient statistics.

suff_stat is (count, sum_log_x, sum_x, sum_x2). The concentration parameters are solved from the mean-log-probability statistic with a safeguarded Newton solver, or find_alpha when use_mpe is set.

nobs is accepted for estimator API consistency but counts are taken from suff_stat[0].

Parameters:

nobs (float | None)
suff_stat (tuple[int, ndarray, ndarray, ndarray])

Return type:

DirichletDistribution

class DiagonalGaussianDistribution(mu, covar=MISSING, name=None, keys=None, covariance=MISSING, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Multivariate Gaussian distribution with independent components (diagonal covariance matrix).

Parameters:

mu (Sequence[float] | ndarray)
covar (Sequence[float] | ndarray)
name (str | None)
keys (str | None)
covariance (Sequence[float] | ndarray)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for diagonal Gaussian generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the diagonal Gaussian.

static exp_family_sufficient_statistics(x, engine)[source]

Return vector sufficient statistics for generated diagonal-Gaussian scoring.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return vector natural parameters for generated diagonal-Gaussian scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the diagonal-Gaussian log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return row-wise legacy accumulator statistics for generated resident reductions.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

set_prior(prior)[source]

Attach a parameter prior and precompute conjugate-prior expectations.

With a MultivariateNormalGamma(mu0, lam, a, b) prior over (mu, tau=1/covar) this caches the expected natural parameters [ea, eb, e1, e2] with e1 = E[mu*tau] and e2 = -0.5*E[tau] per component (ea, eb scalars summed over components), so that expected_log_density(x) = x.e1 + (x*x).e2 - ea + eb. Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | mu, tau)] under the prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Evaluate the density at observation x.

See log_density() for details.

Parameters:: x (Union[Sequence[float], np.ndarray]) – Length-dim observation vector.
Returns:: Density at x.

log_density(x)[source]

Evaluate the log-density at observation x.

The log-density is given by

log(p(x)) = -0.5*sum_{i=1}^{n} (x_i-m_i)^2 / s2_i - 0.5*log(s2_i) - (n/2)*log(2*pi).

Computed in the CENTERED form the formula above states, -0.5*sum (x-mu)^2/covar, not in the algebraically equal expanded form x^2*ca + x*cb + cc. The expanded form is three terms of size O(|x|^2/covar) summing to an O(1) answer, so at |x| ~ 1e9 with unit variance it cancels away every significant digit: the scorer returned round-number garbage (measured: log-likelihoods of exactly 66560.0 and -135168.0 on unit-variance data at offset 1.7e9), and because EM selects the model with the best objective, an optimize/fit run at that offset returned the WORSE of its own iterates. x - mu is exact for operands of the same magnitude, so the centered form is accurate at any offset; it is also one gemv instead of two. The full-covariance estimator’s scorer always used the centered form – this is the diagonal one catching up, and it makes the documented formula true (T1-F1). The expanded coefficients remain available as ca/cb/cc for the fused kernels.

Parameters:: x (Union[Sequence[float], np.ndarray]) – Length-dim observation vector.
Returns:: Log-density at x.

condition(observed)[source]

Return the conditional over the unobserved dimensions given observed.

A diagonal Gaussian has independent coordinates, so conditioning on some of them leaves the rest unchanged: the result is just DiagonalGaussian(mu[unobserved], covar[unobserved]) (the observed values do not shift the unobserved mean or variance). Provided so diagonal-covariance Gaussian mixtures support MixtureDistribution.conditional() – there the responsibilities still update from how well each component explains the observed coordinates, even though the within-component coordinates are independent. Raises if no dimension is left unobserved.

Parameters:: observed (dict[int, float])
Return type:: DiagonalGaussianDistribution

marginal(keep)[source]

Return the marginal over the dimensions keep: DiagonalGaussian(mu[keep], covar[keep]).

Marginalizing a diagonal Gaussian simply drops the other independent coordinates (order kept).

Parameters:: keep (Sequence[int])
Return type:: DiagonalGaussianDistribution

density_cumulative(x)[source]

Exact probability-ordered cumulative G(x) = P(p(Y) >= p(x)) – the highest-density-region mass through x (multivariate analogue of a CDF). For a diagonal Gaussian the squared Mahalanobis distance sum_i (x_i-mu_i)^2/var_i is chi-square(dim), so G = chi2.cdf(maha2, dim). Used by mixle.enumeration.density_rank.density_rank() to return an EXACT cumulative.

Parameters:: x (Sequence[float] | ndarray)
Return type:: float

density_quantile(q)[source]

Inverse of density_cumulative(): a representative point at cumulative-density index q.

q is the highest-density-region mass, whose boundary is the squared-Mahalanobis level chi2.ppf(q, dim); a representative point on that contour offsets the first coordinate by sqrt(level * var_0) (Mahalanobis distance exactly the level). Sweeping q enumerates the support in descending density.

Parameters:: q (float)
Return type:: ndarray

seq_log_density(x)[source]

Vectorized evaluation of the log-density at a sequence-encoded input x.

Parameters:: x (np.ndarray) – Encoded data matrix with shape (sz, dim) from DiagonalGaussianDataEncoder.seq_encode().
Returns:: Numpy array of length sz containing the log-density of each encoded observation.
Return type:: ndarray

static backend_log_density_from_params(x, mu, covar, engine)[source]

Engine-neutral diagonal Gaussian log-density from explicit parameters.

Parameters:

x (Any)
mu (Any)
covar (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked diagonal-Gaussian parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[DiagonalGaussianDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of diagonal-Gaussian log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

to_fisher(**kwargs)[source]: Return this distribution’s own Fisher view.

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional seed for the sampler’s random state.
Returns:: A configured DiagonalGaussianSampler.
Return type:: DiagonalGaussianSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s shape.

Parameters:: pseudo_count (float | None) – Optional smoothing count applied to mean and variance estimates.
Returns:: A DiagonalGaussianEstimator.
Return type:: DiagonalGaussianEstimator

dist_to_encoder()[source]

Return an encoder for iid diagonal Gaussian observations.

Return type:: DiagonalGaussianDataEncoder

class DiagonalGaussianEstimator(dim=None, pseudo_count=(None, None), suff_stat=(None, None), name=None, keys=None, prior=None, min_covar=None, ridge=None)[source]

Bases: ParameterEstimator

Estimator for diagonal Gaussian distributions.

The fit is SHIFT-EQUIVARIANT: fit(x + c) returns the variances of x + c to within about 1e-7 relative for any constant c the data can carry, epoch seconds (~1.7e9) included. That is not free from the declared (sum, sum2, count) statistics – their variance is the cancellation-prone E[x^2] - mu^2, which at offset 1e7 was tens of percent wrong and at 1.7e9 thousands-fold wrong or collapsed onto the floor – so DiagonalGaussianAccumulator carries a conditioning-gated shift-anchored moment track and this estimator reads it. Statistics that arrive already reduced and WITHOUT that track (an engine kernel’s stacked moments, a hand-built tuple) cannot be corrected here and take the historical path; when they are too ill-conditioned for it, estimate warns rather than returning variances it cannot stand behind.

The 1e-7 is a measured relative bound, not a figure of speech, and the error is NOT uniform across the offset range. Once the anchored track engages, the variances are exact to a few ulps (~1e-14 relative, and unchanged from offset 1.7e9 to 1e10). The bound is set by the band just BELOW the conditioning gate, where the raw E[x^2] - mu^2 form is still in use because it is accurate enough to be worth its single pass: at mean^2/variance just under the gate’s 4e6 the worst case measured over seeds, sample sizes and scales is 3.1e-8 relative. An earlier revision of this docstring promised “a few ulps” everywhere, which overstated that band by roughly eight orders of magnitude (T1-07).

VARIANCE FLOOR. The fitted variances are the exact per-coordinate maximum-likelihood ones whenever every coordinate has a positive variance of its own. The M-step floors each coordinate at ridge * var_i (default ridge=1e-6) – RELATIVE to that coordinate’s own variance, so the safeguard is equivariant under any per-coordinate change of units and, sitting strictly below the variance it guards, never binds on such a coordinate. It is not priced off mean(var) across coordinates: that coupled columns a diagonal covariance exists to keep independent, and inflated the smallest variance of a plain probability/dollars/count table 3.03x (T1-03).

A coordinate with no positive variance of its own – a constant column, an EM component holding a single point – still has to be lifted, because a zero variance is an infinite density. It gets ridge * mean(var over the coordinates that have one), the same manufactured jitter the full covariance estimator uses for a degenerate direction. The absolute min_covar (default 1e-8) is the last resort when nothing carries a scale at all (every coordinate non-positive, or ridge=0.0), and becomes a hard per-coordinate lower bound as soon as it is passed explicitly – which is how mixle.task regularizes its diagonal Gaussians.

A floor that actually lifted a coordinate is recorded on the fitted distribution as a variance-floored(...) entry in numerical_repairs() – and therefore in fit_provenance().repairs – naming the coordinate and how far it moved. Manufactured jitter is always reported; an explicit min_covar dominating a positive variance is reported once it exceeds _FLOOR_MATERIAL_RATIO of it. An ordinary fit lifts nothing and records nothing. Because the default floor never binds on a coordinate with its own variance, ridge=0.0 is not the route to the maximum-likelihood fit here – it removes the only scale the degenerate-column jitter can be priced from and hands those coordinates to the absolute min_covar instead.

Parameters:

dim (int | None)
pseudo_count (float | tuple[float | None, float | None])
suff_stat (tuple[ndarray | None, ndarray | None])
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)
min_covar (float | None)
ridge (float | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: DiagonalGaussianAccumulatorFactory

model_log_density(model)[source]

Log-density of the model parameters under the MultivariateNormalGamma prior (ELBO global term).

The prior is over (mu, tau=1/covar), so the model’s covariance is inverted before scoring.

Parameters:: model (DiagonalGaussianDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a diagonal Gaussian distribution from aggregated sufficient statistics.

Suff_stat is a Tuple of size 3 containing:: suff_stat[0] (np.ndarray): Component-wise sum of weighted observation values. suff_stat[1] (np.ndarray): Component-wise sum of weighted squared observation values. suff_stat[2] (float): Sum of weights for each observation.

Parameters:

nobs (Optional[float]) – Weighted number of observations used in aggregation of suff stats.
suff_stat (Tuple[np.ndarray, np.ndarray, float]) – See above for details.

Returns:

DiagonalGaussianDistribution object.

Return type:

DiagonalGaussianDistribution

class ExponentialDistribution(beta, name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Exponential distribution on non-negative real values with scale beta.

Parameters:

beta (float)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for generated Exponential density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Exponential distribution.

static exp_family_sufficient_statistics(x, engine)[source]

Return Exponential sufficient statistics for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Exponential sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Exponential natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Exponential log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return Exponential support base measure for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

set_prior(prior)[source]

Attach a parameter prior and precompute the conjugate Gamma expectations.

The exponential rate is 1/beta; with a Gamma(k, theta) prior on that rate this caches the variational expected natural parameters so that expected_log_density(x) = e1*x - ea where the natural parameter is eta = -rate, E[eta] = -k*theta and E[-log(-eta)] = psi(k) + ln theta (mapping the prior’s (k, theta) to the bstats [a, b] = [k, 1/theta] form). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | rate)] under the Gamma prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (float)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Evaluate the density of exponential distribution with scale beta.

See log_density() for details.

Parameters:: x (float) – Non-negative real-valued number.
Returns:: Density evaluated at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of exponential distribution with scale beta.

log(f(x;beta)) = -log(beta) - x/beta, for x >= 0, else -np.inf.

Parameters:: x (float) – Non-negative real-valued number.
Returns:: Log-density evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Vectorized call to log-density on each observation value x.

Parameters:: x (np.ndarray) – Numpy array of floats.
Returns:: Numpy array of log-density (float) of len(x).
Return type:: ndarray

static backend_log_density_from_params(x, beta, engine)[source]

Engine-neutral exponential log-density from explicit parameters.

Parameters:

x (Any)
beta (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Exponential parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[ExponentialDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Exponential log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Exponential sufficient statistics using engine-resident arrays.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

to_fisher(**kwargs)[source]: Return the Exponential’s count-family Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy 1 + log(scale).

Return type:: float

skewness()[source]

Skewness (2).

Return type:: float

kurtosis()[source]

Excess kurtosis (6).

Return type:: float

mode()[source]

Mode (0).

Return type:: float

sampler(seed=None)[source]

Create a sampler with scale beta.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: ExponentialSampler object.
Return type:: ExponentialSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized with this distribution’s scale.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: ExponentialEstimator.
Return type:: ExponentialEstimator

dist_to_encoder()[source]

Return the encoder for exponential observations.

Return type:: ExponentialDataEncoder

class ExponentialEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate Exponential scale parameters from accumulated sufficient statistics.

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Create an exponential accumulator factory with this estimator’s keys.

Return type:: ExponentialAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s rate (1/beta) under the Gamma prior (ELBO global term).

Parameters:: model (ExponentialDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate ExponentialDistribution from suff_stat arg.

Estimate ExponentialDistribution from sufficient statistic tuple suff_stat, counting a float value for count and sum. If pseudo_count is set, this is used to re-weight the member value “suff_stat”, which is the scale of ExponentialEstimator object.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (Tuple[float, float]) – Tuple of count and sum. Both are positive real-valued floats.

Returns:

ExponentialDistribution object.

Return type:

ExponentialDistribution

class GammaDistribution(k, theta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gamma distribution parameterized by shape and scale.

Parameters:

k (float)
theta (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare backend support for generated Gamma density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Gamma distribution.

static exp_family_sufficient_statistics(x, engine)[source]

Return Gamma sufficient statistics for generated scoring.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Gamma sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Gamma natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Gamma log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return Gamma support base measure for generated scoring.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

get_parameters()[source]

Return the (shape k, scale theta) pair.

Lets a GammaDistribution serve as a conjugate prior (on a Poisson/Exponential rate, or a Gamma scale) under the unified Bayesian estimation protocol.

Return type:: tuple[float, float]

cross_entropy(dist)[source]

Cross entropy -E_self[log dist(x)] for a Gamma argument (closed form).

Used as the conjugate prior/posterior cross-entropy term in variational Bayes (e.g. the ELBO global term in DPM for Poisson/Exponential-rate components).

Parameters:: dist (GammaDistribution)
Return type:: float

entropy()[source]

Return the differential entropy in nats.

Return type:: float

density(x)[source]

Density of gamma distribution evaluated at x.

See log_density() for details.

Parameters:: x (float) – Positive real-valued number.
Returns:: Density of gamma distribution evaluated at x.
Return type:: float

log_density(x)[source]

Log-density of gamma distribution evaluated at x.

Log-density given by, If x > 0.0,

log(f(x;k,theta)) = -gammaln(k) - k*log(theta) + (k-1) * log(x) - x / theta,

else,

-np.inf

Parameters:: x (float) – Positive real-valued number.
Returns:: Log-density of gamma distribution evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of sequence encoded observations from gamma distribution.

Input must be x (Tuple[ndarray, ndarray]):: x[0]: Numpy array of floats containing observations from gamma distribution. x[1]: Numpy array of floats containing log of observation values.

Parameters:: x (Tuple[np.ndarray, np.ndarray]) – See above for details.
Returns:: Numpy array containing log-density evaluated at all observations of encoded sequence x.
Return type:: ndarray

static backend_log_density_from_params(vals, log_vals, k, theta, engine)[source]

Engine-neutral gamma log-density from explicit parameters.

Parameters:

vals (Any)
log_vals (Any)
k (Any)
theta (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Gamma parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GammaDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Gamma log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Gamma sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

to_fisher(**kwargs)[source]: Return this distribution’s own Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

skewness()[source]

Skewness 2/sqrt(k).

Return type:: float

kurtosis()[source]

Excess kurtosis 6/k.

Return type:: float

mode()[source]

Mode (k-1)*theta for k>=1, else 0.

Return type:: float

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional seed for the sampler’s random state.
Returns:: A configured GammaSampler.
Return type:: GammaSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s shape.

Parameters:: pseudo_count (float | None) – Optional smoothing count applied to the current distribution moments.
Returns:: A GammaEstimator.
Return type:: GammaEstimator

dist_to_encoder()[source]

Return an encoder for iid Gamma observations.

Return type:: GammaDataEncoder

class GammaEstimator(pseudo_count=(0.0, 0.0), suff_stat=(1.0, 0.0), threshold=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate Gamma shape and scale parameters from sufficient statistics.

Parameters:

pseudo_count (float | tuple[float, float])
suff_stat (tuple[float, float])
threshold (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: GammaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a Gamma distribution from aggregated sufficient statistics.

The tuple is interpreted as (count, sum, sum_of_logs).

Parameters:

nobs (float | None) – Unused; accepted for the ParameterEstimator interface.
suff_stat (tuple[float, float, float]) – Aggregated Gamma sufficient statistics.

Returns:

A fitted Gamma distribution.

Return type:

GammaDistribution

static estimate_shape(avg_sum, avg_sum_of_logs, threshold)[source]

Estimates the shape parameter of GammaDistribution.

Parameters:

avg_sum (float) – Weighted sum of gamma observations.
avg_sum_of_logs (float) – Weighted log sum of gamma observations.
threshold (float) – Threshold used for assessing convergence of shape estimation.

Returns:

Estimate of shape parameter ‘k’.

Return type:

class GaussianDistribution(mu, sigma2, name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Univariate Gaussian distribution.

Parameters:

mu (float)
sigma2 (float)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for generated Gaussian density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Gaussian distribution.

static exp_family_sufficient_statistics(x, engine)[source]

Return Gaussian sufficient statistics for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Gaussian sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Gaussian natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Gaussian log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

set_prior(prior)[source]

Attach a parameter prior and precompute conjugate-prior expectations.

With a NormalGamma(mu0, lam, a, b) prior over (mu, tau=1/sigma2) this caches the variational expected natural parameters [ea, eb, e1, e2] so that expected_log_density(x) = x*(e1 + x*e2) - ea + eb (the VB E-step term). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | mu, tau)] under the NormalGamma prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (float)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Density of Gaussian distribution at observation x.

See log_density() for details.

Parameters:: x (float) – Real-valued observation of Gaussian.
Returns:: Density of Gaussian at x.
Return type:: float

log_density(x)[source]

Log-density of Gaussian distribution at observation x.

Log-density of Gaussian with mean mu and variance sigma2 given by,: log(f(x;mu, sigma2)) = -0.5*log(2*pi*sigma2) - 0.5*(x-mu)^2/sigma2, for real-valued x.

Parameters:: x (float) – Real-valued observation of Gaussian.
Returns:: Log-density at observation x.
Return type:: float

seq_ld_lambda()[source]

Return vectorized log-density callables for encoded data.

Return type:: list[Callable]

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (np.ndarray) – Numpy array of floats.
Returns:: Numpy array of log-density (float) of len(x).
Return type:: ndarray

static backend_log_density_from_params(x, mu, sigma2, engine)[source]

Engine-neutral Gaussian log-density from explicit parameters.

Parameters:

x (Any)
mu (Any)
sigma2 (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

gradient_log_prior(priors, prior_strength, torch, engine)[source]

Distribution-owned MAP prior contribution for Gaussian parameters.

Parameters:

priors (Any)
prior_strength (float)
torch (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Gaussian parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GaussianDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Gaussian log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Gaussian sufficient statistics using engine-resident arrays.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

to_fisher(**kwargs)[source]: Return the Gaussian’s own Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy 0.5*log(2*pi*e*sigma2).

Return type:: float

skewness()[source]

Skewness (0).

Return type:: float

kurtosis()[source]

Excess kurtosis (0).

Return type:: float

mode()[source]

Mode (= the mean mu).

Return type:: float

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional seed for the sampler’s random state.
Returns:: A configured GaussianSampler.
Return type:: GaussianSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s shape.

Parameters:: pseudo_count (float | None) – Optional smoothing count applied to the current mean and variance.
Returns:: A GaussianEstimator.
Return type:: GaussianEstimator

dist_to_encoder()[source]

Return an encoder for iid scalar Gaussian observations.

Return type:: GaussianDataEncoder

class GaussianEstimator(pseudo_count=(None, None), suff_stat=(None, None), name=None, keys=None, prior=None, min_covar=None, compensated=False)[source]

Bases: ParameterEstimator

Estimate Gaussian mean and variance from accumulated sufficient statistics.

The variance is formed from shift-anchored statistics whenever the accumulated statistics carry that payload (see GaussianAccumulator), which makes the fit shift-equivariant at any data offset. Statistics that arrive WITHOUT that payload cannot be corrected here – the information cancellation destroyed is not in them any more – and that is a reachable state, not a theoretical one: an engine kernel stacks the declared (sum, sum2, count, count2) moments directly, so optimize(x + 1.7e9, GaussianEstimator(), engine=NUMPY_ENGINE) on sd ~2 data returned a variance 7.9e9 times too large. estimate now WARNS in that case rather than returning it silently; the remedy is to accumulate through GaussianAccumulator (which anchors automatically) or to subtract a constant origin from the data before fitting.

ON GENUINELY DEGENERATE (zero-spread) DATA the equivariance guarantee above does not apply, and cannot: the true variance of a point mass is 0 and the true density is a Dirac delta, so the floor returned is a convention, not a measurement, and no offset makes one convention more correct than another. This estimator’s convention is ratio * mu**2 (scale-relative, so it is a UV of noise on 10 uV data and 2.9e10 on data at the Unix epoch); its sibling DiagonalGaussianEstimator uses a flat 1e-8 regardless of magnitude – the two disagree by up to 18 orders of magnitude on identical degenerate input (T1-05, campaign four), and neither is “right”. A caller that needs a specific, fixed value on this exact input – not just a safeguard against it – should pass min_covar=<value> explicitly, which both estimators honor exactly.

Parameters:

pseudo_count (float | tuple[float | None, float | None])
suff_stat (tuple[float | None, float | None])
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)
min_covar (float | None)
compensated (bool)

accumulator_factory()[source]

Return GaussianAccumulatorFactory with name and keys passed.

Return type:: GaussianAccumulatorFactory

model_log_density(model)[source]

Log-density of the model parameters under the NormalGamma prior (ELBO global term).

The prior is over (mu, tau=1/sigma2), so the model’s (mu, sigma2) is mapped accordingly.

Parameters:: model (GaussianDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a Gaussian distribution from aggregated sufficient statistics.

The tuple is interpreted as (sum_x, sum_x2, count_for_mean, count_for_variance). Optional pseudo-counts smooth the corresponding mean and variance estimates.

Parameters:

nobs (float | None) – Unused; accepted for the ParameterEstimator interface.
suff_stat (tuple[float, float, float, float]) – Aggregated Gaussian sufficient statistics.

Returns:

A fitted Gaussian distribution.

Return type:

GaussianDistribution

class InverseGammaDistribution(alpha, beta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Inverse-gamma distribution with shape alpha > 0 and rate beta > 0 on x > 0.

Parameters:

alpha (float)
beta (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated inverse-gamma kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for inverse-gamma distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row (count, 1/x, -log x) sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)[source]

Return inverse-gamma sufficient statistics T(x) = (log x, 1/x).

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return inverse-gamma natural parameters eta = (-(alpha + 1), -beta).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return inverse-gamma log partition A = lgamma(alpha) - alpha * log(beta).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_from_natural(eta)[source]

Return the inverse-gamma with natural parameters eta = (-(alpha + 1), -beta).

Parameters:: eta (Any)
Return type:: InverseGammaDistribution

static backend_log_density_from_params(log_x, inv_x, alpha, beta, log_const, engine)[source]

Engine-neutral inverse-gamma log-density from explicit parameters (linear in log x and 1/x).

Parameters:

log_x (Any)
inv_x (Any)
alpha (Any)
beta (Any)
log_const (Any)
engine (Any)

Return type:

get_parameters()[source]

Return the (shape alpha, rate beta) pair (so this can serve as a conjugate prior).

Return type:: tuple[float, float]

cross_entropy(dist)[source]

Cross entropy -E_self[log dist(x)] for an inverse-gamma argument (closed form).

Parameters:: dist (InverseGammaDistribution)
Return type:: float

entropy()[source]

Returns the differential entropy in nats.

Return type:: float

mean()[source]

Mean E[X] = beta / (alpha - 1) for alpha > 1, else inf (the mean integral diverges).

Return type:: float

variance()[source]

Variance beta^2 / ((alpha-1)^2 (alpha-2)) for alpha > 2, else inf.

Return type:: float

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation (or -inf off support).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded (log x, 1/x) observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[InverseGammaDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of inverse-gamma log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) = Q(alpha, beta/x) (0 for x <= 0).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: InverseGammaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: InverseGammaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: InverseGammaDataEncoder

class InverseGammaEstimator(pseudo_count=None, suff_stat=None, threshold=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the inverse-gamma shape and rate.

Fits the gamma distribution to the reciprocals y = 1/x (y ~ Gamma(alpha, 1/beta)) by the standard log-mean / mean shape equation, then maps back to (alpha, beta) = (k, 1/theta).

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
threshold (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for inverse-gamma statistics.

Return type:: InverseGammaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate shape and rate from reciprocal and log-reciprocal statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

InverseGammaDistribution

class InverseGaussianDistribution(mu, lam, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Inverse Gaussian (Wald) distribution with mean mu > 0 and shape lam > 0 on x > 0.

Parameters:

mu (float)
lam (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated inverse-Gaussian kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for inverse Gaussian distributions.

static exp_family_sufficient_statistics(x, engine)[source]

Return the (x, 1/x) sufficient statistics for generated scoring.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the (-lam/(2*mu^2), -lam/2) natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the inverse Gaussian log partition -0.5*log(lam) - lam/mu.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return the support base measure -0.5*log(2*pi) - 1.5*log(x) (or -inf off support).

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row (count, x, 1/x) sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation (or -inf off support).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (Tuple[ndarray, ndarray, ndarray]) – Tuple of observations, reciprocals, and log values produced by the InverseGaussianDataEncoder.
Returns:: Numpy array of log-density values, with -inf entries off the positive support.
Return type:: ndarray

static backend_log_density_from_params(vals, inv_vals, log_vals, mu, lam, engine)[source]

Engine-neutral inverse Gaussian log-density from explicit parameters.

Parameters:

vals (Any)
inv_vals (Any)
log_vals (Any)
mu (Any)
lam (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[InverseGaussianDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of inverse Gaussian log densities.

Parameters:

x (tuple[Any, Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (Wald, via scipy invgauss).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] = mu.

Return type:: float

variance()[source]

Variance Var[X] = mu^3 / lam.

Return type:: float

entropy()[source]

Differential entropy in nats (closed form).

H = -E[log f(X)] = 1/2 log(2 pi e / lam) + 3/2 E[log X] (the quadratic term integrates to exactly 1/2 since E[(X - mu)^2 / X] = mu^2 / lam), with E[log X] = log(mu) - e^{2z} E_1(2z) at z = lam / mu – the order-derivative identity for the Bessel K_{1/2} under the GIG representation, E_1 the exponential integral. The scaled product e^x E_1(x) switches to its asymptotic series where exp overflows.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: InverseGaussianSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (Optional[float]) – Re-weight the sufficient statistics of this instance toward its own moments when not None (a simple ridge toward the current parameters).
Returns:: InverseGaussianEstimator object.
Return type:: InverseGaussianEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: InverseGaussianDataEncoder

class InverseGaussianEstimator(pseudo_count=None, suff_stat=None, min_param=_MIN_IG_PARAM, max_param=_MAX_IG_PARAM, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the inverse Gaussian mean and shape.

The MLE is closed form: mu = mean(x) and 1/lam = mean(1/x) - 1/mu.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_param (float)
max_param (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for inverse-Gaussian statistics.

Return type:: InverseGaussianAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate mean and shape from count, sum, and reciprocal sum.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

InverseGaussianDistribution

class GeometricDistribution(p, name=None, keys=None, prior=None)[source]

Bases: CachedParameterLaw, SequenceEncodableProbabilityDistribution

Geometric distribution on {1, 2, ...} with success probability p.

Parameters:

p (float)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for generated Geometric density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Geometric distribution.

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Geometric sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)[source]

Return Geometric sufficient statistic T(x) = (x,) (support x = 1, 2, …).

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Geometric natural parameter eta = log(1 - p).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Geometric log partition A = log(1 - p) - log(p).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_from_natural(eta)[source]

Return the Geometric with natural parameter eta = log(1 - p).

Parameters:: eta (Any)
Return type:: GeometricDistribution

set_prior(prior)[source]

Attach a Beta parameter prior and precompute conjugate-prior expectations.

With a Beta(a, b) prior on the success probability p this caches the digamma terms (digamma(a), digamma(b), digamma(a+b)) so that expected_log_density evaluates the variational Bayes expectation E_q[log p(x | p)] via E[log p] = digamma(a) - digamma(a+b) and E[log(1-p)] = digamma(b) - digamma(a+b). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | p)] under the Beta prior.

Uses the cached digamma expectations of log p and log(1-p); falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (int)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Density of geometric distribution evaluated at x.

P(x=k) = (k-1)*log(1-p) + log(p), for x = 1,2,…, else 0.0.

Parameters:: x (int) – Observed geometric value (1,2,3,….).
Returns:: Density of geometric distribution evaluated at x.
Return type:: float

log_density(x)[source]

Log-density of geometric distribution evaluated at x.

See density() for details.

Parameters:: x (int) – Must be natural number (1,2,3,….).
Returns:: Log-density of geometric distribution evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized log-density evaluated on sequence encoded x.

Parameters:: x (int) – Numpy array of non-negative integers.
Returns:: Numpy array of log-density evaluated at each encoded observation value x.
Return type:: ndarray

static backend_log_density_from_params(x, p, engine)[source]

Engine-neutral geometric log-density from explicit parameters.

Parameters:

x (Any)
p (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked geometric parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GeometricDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of geometric log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

to_fisher(**kwargs)[source]: Return the Geometric’s count-family Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x) = 1 - (1-p)^floor(x), support x >= 1.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q), support >= 1 (via scipy geom).

Parameters:: q (float)
Return type:: float

entropy()[source]

Shannon entropy (-(1-p) log(1-p) - p log p) / p (nats).

Return type:: float

mode()[source]

Mode (1 – the minimum of the decreasing pmf).

Return type:: float

sampler(seed=None)[source]

Create a sampler from this geometric distribution.

Parameters:: seed (Optional[int]) – Used to set seed on random number generator.
Returns:: GeometricSampler configured from this distribution.
Return type:: GeometricSampler

estimator(pseudo_count=None)[source]

Create an estimator for a geometric distribution.

Parameters:: pseudo_count (Optional[float]) – Regularize empirical summary statistics.
Returns:: GeometricEstimator configured with this distribution’s prior and name.
Return type:: GeometricEstimator

dist_to_encoder()[source]

Return the encoder for geometric observations.

Return type:: GeometricDataEncoder

enumerator()[source]

Returns GeometricEnumerator iterating the support {1, 2, …} in descending probability order.

Return type:: GeometricEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index directly from the geometric tail formula.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over bounded geometric prefixes.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over two bounded geometric prefixes.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class GeometricEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate Geometric success probabilities from accumulated sufficient statistics.

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Create a geometric accumulator factory with this estimator’s name and keys.

Return type:: GeometricAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s success probability under the Beta prior (ELBO global term).

Parameters:: model (GeometricDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a geometric distribution from weighted count and sum statistics.

nobs is accepted for estimator API consistency but is not used. suff_stat is (count, sum). Without a pseudo-count, the estimate is p = count / sum; with a pseudo-count, the empirical statistic is shrunk toward the estimator’s prior statistic when available.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

GeometricDistribution

class GeometricEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate geometric support values in descending probability order.

Parameters:: dist (GeometricDistribution)

class GumbelDistribution(loc=0.0, scale=1.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gumbel (extreme value type I) distribution with location loc and scale beta > 0.

Parameters:

loc (float)
scale (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Gumbel kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Gumbel distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Gumbel sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, loc, scale, engine)[source]

Engine-neutral Gumbel log-density from explicit parameters.

Parameters:

x (Any)
loc (Any)
scale (Any)
engine (Any)

Return type:

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Gumbel parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GumbelDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Gumbel log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Gumbel sufficient statistics using engine-resident arrays.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] = loc + scale * euler_gamma.

Return type:: float

variance()[source]

Variance Var[X] = pi^2 scale^2 / 6.

Return type:: float

entropy()[source]

Differential entropy log(scale) + euler_gamma + 1.

Return type:: float

skewness()[source]

Skewness 12*sqrt(6)*zeta(3)/pi^3.

Return type:: float

kurtosis()[source]

Excess kurtosis (12/5).

Return type:: float

mode()[source]

Mode (= the location loc).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: GumbelSampler

estimator(pseudo_count=None)[source]

Return a moment estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: GumbelEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: GumbelDataEncoder

class GumbelEstimator(pseudo_count=None, suff_stat=None, min_scale=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Moment estimator for the Gumbel location and scale.

Inverts the Gumbel moments: beta = sqrt(6 * var) / pi and loc = mean - beta * gamma where gamma is the Euler-Mascheroni constant.

The variance moment is formed from shift-anchored statistics whenever the accumulated sufficient statistics carry that payload (see GumbelAccumulator), which makes the fit SHIFT-EQUIVARIANT: estimating on x + c returns loc + c with scale unchanged, for any constant c the data can carry – epoch seconds (~1.7e9) and 2**31 included. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones that arrived already reduced from an engine kernel or an older serialization – the historical raw path is used bit-identically, and estimate warns rather than returning a scale it cannot stand behind.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_scale (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Gumbel moment statistics.

Return type:: GumbelAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location and scale from weighted moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

GumbelDistribution

class HalfNormalDistribution(sigma, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Half-normal distribution with scale sigma > 0 on x >= 0.

Parameters:

sigma (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated half-normal kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for half-normal distributions.

static exp_family_sufficient_statistics(x, engine)[source]

Return the (x**2,) sufficient statistic for generated scoring.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the (-1/(2*sigma^2),) natural parameter for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the half-normal log partition log(sigma).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return the support base measure 0.5*log(2/pi) (or -inf off support x >= 0).

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row (count, x**2) sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation (or -inf off support).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (Tuple[ndarray, ndarray]) – Tuple of observations and squared observations produced by the HalfNormalDataEncoder.
Returns:: Numpy array of log-density values, with -inf entries off the non-negative support.
Return type:: ndarray

static backend_log_density_from_params(vals, sq_vals, sigma, engine)[source]

Engine-neutral half-normal log-density from explicit parameters.

Parameters:

vals (Any)
sq_vals (Any)
sigma (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[HalfNormalDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of half-normal log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (0 for x < 0).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] = sigma * sqrt(2/pi).

Return type:: float

variance()[source]

Variance Var[X] = sigma^2 (1 - 2/pi).

Return type:: float

entropy()[source]

Differential entropy 0.5*log(pi*sigma^2/2) + 1/2.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: HalfNormalSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (Optional[float]) – Re-weight the second moment toward this instance’s own E[x**2] = sigma**2 when not None (a simple ridge toward the current parameter).
Returns:: HalfNormalEstimator object.
Return type:: HalfNormalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: HalfNormalDataEncoder

class HalfNormalEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the half-normal scale: sigma = sqrt(mean(x**2)).

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for half-normal statistics.

Return type:: HalfNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the half-normal scale from weighted squared observations.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

HalfNormalDistribution

class NegativeBinomialDistribution(r, p, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Negative binomial distribution over non-negative integer counts.

Parameters:

r (float)
p (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated negative-binomial kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for negative binomial distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row negative-binomial sufficient statistics in accumulator order.

The accumulator’s NegativeBinomialAccumulator.value() returns (count, sum, histogram); the third row stat carries the per-row counts so the declaration’s kind="histogram" reducer can fold them into the weighted count histogram the dispersion (r) solve needs.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)[source]

Return the NegativeBinomial sufficient statistic T(x) = (x,) (r fixed).

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the NegativeBinomial natural parameter eta = log(1 - p) (r fixed).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the NegativeBinomial log partition A = -r * log(p) (r fixed).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure_from_params(x, params, engine)[source]

Return the NegativeBinomial base measure log h(x) = lgamma(x+r) - lgamma(r) - log(x!).

The base measure carries the binomial-coefficient term and depends on the fixed shape r; invalid (non-integer / negative) counts are mapped to -inf.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (int)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (int)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

static backend_log_density_from_params(vals, log_fact, r, p, engine)[source]

Engine-neutral negative-binomial log-density from explicit parameters.

Parameters:

vals (Any)
log_fact (Any)
r (Any)
p (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked negative-binomial parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[NegativeBinomialDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of negative-binomial log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

to_fisher(**kwargs)[source]: Return the NegativeBinomial’s count-family Fisher view.

mean()[source]

Mean E[X] (failures before r successes): r(1-p)/p.

Return type:: float

variance()[source]

Variance Var[X]: r(1-p)/p^2.

Return type:: float

entropy()[source]

Shannon entropy in nats, by exact summation of the standard series.

The negative-binomial entropy -sum_k p_k log p_k has no closed form (Johnson, Kemp & Kotz, Univariate Discrete Distributions, ch. 5). The series is summed over the support up to this distribution’s own quantile at 1 - 1e-16 (plus a safety margin), beyond which the tail mass is far below double rounding – the same effective-support truncation PoissonDistribution.entropy() uses, but driven by the exact CDF (via betainc) rather than a Gaussian-tail heuristic, since the negative binomial can be heavy-tailed.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x) = I_p(r, floor(x)+1).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) (via scipy nbinom).

Parameters:: q (float)
Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: NegativeBinomialSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: NegativeBinomialEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: NegativeBinomialDataEncoder

enumerator()[source]

Return an enumerator over the distribution support when available.

Return type:: NegativeBinomialEnumerator

class NegativeBinomialEstimator(r=1.0, pseudo_count=None, suff_stat=None, estimate_r=True, threshold=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate r and p for a negative binomial distribution.

By default the dispersion r is recovered by a 1-D solve of the digamma score equation (p profiled out), then p follows in closed form. Pass estimate_r=False to hold r fixed at the constructor value (the historical geometric/fixed-shape M-step). The r argument is the initial value / fallback when estimate_r=True.

Parameters:

r (float)
pseudo_count (float | None)
suff_stat (float | None)
estimate_r (bool)
threshold (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for negative-binomial statistics.

Return type:: NegativeBinomialAccumulatorFactory

resident_accumulation_supported()[source]

Dispersion estimation needs the full count histogram, not fixed-width resident stats.

Return type:: bool

static estimate_dispersion(histogram, r_init, threshold)[source]

Solve the negative-binomial dispersion MLE from a weighted count histogram.

With p profiled to its MLE p = r / (r + xbar), the score for r is

g(r) = sum_k h(k) [digamma(k + r) - digamma(r)] - N * log(1 + xbar / r),

which is strictly decreasing and crosses zero exactly when the data are over-dispersed (sample variance > mean). Under equi/under-dispersion the MLE runs off to the Poisson limit, so r is capped at _MAX_NB_SHAPE.

Parameters:

histogram (dict[int, float])
r_init (float)
threshold (float)

Return type:

estimate(nobs, suff_stat)[source]

Estimate r and p from weighted count statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, dict[int, float]])

Return type:

NegativeBinomialDistribution

class NegativeBinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate the infinite support in descending probability order.

Parameters:: dist (NegativeBinomialDistribution)

class ParetoDistribution(xm, alpha, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Pareto type-I distribution with scale xm > 0 and shape alpha > 0.

Parameters:

xm (float)
alpha (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Pareto kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Pareto distributions.

static exp_family_sufficient_statistics(x, engine)[source]

Return the Pareto sufficient statistic T(x) = (log x,) (scale xm fixed).

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the Pareto natural parameter eta = -alpha (scale xm fixed).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the Pareto log partition A = -log(alpha) - alpha * log(xm).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure_from_params(x, params, engine)[source]

Return the Pareto base measure log h(x) = -log(x) on [xm, inf) (-inf below xm).

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

static backend_log_density_from_params(vals, log_vals, xm, alpha, engine)[source]

Engine-neutral Pareto log-density from explicit parameters.

Parameters:

vals (Any)
log_vals (Any)
xm (Any)
alpha (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Pareto parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[ParetoDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Pareto log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Pareto sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean alpha*xm/(alpha-1) for alpha > 1, else inf.

Return type:: float

variance()[source]

Variance xm^2 alpha / ((alpha-1)^2 (alpha-2)) for alpha > 2, else inf.

Return type:: float

entropy()[source]

Differential entropy log(xm/alpha) + 1/alpha + 1.

Return type:: float

mode()[source]

Mode (the scale xm).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: ParetoSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: ParetoEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: ParetoDataEncoder

class ParetoEstimator(pseudo_count=None, suff_stat=None, min_denom=1.0e-12, name=None, keys=None)[source]

Bases: ParameterEstimator

MLE estimator for Pareto scale and shape.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_denom (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Pareto sufficient statistics.

Return type:: ParetoAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Pareto scale and shape from support and log-sum statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

ParetoDistribution

class RayleighDistribution(sigma, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Rayleigh distribution with scale sigma > 0.

Parameters:

sigma (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Rayleigh kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Rayleigh distributions.

static exp_family_sufficient_statistics(x, engine)[source]

Return Rayleigh sufficient statistics for generated scoring.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Rayleigh sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Rayleigh natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Rayleigh log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return Rayleigh support/base measure for generated scoring.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray, ndarray])
Return type:: ndarray

static backend_log_density_from_params(vals, vals2, log_vals, sigma, engine)[source]

Engine-neutral Rayleigh log-density from explicit parameters.

Parameters:

vals (Any)
vals2 (Any)
log_vals (Any)
sigma (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Rayleigh parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[RayleighDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Rayleigh log densities.

Parameters:

x (tuple[Any, Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy 1 + log(sigma/sqrt(2)) + gamma/2.

Return type:: float

skewness()[source]

Skewness 2*sqrt(pi)(pi-3)/(4-pi)^1.5.

Return type:: float

kurtosis()[source]

Excess kurtosis -(6pi^2-24pi+16)/(4-pi)^2.

Return type:: float

mode()[source]

Mode (sigma).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: RayleighSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: RayleighEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: RayleighDataEncoder

class RayleighEstimator(pseudo_count=None, suff_stat=None, min_sigma=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form MLE estimator for Rayleigh scale.

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
min_sigma (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Rayleigh sufficient statistics.

Return type:: RayleighAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the Rayleigh scale from weighted squared observations.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

RayleighDistribution

class StudentTDistribution(df, loc=0.0, scale=1.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Student’s t distribution with degrees of freedom df, location loc, and scale > 0.

Parameters:

df (float)
loc (float)
scale (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Student-t kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Student-t distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Student-t sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

static backend_log_density_from_params(x, df, loc, scale, engine)[source]

Engine-neutral Student-t log-density from explicit parameters.

Parameters:

x (Any)
df (Any)
loc (Any)
scale (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Student-t parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[StudentTDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Student-t log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean (loc) for df > 1, else inf (undefined).

Return type:: float

variance()[source]

Variance scale^2 * df/(df-2) for df > 2, else inf.

Return type:: float

entropy()[source]

Differential entropy log(scale) + (df+1)/2 [psi((df+1)/2) - psi(df/2)] + log(sqrt(df) B(df/2, 1/2)).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: StudentTSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: StudentTEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: StudentTDataEncoder

class StudentTEstimator(df=5.0, pseudo_count=None, suff_stat=None, min_scale=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Moment-style fixed-df estimator for Student’s t location and scale.

The exact MLE has no simple closed-form update. This estimator keeps df fixed and uses weighted moments, while generic gradient optimizers such as mixle.inference.gradient_fit.fit_mle / fit_map can fit all three parameters through distribution-owned backend math.

The variance moment is formed from shift-anchored statistics whenever the accumulated sufficient statistics carry that payload (see StudentTAccumulator), which makes the fit SHIFT-EQUIVARIANT: estimating on x + c returns loc + c with scale unchanged, for any constant c the data can carry – epoch seconds (~1.7e9) and 2**31 included. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones that arrived already reduced from an engine kernel or an older serialization – the historical raw path is used bit-identically, and estimate warns rather than returning a scale it cannot stand behind.

min_scale (default 1e-8) is an absolute floor on the returned scale; it exists for genuinely constant data, and a fit that lands on it is reporting no resolvable spread.

Parameters:

df (float)
pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_scale (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for fixed-df Student-t moments.

Return type:: StudentTAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location and scale while keeping degrees of freedom fixed.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

StudentTDistribution

class UniformDistribution(low, high, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Continuous uniform distribution on [low, high].

Parameters:

low (float)
high (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated uniform kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for uniform distributions.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

static backend_log_density_from_params(x, low, high, engine)[source]

Engine-neutral uniform log-density from explicit parameters.

Parameters:

x (Any)
low (Any)
high (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked uniform parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[UniformDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of uniform log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Uniform sufficient statistics using engine-resident arrays.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy log(high - low).

Return type:: float

skewness()[source]

Skewness (0).

Return type:: float

kurtosis()[source]

Excess kurtosis (-6/5).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: UniformSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: UniformEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UniformDataEncoder

class UniformEstimator(pseudo_count=None, suff_stat=None, min_width=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

MLE estimator for uniform support endpoints.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_width (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for uniform support statistics.

Return type:: UniformAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate support endpoints from observed weighted bounds.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

UniformDistribution

class VonMisesDistribution(mu, kappa, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Von Mises distribution on the circle with mean direction mu and concentration kappa >= 0.

Observations are angles in radians, interpreted modulo 2*pi: log_density(x) equals log_density(x + 2*pi*k) for every integer k, and the density normalizes over one period, not over the real line. Scores are therefore comparable only to other circular models – see the module docstring for why a wrapped fit of real-line data can spuriously out-score every real-line family.

Parameters:

mu (float)
kappa (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated von Mises kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for von Mises distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row (count, cos, sin) sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)[source]

Return von Mises sufficient statistics T(x) = (cos x, sin x).

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return von Mises natural parameters eta = (kappa cos mu, kappa sin mu).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return von Mises log partition A = log(2 pi I_0(kappa)) = -log_const.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_from_natural(eta)[source]

Return the von Mises with natural parameters eta = (kappa cos mu, kappa sin mu).

Parameters:: eta (Any)
Return type:: VonMisesDistribution

static backend_log_density_from_params(cos_t, sin_t, eta1, eta2, log_const, engine)[source]

Engine-neutral von Mises log-density from natural parameters (linear in cos/sin).

Parameters:

cos_t (Any)
sin_t (Any)
eta1 (Any)
eta2 (Any)
log_const (Any)
engine (Any)

Return type:

density(x)[source]

Return the probability density at a single angle.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single angle (radians), wrapping x modulo 2*pi.

Any finite real is accepted; values outside (-pi, pi] are folded onto the circle, so this is the density of x mod 2*pi, normalized over one period only.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded (cos, sin) observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked natural parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[VonMisesDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of von Mises log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing angles from this distribution.

Parameters:: seed (int | None)
Return type:: VonMisesSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: VonMisesEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: VonMisesDataEncoder

class WrappedCauchyDistribution(mu, rho, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Wrapped Cauchy distribution with mean direction mu and concentration rho in [0, 1).

Parameters:

mu (float)
rho (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at a single angle (radians).

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single angle (radians).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded (cos, sin) observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated wrapped-Cauchy kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for wrapped Cauchy distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row circular moments in accumulator order (sum_cos, sum_sin, count).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(cos_t, sin_t, cos_mu, sin_mu, rho, engine)[source]

Engine-neutral wrapped-Cauchy log-density from pre-computed observation/parameter trig.

Parameters:

cos_t (Any)
sin_t (Any)
cos_mu (Any)
sin_mu (Any)
rho (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded (cos, sin) data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Stacked wrapped-Cauchy parameters (trig computed host-side) for a homogeneous mixture kernel.

Parameters:

dists (Sequence[WrappedCauchyDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of wrapped-Cauchy log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Stacked circular moments (sum_cos, sum_sin, count) using engine-resident arrays.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing angles from this distribution.

Parameters:: seed (int | None)
Return type:: WrappedCauchySampler

estimator(pseudo_count=None)[source]

Return a closed-form (mean-resultant) estimator for mu and rho.

Parameters:: pseudo_count (float | None)
Return type:: WrappedCauchyEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (cos/sin of the angle).

Return type:: WrappedCauchyDataEncoder

class WrappedCauchyEstimator(rho_max=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate mu and rho from the mean resultant (the first trigonometric moment).

Parameters:

rho_max (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for circular-resultant statistics.

Return type:: WrappedCauchyAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate mean direction and concentration from the mean resultant.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

WrappedCauchyDistribution

exception WrappedCauchyFitError[source]

Bases: RuntimeError

Raised when circular moments have no finite wrapped-Cauchy fit.

class ProjectedNormalDistribution(mu_x, mu_y, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Isotropic projected normal PN(mu) on the circle, mu = (mu_x, mu_y).

Parameters:

mu_x (float)
mu_y (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at a single angle (radians).

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single angle (radians).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for sequence-encoded (cos, sin) observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated projected-normal kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for projected normal distributions.

classmethod backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row E-step stats (E[r] cos, E[r] sin, 1) under the CURRENT estimate’s parameters.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

classmethod backend_log_density_from_params(cos_t, sin_t, mu_x, mu_y, engine)[source]

Engine-neutral projected-normal log-density from (cos, sin) and the mean vector.

Parameters:

cos_t (Any)
sin_t (Any)
mu_x (Any)
mu_y (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded (cos, sin) data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Stacked projected-normal mean vectors for a homogeneous mixture kernel.

Parameters:

dists (Sequence[ProjectedNormalDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of projected-normal log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Stacked E-step resultants (sum r cos, sum r sin, count) under per-component parameters.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler that draws N(mu, I_2) and returns the angle.

Parameters:: seed (int | None)
Return type:: ProjectedNormalSampler

estimator(pseudo_count=None)[source]

Return an EM (latent-radius) estimator for mu.

Parameters:: pseudo_count (float | None)
Return type:: ProjectedNormalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (cos/sin of the angle).

Return type:: ProjectedNormalDataEncoder

class ProjectedNormalEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

EM estimator: mu = mean(E[r|theta] u(theta)) (one M-step per accumulated E-step).

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for projected-normal EM statistics.

Return type:: ProjectedNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the projected-normal mean vector from EM sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

ProjectedNormalDistribution

exception ProjectedNormalFitError[source]

Bases: RuntimeError

Raised when projected-normal EM statistics do not define a finite fit.

class WrappedNormalDistribution(mu, sigma2, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Wrapped normal distribution with mean direction mu and wrapped variance sigma2 > 0.

Parameters:

mu (float)
sigma2 (float)
name (str | None)
keys (str | None)

property K: int: Number of wraps summed on each side of the window.

density(x)[source]

Return the probability density at a single angle (radians).

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single angle (radians).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded array of angles.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated wrapped-normal kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for wrapped normal distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row circular moments (sum_cos, sum_sin, count) — uses the engine trig tier.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density: the (2K+1)-branch wrapped logsumexp on engine ops.

Parameters:

x (Any)
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler that wraps N(mu, sigma2) onto the circle.

Parameters:: seed (int | None)
Return type:: WrappedNormalSampler

estimator(pseudo_count=None)[source]

Return a closed-form (mean-resultant) estimator for mu and sigma2.

Parameters:: pseudo_count (float | None)
Return type:: WrappedNormalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (the angle itself).

Return type:: WrappedNormalDataEncoder

class WrappedNormalEstimator(sigma2_max=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate mu and sigma2 from the mean resultant (rho = exp(-sigma2/2)).

Parameters:

sigma2_max (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for circular-resultant statistics.

Return type:: WrappedNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate mean direction and variance from the mean resultant.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

WrappedNormalDistribution

exception WrappedNormalFitError[source]

Bases: RuntimeError

Raised when circular moments have no finite wrapped-normal fit.

class GeneralizedGaussianDistribution(mu, alpha, beta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Generalized Gaussian (exponential power) with location mu, scale alpha and shape beta.

Parameters:

mu (float)
alpha (float)
beta (float)
name (str | None)
keys (str | None)

classmethod compute_declaration()[source]: Return the structured compute declaration for generalized Gaussian distributions.

static backend_log_density_from_params(x, mu, alpha, beta, engine)[source]

Engine-neutral generalized-Gaussian log-density: log_norm - (abs(x-mu)/alpha)**beta.

Parameters:

x (Any)
mu (Any)
alpha (Any)
beta (Any)
engine (Any)

Return type:

density(x)[source]

Return the probability density at x.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at x.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded array of observations.

Parameters:: x (ndarray)
Return type:: ndarray

cdf(x)[source]

Cumulative distribution function P(X <= x).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean (the location mu).

Return type:: float

variance()[source]

Variance alpha^2 Gamma(3/beta) / Gamma(1/beta).

Return type:: float

skewness()[source]

Skewness (0 – the law is symmetric).

Return type:: float

kurtosis()[source]

Excess kurtosis Gamma(5/beta)Gamma(1/beta)/Gamma(3/beta)^2 - 3.

Return type:: float

entropy()[source]

Differential entropy 1/beta - log(beta / (2 alpha Gamma(1/beta))).

Return type:: float

sampler(seed=None)[source]

Return a sampler (Gamma magnitude with a random sign).

Parameters:: seed (int | None)
Return type:: GeneralizedGaussianSampler

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for mu, alpha, beta.

Parameters:: pseudo_count (float | None)
Return type:: GeneralizedGaussianEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (the raw value).

Return type:: GeneralizedGaussianDataEncoder

class GeneralizedGaussianEstimator(pseudo_count=None, suff_stat=None, beta_bounds=(0.25, 50.0), name=None, keys=None, prior_central=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator: mu = mean, beta from excess kurtosis, alpha from variance.

The reduced moments are formed about a reference point rather than about zero whenever the accumulated statistics carry a shift-anchored payload (see GeneralizedGaussianAccumulator), which makes the fit shift-equivariant: estimate on x + c returns mu + c with alpha and beta unchanged. With a plain raw tuple – statistics restored from an older serialization, or a hand-built one – the historical raw path is used unchanged.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float, float, float] | None)
beta_bounds (tuple[float, float])
name (str | None)
keys (str | None)
prior_central (tuple[float, float, float, float] | None)

accumulator_factory()[source]

Return an accumulator factory for generalized-Gaussian raw moments.

Return type:: GeneralizedGaussianAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location, scale, and shape from weighted raw moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float, float, float])

Return type:

GeneralizedGaussianDistribution

class NakagamiDistribution(m, omega, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Nakagami distribution with shape m >= 1/2 and spread omega = E[X^2] > 0.

Parameters:

m (float)
omega (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at x.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at x, including the exact limit at zero.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded array of observations.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated Nakagami kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Nakagami distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row Nakagami power sums in accumulator order (count, sum x^2, sum x^4).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, m, omega, engine)[source]

Engine-neutral Nakagami log-density with the exact limit at zero.

Parameters:

x (Any)
m (Any)
omega (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Stacked Nakagami parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[NakagamiDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Nakagami log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Stacked Nakagami power sums (count, sum x^2, sum x^4) using engine-resident arrays.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) = P(m, m x^2 / omega) (0 for x <= 0).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean (Gamma(m+1/2)/Gamma(m)) sqrt(omega/m).

Return type:: float

variance()[source]

Variance omega - mean^2 (since E[X^2] = omega).

Return type:: float

entropy()[source]

Differential entropy m + lgamma(m) + (1/2 - m) psi(m) + (1/2) log(omega/m) - log(2).

Derived via the entropy of a monotone transform: X = sqrt(Y) with Y = X^2 ~ Gamma(m, omega/m) (Nakagami, ‘The m-distribution’, 1960), so h(X) = h(Y) - log(2) - E[log X] = h(Y) - log(2) - (1/2)(E[log Y]) and both h(Y) and E[log Y] are standard Gamma-distribution identities. Reduces exactly to the Rayleigh entropy at m = 1.

Return type:: float

sampler(seed=None)[source]

Return a sampler (X = sqrt(Gamma(m, omega/m))).

Parameters:: seed (int | None)
Return type:: NakagamiSampler

estimator(pseudo_count=None)[source]

Return a closed-form method-of-moments estimator.

Parameters:: pseudo_count (float | None)
Return type:: NakagamiEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (the raw value).

Return type:: NakagamiDataEncoder

class NakagamiEstimator(pseudo_count=None, suff_stat=None, m_min=0.5, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator: omega = E[X^2], m = E[X^2]^2 / Var[X^2] (clamped m >= 1/2).

Var[X^2] comes from the shift-anchored moment track whenever the accumulated statistics carry that payload (see NakagamiAccumulator). The shape is the reciprocal of the relative spread of X^2, so the raw E[X^4] - E[X^2]^2 form loses about eps * m: measured against exact rational arithmetic, 2.0e-10 relative at m=1e6, 2.6e-8 at 1e8 and 2.6e-6 at 1e10, now 2.0e-10, 4.7e-16 and 1.0e-13. With a plain raw tuple the historical path is used bit-identically, and estimate warns rather than returning a shape it cannot stand behind.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
m_min (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Nakagami power-sum statistics.

Return type:: NakagamiAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate shape and spread from weighted second and fourth moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

NakagamiDistribution

class RicianDistribution(nu, sigma, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Rician distribution with non-centrality nu >= 0 and scale sigma > 0.

Parameters:

nu (float)
sigma (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at x.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at x (-inf for x <= 0).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded array of observations.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated Rician kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Rician distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row Rician power sums in accumulator order (count, sum x^2, sum x^4).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, nu, sigma, engine)[source]

Engine-neutral Rician log-density (-inf for x <= 0).

Parameters:

x (Any)
nu (Any)
sigma (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Stacked Rician parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[RicianDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Rician log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Stacked Rician power sums (count, sum x^2, sum x^4) using engine-resident arrays.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (Marcum-Q, via scipy rice).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) (via scipy rice).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean sigma sqrt(pi/2) L_{1/2}(-nu^2/(2 sigma^2)) (stable via the scaled Bessel ive).

Return type:: float

variance()[source]

Variance E[X^2] - mean^2 with E[X^2] = nu^2 + 2 sigma^2.

Return type:: float

entropy()[source]

Differential entropy in nats, by adaptive quadrature of -f(x) log f(x) over x > 0.

At nu = 0 the Rician is exactly the Rayleigh, whose entropy is the closed form 1 + log(sigma / sqrt(2)) + euler_gamma / 2. For nu > 0 the density’s log I0(x nu / sigma^2) term has no closed-form expectation (Rice, ‘Mathematical analysis of random noise’, 1944/1945), so the integral is evaluated numerically against the exact log-density.

Return type:: float

sampler(seed=None)[source]

Return a sampler (the envelope of a 2-D Gaussian offset by nu).

Parameters:: seed (int | None)
Return type:: RicianSampler

estimator(pseudo_count=None)[source]

Return a closed-form method-of-moments estimator.

Parameters:: pseudo_count (float | None)
Return type:: RicianEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (the raw value).

Return type:: RicianDataEncoder

class RicianEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator from E[X^2] and E[X^4] (closed-form quadratic in sigma^2).

The quadratic is solved in its RATIONALIZED form, sigma^2 = Var(X^2) / (2 (E[X^2] + sqrt(E[X^2]^2 - Var(X^2)))), whenever the accumulated statistics carry the shift-anchored payload (see RicianAccumulator). Algebraically it is the same root as (m2 - sqrt(2 m2^2 - m4)) / 2, but it differences raw moments once instead of twice, and the one difference it needs is supplied exactly by the anchored track. That makes the fit accurate at any nu/sigma: measured against exact rational arithmetic on the same 2000-point samples, the historical form lost 5.4e-9 relative at nu/sigma 1e4, 4.1e-5 at 1e6 and 44% at 1e8, and now measures 3.5e-15, 7.1e-13 and 3.5e-11. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones that arrived already reduced from an engine kernel or an older serialization – the historical path is used bit-identically, and estimate warns rather than returning a scale it cannot stand behind.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Rician power-sum statistics.

Return type:: RicianAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Rician noncentrality and scale from second and fourth moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

RicianDistribution

class VonMisesEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the von Mises mean direction and concentration.

The MLE is mu = atan2(sum sin, sum cos) and kappa = A^{-1}(R) where R is the mean resultant length and A(kappa) = I_1(kappa) / I_0(kappa).

The data must be angles in radians. Any finite real is accepted and wrapped modulo 2*pi (only cos/sin enter the statistics), so fitting a non-angular real-line column does not fail – it silently fits the circular law of x mod 2*pi, whose log-likelihood is normalized over one period and is not comparable to real-line families (see the module docstring).

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for von Mises circular moments.

Return type:: VonMisesAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate mean direction and concentration from weighted circular moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

VonMisesDistribution

exception VonMisesFitError[source]

Bases: RuntimeError

Raised when circular moments have no finite von Mises fit.

class WeibullDistribution(shape, scale, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Weibull distribution with shape > 0 and scale > 0 on x >= 0.

Parameters:

shape (float)
scale (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated Weibull kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Weibull distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Weibull sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

static backend_log_density_from_params(vals, log_vals, shape, scale, engine)[source]

Engine-neutral Weibull log-density from explicit parameters.

Parameters:

vals (Any)
log_vals (Any)
shape (Any)
scale (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Weibull parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[WeibullDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Weibull log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean scale * Gamma(1 + 1/shape).

Return type:: float

variance()[source]

Variance scale^2 * (Gamma(1+2/shape) - Gamma(1+1/shape)^2).

Return type:: float

entropy()[source]

Differential entropy gamma*(1 - 1/shape) + log(scale/shape) + 1.

Return type:: float

mode()[source]

Mode scale*((k-1)/k)^(1/k) for shape k>1, else 0.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: WeibullSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: WeibullEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: WeibullDataEncoder

class GeneralizedParetoDistribution(scale, shape, loc=0.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Generalized Pareto distribution with threshold loc, scale > 0 and shape xi.

Parameters:

scale (float)
shape (float)
loc (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation (-inf outside the support).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated generalized-Pareto kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for generalized Pareto distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row GPD moment sums in accumulator order (sum, sum2, count).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, scale, shape, loc, engine)[source]

Engine-neutral GPD log-density; the abs(xi) < tol exponential limit is selected per element.

Parameters:

x (Any)
scale (Any)
shape (Any)
loc (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Stacked GPD parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GeneralizedParetoDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of GPD log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Stacked GPD moment sums (sum, sum2, count) using engine-resident arrays.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean loc + scale/(1-xi) for xi < 1, else inf.

Return type:: float

variance()[source]

Variance scale^2 / ((1-xi)^2 (1-2xi)) for xi < 1/2, else inf.

Return type:: float

entropy()[source]

Differential entropy log(scale) + xi + 1.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: GeneralizedParetoSampler

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for scale and shape at the fixed threshold loc.

Parameters:: pseudo_count (float | None)
Return type:: GeneralizedParetoEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: GeneralizedParetoDataEncoder

class GeneralizedParetoEstimator(loc=0.0, pseudo_count=None, suff_stat=None, min_scale=1.0e-12, xi_max=0.5 - 1.0e-6, xi_min=-10.0, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for GPD scale and shape at a fixed threshold loc.

Both inverted moments – the exceedance mean sum_x/count - loc and the variance E[x^2]-E[x]^2 – are differences taken at DATA magnitude, so a threshold far from zero destroys them: peaks over a threshold at epoch seconds fitted shape=0 (the exponential limit) instead of +0.16, silently. Whenever the accumulated statistics carry the shift-anchored payload (see GeneralizedParetoAccumulator) both moments are formed about a data anchor instead, which makes the fit THRESHOLD-EQUIVARIANT: estimating on x + c with the threshold at loc + c returns the same scale and shape, for any constant c the data can carry. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones that arrived already reduced from an engine kernel or an older serialization – the historical raw path is used bit-identically, and estimate warns rather than returning moments it cannot stand behind.

The pseudo_count prior is carried as the raw pair suff_stat = (mean0, second0); a plain 2-tuple has its variance and exceedance-mean offset recovered by differencing (second0 - mean0**2 and mean0 - loc respectively), which is the prior’s own encoding and is unaffected by the anchored track – a prior whose mean sits far from zero loses precision in both reconstructions, so express such a prior in threshold-relative coordinates, or build it with GeneralizedParetoDistribution.estimator(), which carries both exactly (see GeneralizedParetoPriorMoments).

loc is a property, not a bare attribute: reassigning it re-targets this SAME estimator at a new threshold (the “threshold stability” / mean-residual-life re-thresholding workflow) and, when a pseudo_count prior is configured, re-anchors its frozen (mean0, second0) moments to the new origin so the prior keeps meaning what it meant when built instead of being silently reinterpreted relative to the wrong loc (T1-01).

Parameters:

loc (float)
pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_scale (float)
xi_max (float)
xi_min (float)
name (str | None)
keys (str | None)

property loc: float: The fixed threshold mu observations are exceedances over.

accumulator_factory()[source]

Return an accumulator factory for generalized-Pareto moments.

Return type:: GeneralizedParetoAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate scale and shape from exceedance moments at the fixed location.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

GeneralizedParetoDistribution

class GeneralizedExtremeValueDistribution(loc, scale, shape, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Generalized Extreme Value distribution with location loc, scale > 0 and shape xi.

Parameters:

loc (float)
scale (float)
shape (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation (-inf outside the support).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated GEV kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for GEV distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row GEV moment sums in accumulator order (sum, sum2, sum3, count).

Deliberately not wired into the declaration as legacy_sufficient_statistics. The generated statistic path reduces every declared statistic with a weighted sum, ignoring StatisticSpec.additive, so it cannot produce the observed range the M-step needs to keep the fitted support around the data (see _shape_covering_range()) – it would silently hand estimate a summed min and max. GEV therefore accumulates through the host seq_update, which is three dot products for a univariate leaf; engine-resident scoring via backend_seq_log_density is unaffected. Reinstate this hook once the generated path honours non-additive support bounds.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, loc, scale, shape, engine)[source]

Engine-neutral GEV log-density; the abs(xi) < tol Gumbel limit is selected per element.

s^{-1/xi} is computed as exp(-log(s)/xi) so the whole expression stays on engine ops.

Parameters:

x (Any)
loc (Any)
scale (Any)
shape (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Stacked GEV parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GeneralizedExtremeValueDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of GEV log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean: loc + scale*(Gamma(1-xi)-1)/xi (loc+scale*euler_gamma at xi=0); inf for xi>=1.

Return type:: float

variance()[source]

Variance: scale^2 (Gamma(1-2xi)-Gamma(1-xi)^2)/xi^2 (scale^2 pi^2/6 at xi=0); inf for xi>=1/2.

Return type:: float

entropy()[source]

Differential entropy log(scale) + euler_gamma * xi + euler_gamma + 1.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: GeneralizedExtremeValueSampler

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for loc, scale and shape.

Parameters:: pseudo_count (float | None)
Return type:: GeneralizedExtremeValueEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: GeneralizedExtremeValueDataEncoder

class GeneralizedExtremeValueEstimator(pseudo_count=None, suff_stat=None, min_scale=1.0e-12, xi_max=1.0 / 3.0 - 1.0e-4, xi_min=-1.0, name=None, keys=None, prior_central=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for GEV location, scale and shape.

This is a moment estimator, not an MLE: the shape is solved from the skewness-vs-xi relation, and the shape is additionally constrained so the fitted support covers the observed range (see _shape_covering_range()). Whenever that constraint rewrites the shape – or the rewritten shape still scores the extreme observation catastrophically and the estimate falls back to the Gumbel limit – the returned distribution is not the raw moment fit, and the change is recorded in numerical_repairs() so fit_provenance() carries it (MXR-080-1202).

The reduced moments are formed about a reference point rather than about zero whenever the accumulated statistics carry a shift-anchored payload (see GeneralizedExtremeValueAccumulator), which makes the fit shift-equivariant: estimate on x + c returns loc + c with scale and shape unchanged. With a plain raw tuple – statistics restored from an older serialization, or a hand-built one – the historical raw path is used unchanged.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float, float] | None)
min_scale (float)
xi_max (float)
xi_min (float)
name (str | None)
keys (str | None)
prior_central (tuple[float, float, float] | None)

accumulator_factory()[source]

Return an accumulator factory for GEV raw-moment statistics.

Return type:: GeneralizedExtremeValueAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location, scale, and shape from weighted moments, keeping the data in support.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float, float, float, float])

Return type:

GeneralizedExtremeValueDistribution

class WeibullEstimator(pseudo_count=None, suff_stat=None, min_shape=1.0e-3, max_shape=1.0e3, min_scale=1.0e-12, name=None, keys=None)[source]

Bases: ParameterEstimator

Moment estimator for Weibull shape and scale.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_shape (float)
max_shape (float)
min_scale (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Weibull moment statistics.

Return type:: WeibullAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate shape and scale by matching weighted moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

WeibullDistribution

class GateBufferReceipt(rows_seen, rows_retained, rows_dropped, capacity, selection='deterministic_hash_top_k')[source]

Bases: object

Bounded deterministic coreset status for gate-training rows.

Parameters:

rows_seen (int)
rows_retained (int)
rows_dropped (int)
capacity (int)
selection (str)

class GateOptimizationReceipt(converged, steps_completed, initial_loss, final_loss, gradient_norm, termination)[source]

Bases: object

Outcome of a bounded softmax-gate optimization.

Parameters:

converged (bool)
steps_completed (int)
initial_loss (float)
final_loss (float)
gradient_norm (float)
termination (str)

class GatedMixtureDistribution(components, gate, name=None, keys=None, *, gate_fit_receipt=None, gate_buffer_receipt=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A mixture whose weights are a gate p(k | z); observations are (z, y) pairs.

Parameters:

components (Sequence[SequenceEncodableProbabilityDistribution])
gate (Any)
name (str | None)
keys (str | None)
gate_fit_receipt (GateOptimizationReceipt | None)
gate_buffer_receipt (GateBufferReceipt | None)

log_density(x)[source]

Return log p(y | z) for one covariate/response pair.

Parameters:: x (tuple[Any, Any])
Return type:: float

seq_log_density(enc)[source]

Return vectorized conditional log-densities for encoded (z, y) pairs.

Parameters:: enc (Any)
Return type:: ndarray

posterior(x)[source]

Return posterior expert responsibilities for one (z, y) observation.

Parameters:: x (tuple[Any, Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a conditional sampler that requires a covariate z.

Parameters:: seed (int | None)
Return type:: GatedMixtureSampler

estimator(pseudo_count=None)[source]

Return an EM estimator for experts and the covariate-dependent gate.

Parameters:: pseudo_count (float | None)
Return type:: GatedMixtureEstimator

dist_to_encoder()[source]

Return the encoder for covariates plus expert response encodings.

Return type:: GatedMixtureDataEncoder

class GatedMixtureEstimator(component_estimators, gate, gate_steps=200, gate_lr=0.1, gate_tol=1.0e-8, max_buffer_rows=10_000, name=None, keys=None)[source]

Bases: ParameterEstimator

M-step: refit each expert from its responsibility-weighted stats, refit the gate on (z, resp).

Parameters:

component_estimators (Sequence[ParameterEstimator])
gate (Any)
gate_steps (int)
gate_lr (float)
gate_tol (float)
max_buffer_rows (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for gated-mixture sufficient-statistic accumulators.

Return type:: GatedMixtureAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate experts from responsibility-weighted stats and refit the gate.

Parameters:

nobs (float | None)
suff_stat (tuple[Any, ...])

Return type:

GatedMixtureDistribution

class SoftmaxGate(weight, bias, *, fit_receipt=None)[source]

Bases: object

A torch-free multinomial-logistic gate p(k | z) = softmax(W z + b)_k, fit on soft targets.

fit(Z, R) minimizes the soft cross-entropy -sum_{n,k} R_{n,k} log p(k | z_n) by gradient descent – R are the responsibilities (rows need not sum to 1; the sample weight is folded in).

Parameters:

weight (np.ndarray)
bias (np.ndarray)
fit_receipt (GateOptimizationReceipt | None)

classmethod zeros(n_classes, n_features)[source]

Create a zero-logit gate with uniform initial class probabilities.

Parameters:

n_classes (int)
n_features (int)

Return type:

SoftmaxGate

log_prob_batch(z)[source]

(n, K) log-gate log p(k | z_n) for each row of z (shape (n, p)).

Parameters:: z (ndarray)
Return type:: ndarray

fit_with_receipt(z, resp, *, steps=200, lr=0.1, tol=1.0e-8)[source]

Fit a softmax gate and return explicit convergence/failure status.

Parameters:

z (ndarray)
resp (ndarray)
steps (int)
lr (float)
tol (float)

Return type:

tuple[SoftmaxGate, GateOptimizationReceipt]

fit(z, resp, *, steps=200, lr=0.1, tol=1.0e-8)[source]

Fit a softmax gate; the returned gate carries fit_receipt.

Parameters:

z (ndarray)
resp (ndarray)
steps (int)
lr (float)
tol (float)

Return type:

SoftmaxGate

class HeterogeneousMixtureDistribution(components, w=MISSING, name=None, weights=MISSING)[source]

Bases: SequenceEncodableProbabilityDistribution

Mixture distribution with component-specific observation encoders.

Parameters:

components (Sequence[SequenceEncodableProbabilityDistribution])
w (list[float] | ndarray)
name (str | None)
weights (list[float] | ndarray)

compute_capabilities()[source]: Return compute-backend metadata shared by heterogeneous mixture components.

compute_declaration()[source]: Return the symbolic declaration for heterogeneous mixture weights and components.

density(x)[source]

Evaluate the density of the heterogeneous mixture at one observation.

See log_density() for details.

Parameters:: x (T) – (T): Single observation from heterogeneous mixture distribution. T is data type of components.
Returns:: Density at x.
Return type:: float

density_semantics()[source]: Return joined density semantics over heterogeneous mixture components.

log_density(x)[source]

Evaluate log-density of heterogeneous mixture distribution at observation x.

A K-component heterogeneous mixture has log-density,

log(p_mat(x)) = log(sum_{z=k}^{K} p_mat(x|z=k)*p_mat(z=k)),

where p_mat(x|z=k) is component-k log-density at x, and p_mat(z=k) = w[k]. A log-sum-exp is used to evaluate the sum inside the log of the right-hand side above. (See mixle.utils.vector.log_sum() for details).

Recall: p_mat(x|z=k) need only be compatible with same data type T. They are need not be the same distribution.

Parameters:: x (T) – (T): Single observation from heterogeneous mixture distribution. T is data type of components.
Returns:: Log-density at x.
Return type:: float

component_log_density(x)[source]

Evaluate component-wise log-density of heterogeneous mixture distribution at observation x.

A K-component heterogeneous mixture has log-density,

log(p_mat(x)) = log(sum_{z=k}^{K} p_mat(x|z=k)*p_mat(z=k)),

where p_mat(x|z=k) is component-k log-density at x, and p_mat(z=k) = w[k].

This function returns an ndarray[float] of length K, containing log(p_mat(x|z=k)) as its k^{th} entry.

Parameters:: x (T) – (T): Single observation from mixture distribution. T is data type of components.
Returns:: Numpy array of floats containing component-wise log-density at x.
Return type:: ndarray

posterior(x)[source]

Obtain the posterior distribution for each heterogeneous mixture component at observation x.

The posterior distribution of component ‘k’ at observation x is given by,

p_mat(Z=k|x) = p_mat(x|Z=k)*p_mat(z=k) / p_mat(x),

where

p_mat(x) = sum_{k=1}^{K} p_mat(x|Z=k)*p_mat(z=k) = sum_{k=1}^{K} p_mat(x|Z=k)*w[k].

This function returns an ndarray[float] of length K, containing p_mat(Z=k|x) as its k^{th} entry.

Parameters:: x (T) – (T): Single observation from heterogeneous mixture distribution. T is data type of components.
Returns:: Numpy array of floats containing posterior distribution at observation x.
Return type:: ndarray

seq_log_density(x)[source]

Vectorized evaluation of component-wise log-density for encoded sequence x.

Evaluates the log-density of each observation in the encoded sequence x (see log_density() for details).

Arg x must be a Tuple of length two containing and encoded from: HeterogeneousMixtureDataEncoder.seq_encode(data) with data type Sequence[T] for data.
x[0] (List[np.ndarray[int]]): The component ids for each distinct SequenceEncodableProbabilityDistribution: subclass.
x[1] (List[T1,T2,..Tk]): A list of sequence encodings of iid an iid observation sequence for each: ‘k’ distinct SequenceEncodableProbabilityDistribution subclasses. The data type for each encoding is assumed to be of type Ti.

The returned value is an ndarray[float] with shape (sz,K), where K is the number of mixture components, and sz is the number of iid observations in the encoded sequence x.

Note: A row-wise log-sum-exp is performed for numerical stability. If a row contains a log-density value of,: -np.inf is returned for the corresponding observation value in the encoded sequence x.

Parameters:: x (tuple[list[ndarray], list[Any]]) – See above for details.
Returns:: Numpy array of floats containing the log_density of each observation in encoded sequence.
Return type:: ndarray

seq_component_log_density(x)[source]

Vectorized evaluation of component-wise log-density for encoded sequence x.

Arg x must be a Tuple of length two containing and encoded from: HeterogeneousMixtureDataEncoder.seq_encode(data) with data type Sequence[T] for data.
x[0] (List[np.ndarray[int]]): The component ids for each distinct SequenceEncodableProbabilityDistribution: subclass.
x[1] (List[T1,T2,..Tk]): A list of sequence encodings of iid an iid observation sequence for each: ‘k’ distinct SequenceEncodableProbabilityDistribution subclasses. The data type for each encoding is assumed to be of type Ti.

Creates a 2-d numpy array of floats with vectorized evaluations of component_log_density() stored in the rows corresponding to an observation in encoded sequence x.

The returned value is an ndarray[float] with shape (sz,K), where K is the number of mixture components, and sz is the number of iid observations in the encoded sequence x.

Parameters:: x (tuple[list[ndarray], list[Any]]) – See above for details.
Returns:: 2-d numpy array of floats having shape (sz,K), where sz is the number of iid obs in encoded sequence x, and K is the number of mixture components.
Return type:: ndarray

backend_seq_component_log_density(x, engine)[source]

Engine-neutral component log densities for heterogeneous encoded data.

Parameters:

x (tuple[list[ndarray], list[Any]])
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral heterogeneous-mixture log-density for encoded data.

Parameters:

x (tuple[list[ndarray], list[Any]])
engine (Any)

Return type:

seq_posterior(x)[source]

Vectorized evaluation of posterior of HeterogeneousMixtureDistribution for encoded sequence x.

Arg x must be a Tuple of length two containing and encoded from: HeterogeneousMixtureDataEncoder.seq_encode(data) with data type Sequence[T] for data.
x[0] (List[np.ndarray[int]]): The component ids for each distinct SequenceEncodableProbabilityDistribution: subclass.
x[1] (List[T1,T2,..Tk]): A list of sequence encodings of iid an iid observation sequence for each: ‘k’ distinct SequenceEncodableProbabilityDistribution subclasses. The data type for each encoding is assumed to be of type Ti.

Vectorized evaluation the posterior of each observation in the encoded sequence x (see posterior() for details).

The returned value is an ndarray[float] with shape (sz,K), where K is the number of mixture components, and sz is the number of iid observations in the encoded sequence x. Each row contains the posterior of the corresponding encoded observation.

Note: A row-wise log-sum-exp is performed for numerical stability. If a row contains a log-density value of,: -np.inf is returned for the corresponding observation value in the encoded sequence x.

Parameters:: x (tuple[list[ndarray], list[Any]]) – See above for details.
Returns:: Numpy array of floats containing the posterior of each observation in encoded sequence.
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for this heterogeneous mixture.

Parameters:: seed (Optional[int]) – Seed to set for sampling with RandomState.
Returns:: HeterogeneousMixtureSampler object.
Return type:: HeterogeneousMixtureSampler

estimator(pseudo_count=None)[source]

Return an estimator with one child estimator per component.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics in estimation.
Returns:: HeterogeneousMixtureEstimator object.
Return type:: HeterogeneousMixtureEstimator

decomposition()[source]: Heterogeneous mixture components split along the component axis (logsumexp responsibilities inside a shard; per-component stats SUM-reduce). Components are NOT homogeneous, so there is no stacked-parameter tensor to DTensor-shard (engine_axis=None -> host-shard executor mode).

dist_to_encoder()[source]

Return a data encoder assembled from the component distribution encoders.

Return type:: HeterogeneousMixtureDataEncoder

enumerator()[source]

Returns a HeterogeneousMixtureEnumerator iterating the union of component supports in descending mixture probability order.

Return type:: HeterogeneousMixtureEnumerator

class HeterogeneousMixtureEstimator(estimators, fixed_weights=None, suff_stat=None, pseudo_count=None, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

Estimator for heterogeneous mixture weights and component distributions.

Parameters:

estimators (list[ParameterEstimator])
fixed_weights (ndarray | None)
suff_stat (ndarray | None)
pseudo_count (float | None)
name (str | None)
keys (tuple[str | None, str | None])

accumulator_factory()[source]

Return an accumulator factory built from the component estimator factories.

Return type:: HeterogeneousMixtureAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a heterogeneous mixture from aggregated sufficient statistics.

suff_stat is a two-item tuple containing:: suff_stat[0] (np.ndarray): Sufficient statistics for mixture weights. suff_stat[1] (Tuple[T1,…,Tk]): Tuple of K sufficient statistics for the heterogeneous mixture components.

suff_stat[1] is passed to the corresponding component estimator.

If fixed_weights is not None, suff_stat[0] is ignored and the estimated distribution uses the fixed weights.

If pseudo_count is set, observed counts are blended with either the estimator’s prior statistics or a uniform pseudo-count allocation.

If pseudo_count is None, observed component counts determine the weights.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator super class.
suff_stat (tuple[ndarray, tuple[Any, ...]]) – See above for details.

Returns:

Estimated mixture distribution.

Return type:

HeterogeneousMixtureDistribution

class HeterogeneousMixtureEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerator over the deduplicated union of heterogeneous component supports.

Parameters:: dist (HeterogeneousMixtureDistribution)

class HeterogeneousPCFGDistribution(binary_rules, terminal_rules, start=None, nonterminals=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

CNF PCFG whose terminal productions emit arbitrary distributions.

Parameters:

binary_rules (BinaryRuleInput | None) – Either {parent: [(left, right, prob), ...]} or a flat sequence of (parent, left, right, prob) rules.
terminal_rules (TerminalRuleInput) – Either {parent: [(emission_dist, prob), ...]} or a flat sequence of (parent, emission_dist, prob) rules.
start (Any | None) – Start nonterminal. If omitted, the first nonterminal is used.
nonterminals (Sequence[Any] | None) – Optional explicit nonterminal order.
name (str | None) – Optional model name.

Rule probabilities are normalized over all rules sharing a parent.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (Sequence[Any])
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (Sequence[Any])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[ndarray, tuple[Any, ...]])
Return type:: ndarray

compute_capabilities()[source]

Engine readiness intersected from the terminal emission distributions.

The CKY inside dynamic program is expressed in ComputeEngine ops (see backend_seq_log_density), so the grammar is engine-ready on whatever engines all of its terminal emission leaves support (numpy plus, e.g., torch for autograd/GPU).

backend_seq_log_density(x, engine)[source]

Engine-routed CKY inside scoring (numpy + torch).

Terminal log-densities come from each emission leaf’s own engine backend score, and the inside dynamic program runs in ComputeEngine ops. Per-sequence charts are still a Python loop (variable-length parses), so this trades the tuned NumPy _inside for engine portability and differentiability rather than raw speed.

Parameters:: x (tuple[ndarray, tuple[Any, ...]])
Return type:: Any

to_fisher(**kwargs)[source]: Inside-outside Fisher view for the PCFG.

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: HeterogeneousPCFGSampler

enumerator()[source]

Return an exact support enumerator for acyclic enumerable PCFGs.

Return type:: HeterogeneousPCFGEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded index with an inside-style DP over quantized derivation costs.

Terminal emission distributions must themselves support quantized_index. The DP counts grammar derivations by additive quantized bit cost and lazily unranks those derivations into emitted terminal sequences. For unambiguous grammars this is an index over distinct sequences; for ambiguous grammars the same sequence can be represented by multiple derivations, and the returned log probability is still the exact PCFG log_density of that sequence.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

LazyQuantizedEnumerationIndex

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: HeterogeneousPCFGEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: HeterogeneousPCFGDataEncoder

class HeterogeneousPCFGEstimator(binary_rules, terminal_rules, start=None, nonterminals=None, pseudo_count=None, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

Estimator for a fixed-topology heterogeneous PCFG.

Parameters:

binary_rules (BinaryRuleInput | None)
terminal_rules (TerminalRuleInput)
start (Any | None)
nonterminals (Sequence[Any] | None)
pseudo_count (float | None)
name (str | None)
keys (tuple[str | None, str | None] | None)

accumulator_factory()[source]

Return an accumulator factory for this fixed grammar topology.

Return type:: HeterogeneousPCFGAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate rule probabilities and terminal emissions from statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray, Sequence[Any]])

Return type:

HeterogeneousPCFGDistribution

class InducedHeterogeneousPCFGEstimator(max_nonterminals, terminal_estimators, start='S', nonterminal_prefix='NT', terminal_rule_mass=0.5, rule_pseudo_count=1.0e-3, prune_threshold=0.0, min_rule_prob=0.0, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

Overcomplete sparse PCFG structure learner.

This estimator builds a finite grammar skeleton automatically:

K nonterminals named start, prefix1, ..., prefixK-1.
every binary rule A -> B C.
every terminal rule A -> terminal_family_j.

EM learns rule probabilities and terminal emission parameters. Rules whose expected count is below prune_threshold or whose normalized probability is below min_rule_prob are assigned probability zero, but the rule layout is kept stable so repeated calls to seq_estimate remain compatible.

Parameters:

max_nonterminals (int)
terminal_estimators (Sequence[ParameterEstimator])
start (Any)
nonterminal_prefix (str)
terminal_rule_mass (float)
rule_pseudo_count (float | None)
prune_threshold (float)
min_rule_prob (float)
name (str | None)
keys (tuple[str | None, str | None] | None)

accumulator_factory()[source]

Return an accumulator factory for the induced grammar skeleton.

Return type:: HeterogeneousPCFGAccumulatorFactory

initial_model(terminal_distributions, rng=None, jitter=0.0)[source]

Create an overcomplete starting grammar without hand-written rules.

terminal_distributions may contain one distribution per terminal family, in which case each nonterminal gets its own copy of the same family list, or one distribution per generated terminal rule.

Parameters:

terminal_distributions (Sequence[SequenceEncodableProbabilityDistribution])
rng (RandomState | None)
jitter (float)

Return type:

HeterogeneousPCFGDistribution

estimate(nobs, suff_stat)[source]

Estimate a sparse grammar from rule counts and emission statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray, Sequence[Any]])

Return type:

HeterogeneousPCFGDistribution

class HeterogeneousPCFGEnumerator(dist)[source]

Bases: DistributionEnumerator

Exact best-first enumerator for acyclic heterogeneous PCFGs.

Parameters:: dist (HeterogeneousPCFGDistribution)

class HiddenAssociationDistribution(cond_dist, given_dist=NullDistribution(), len_dist=NullDistribution(), name=None, keys=(None, None))[source]

Bases: SequenceEncodableProbabilityDistribution

Hidden association model: values of a second set are emitted conditionally on values drawn from a first set.

Parameters:

cond_dist (ConditionalDistribution)
given_dist (SequenceEncodableProbabilityDistribution | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
keys (tuple[str | None, str | None] | None)

compute_capabilities()[source]: Return backend capability metadata for this concrete hidden association model.

compute_declaration()[source]: Return the generated-compute declaration for hidden association.

log_density(x)[source]

Log-density of the hidden association model at observation x.

For each emitted value in x[1], marginalizes the conditional emission density over the given values in x[0] weighted by their counts, then adds the log-density of the given set under given_dist and of the total emission count under len_dist.

Parameters:: x (Tuple[List[Tuple[T, float]], List[Tuple[T, float]]]) – Grouped-count observation ([(given value, count)], [(emitted value, count)]).
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Evaluation of log-density at sequence encoded input x (loops over log_density).

Parameters:: x (List[Tuple[List[Tuple[T, float]], List[Tuple[T, float]]]]) – Sequence encoded observations from HiddenAssociationDataEncoder.seq_encode() (the observations themselves).
Returns:: Numpy array of log-density values, one per observation.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Evaluate encoded log-densities through distribution-owned backend composition.

Parameters:

x (Sequence[tuple[list[tuple[T, float]], list[tuple[T, float]]]])
engine (Any)

Return type:

emission_mixture(s1)[source]

The per-emission distribution q(.|S1) as a mixture, or None for an empty/degenerate S1.

q(emitted|S1) = sum_u (c_u/n1) P(emitted|u) is a finite mixture of the conditional emission distributions cond_dist.dmap[u] weighted by the given-bag’s normalized counts – enumerable whenever those component distributions are. Requires cond_dist to be a ConditionalDistribution (so the per-given components are available).

Parameters:: s1 (list[tuple[T, float]])
Return type:: MixtureDistribution | None

enumerator()[source]

Enumerate (S1, S2) observations in descending probability order.

The model factors as given_dist(S1) * [prod_e q(e|S1)^{c_e}] * P_len(n): the emitted bag S2 is drawn iid from the per-given mixture q(.|S1) (see emission_mixture()). Enumeration is a conditional product – the outer stream enumerates S1 from given_dist and, for each S1, the inner stream enumerates S2 as a multiset best-first search over q(.|S1)’s own enumeration under len_dist, merged by descending total score with given_dist(S1) as the frontier bound. Requires an enumerable non-null given_dist and a ConditionalDistribution cond_dist.

Return type:: DistributionEnumerator

sampler(seed=None)[source]

Return a sampler for iid grouped-count pairs.

Requires non-null given_dist and len_dist.

Parameters:: seed (int | None) – Optional random seed.
Returns:: A configured HiddenAssociationSampler.
Return type:: HiddenAssociationSampler

estimator(pseudo_count=None)[source]

Return an estimator built from the child estimators.

Parameters:: pseudo_count (float | None) – Unused; accepted for protocol consistency.
Returns:: A configured HiddenAssociationEstimator.
Return type:: HiddenAssociationEstimator

dist_to_encoder()[source]

Return an encoder for grouped-count hidden-association observations.

Return type:: HiddenAssociationDataEncoder

class HiddenAssociationEstimator(cond_estimator, given_estimator=NullEstimator(), len_estimator=NullEstimator(), pseudo_count=None, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

Estimator for hidden association distributions.

Parameters:

cond_estimator (ConditionalDistributionEstimator)
given_estimator (ParameterEstimator | None)
len_estimator (ParameterEstimator | None)
pseudo_count (float | None)
name (str | None)
keys (tuple[str | None, str | None] | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: HiddenAssociationAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a HiddenAssociationDistribution from aggregated sufficient statistics.

Parameters:

nobs (Optional[float]) – Number of observations, passed to the given and length estimators.
suff_stat (Tuple[SS1, Optional[SS2], Optional[SS3]]) – Conditional, given, and size suff stats.

Returns:

HiddenAssociationDistribution object.

Return type:

HiddenAssociationDistribution

class StructuredHMM(emissions, pi, transition, emission_estimators=None, keys=(None, None), name=None, len_dist=None, terminal_states=None, final_states=None)[source]

Bases: object

An HMM whose transition is a TransitionOperator (dense / low-rank / a combinator).

emissions is one observation distribution per state; pi the initial-state distribution; transition any TransitionOperator. The scaled forward-backward and EM call the operator’s forward/backward/accumulate/estimate, so a low-rank or factorial transition runs the SAME inference at its own cost (O(K r) for low-rank). emission_estimators (one per state) drives the emission M-step; default reuses emissions[k].estimator().

Parameters:: transition (TransitionOperator)

viterbi(seq)[source]: Most-likely state path (Viterbi / max-product). Uses the transition matrix, so it works for any operator; O(T K^2) – a read-out, not the EM hot loop.

posterior_decode(seq)[source]: Per-position MAP state argmax_k P(z_t = k | x) from the forward-backward posteriors gamma.

enumerator()[source]: Enumerate observation sequences in descending marginal probability (top_k / rank / seek / nucleus / certified estimates). Enumeration depends only on pi, the transition MATRIX, the emissions and a length distribution – not on the operator’s internal structure – so it reuses the built-in HMM enumerator (an A*-style best-first search over the trellis) on the dense matrix. Requires len_dist (a distribution over sequence length) and enumerable (discrete) emissions.

dist_to_enumerator()[source]: Return the sequence enumerator for this HMM.

state_posteriors(seq)[source]: The full smoothing posteriors gamma[t,k] = P(z_t = k | x).

seq_log_density(seqs)[source]

Score a batch of observation sequences.

Return type:: ndarray

sampler(seed=None)[source]: Return a sampler for observation sequences.

fit(seqs, *, max_its=50, tol=1e-6, fast=True, weights=None)[source]

Fit by Baum-Welch through the transition operator.

fast=True uses the numba-jitted dense forward-backward when possible. The returned HMMFitResult remains unpackable as (fitted_hmm, loglik_trace) and also exposes a validated diagnostics receipt.

Parameters:

max_its (int)
tol (float)
fast (bool)

class StructuredHMMEstimator(emission_estimators, transition_proto, keys=(None, None), name=None, len_dist=None, terminal_states=None)[source]

Bases: ParameterEstimator

Estimator (M-step) for a StructuredHMM: re-estimates pi, the transition OPERATOR (any structure – dense/low-rank/combinator), and each state’s emission from the Baum-Welch statistics. keys=(init_key, trans_key) tie the initial / transition parameters across HMMs that share them.

accumulator_factory()[source]: Return the accumulator factory used by this estimator.

estimate(nobs, suff_stat)[source]: Estimate an HMM from Baum-Welch sufficient statistics.

class TransitionOperator[source]

Bases: object

A row-stochastic state-transition operator behind the HMM forward-backward.

Subclasses provide the two linear maps the recursions need plus an M-step from expected transition mass. forward/backward must be consistent with as_matrix (forward(a) == a @ A, backward(v) == A @ v); the low-overhead operators never materialize A.

to_dict()[source]

Return a safe JSON-compatible representation of this operator.

Return type:: dict[str, Any]

classmethod from_dict(payload)[source]

Reconstruct an operator from to_dict output.

Parameters:: payload (dict[str, Any])
Return type:: TransitionOperator

forward(alpha)[source]

Push a state-belief row vector one transition forward.

Parameters:: alpha (ndarray)
Return type:: ndarray

backward(v)[source]

Pull an emission-weighted belief vector one transition backward.

Parameters:: v (ndarray)
Return type:: ndarray

as_matrix()[source]

Materialize the transition matrix when an explicit matrix is needed.

Return type:: ndarray

new_accumulator()[source]

Create an empty transition sufficient-statistic accumulator.

Return type:: Any

accumulate(acc, alpha_t, w_next, scale)[source]

Add one transition’s expected mass. alpha_t is the (normalized) forward belief at t, w_next = b_{t+1} * beta_{t+1} the emission-weighted backward belief at t+1, scale the forward normalizer c_{t+1} (so the per-step posterior transition mass is exact).

Parameters:

acc (Any)
alpha_t (ndarray)
w_next (ndarray)
scale (float)

Return type:

None

estimate(acc)[source]

Estimate a transition operator of the same structural family from accumulated statistics.

Parameters:: acc (Any)
Return type:: TransitionOperator

random_accumulator(rng)[source]

A randomly-filled accumulator whose estimate yields a random (structured) transition – used to seed EM when there is no warm start. Fills new_accumulator shapes (nested) with noise.

Return type:: Any

class DenseTransition(a, prior=None)[source]

Bases: TransitionOperator

The usual dense K x K row-stochastic transition (O(K^2) forward-backward).

prior (a K x K pseudocount matrix) is added to the expected counts before each M-step re-normalization – a Dirichlet/MAP transition. A diagonal prior is a sticky self-transition bias (see sticky_transition()); a flat prior is symmetric-Dirichlet smoothing.

Parameters:

a (np.ndarray)
prior (np.ndarray | None)

forward(alpha)[source]: Push a state-belief row vector forward with the dense matrix.

backward(v)[source]: Pull a vector backward with the dense matrix.

as_matrix()[source]: Return the dense row-stochastic transition matrix.

new_accumulator()[source]: Create dense expected-transition-count storage.

accumulate(acc, alpha_t, w_next, scale)[source]: Accumulate one dense expected-transition-count contribution.

estimate(acc)[source]: Estimate a row-normalized dense transition from expected counts.

class LowRankTransition(g, phi)[source]

Bases: TransitionOperator

A = G @ Phi: each state’s next-state distribution is a mix of r shared transition profiles.

G is K x r row-stochastic (state -> profile mixing), Phi is r x K row-stochastic (profile -> next-state). A = G @ Phi is K x K row-stochastic with rank <= r. Forward ((alpha @ G) @ Phi), backward (G @ (Phi @ v)) and the M-step are all O(K r) – never forming A – and the parameter count is 2 K r instead of K^2.

Parameters:

g (np.ndarray)
phi (np.ndarray)

forward(alpha)[source]: Push a state-belief row vector through the low-rank transition.

backward(v)[source]: Pull a vector backward through the low-rank transition.

as_matrix()[source]: Materialize the implied dense transition matrix.

new_accumulator()[source]: Create state-profile and profile-next sufficient-statistic storage.

accumulate(acc, alpha_t, w_next, scale)[source]: Accumulate one exact low-rank transition contribution.

estimate(acc)[source]: Estimate low-rank transition factors from accumulated statistics.

class BlockDiagonalTransition(blocks)[source]

Bases: TransitionOperator

Independent sub-chains: the states partition into blocks and transitions stay within a block.

A model whose initial state picks a block and then evolves inside it – a mixture of regimes that do not switch. Build it from any sub-operators (each block can itself be dense or low-rank). Exact, block-local forward-backward and M-step.

forward(alpha)[source]: Push each block’s belief mass forward independently.

backward(v)[source]: Pull each block’s vector backward independently.

as_matrix()[source]: Materialize the block-diagonal transition matrix.

new_accumulator()[source]: Create one transition accumulator per block.

accumulate(acc, alpha_t, w_next, scale)[source]: Accumulate block-local expected transition mass.

estimate(acc)[source]: Estimate each block and return a new block-diagonal transition.

class KroneckerTransition(op1, op2)[source]

Bases: TransitionOperator

Factorial HMM: the state is the pair (s1, s2) of two chains evolving in parallel, with A = A1 (x) A2 (Kronecker). State index is i1 * K2 + i2.

Forward-backward uses the reshape identity (alpha @ (A1 (x) A2) reshapes to A1^T @ M @ A2), so a step is O(K1 K2 (K1 + K2)) instead of O((K1 K2)^2) – the whole point of a factorial HMM. The E-step is exact over the joint state; the M-step is the standard factorial marginal update (each factor re-estimated from the marginalized joint transition mass), verified to keep EM monotone.

Parameters:

op1 (TransitionOperator)
op2 (TransitionOperator)

forward(alpha)[source]: Push a joint belief through the Kronecker-factorized transition.

backward(v)[source]: Pull a joint vector backward through the Kronecker transition.

as_matrix()[source]: Materialize the dense Kronecker transition matrix.

new_accumulator()[source]: Create marginal transition-count accumulators for both factors.

accumulate(acc, alpha_t, w_next, scale)[source]: Accumulate exact marginalized factor transition statistics.

estimate(acc)[source]: Estimate both Kronecker factors from marginalized expected counts.

class SparseTransition(n_states, edges, values=None)[source]

Bases: TransitionOperator

Only the given (from, to) edges are allowed (left-to-right / banded HMMs). Forward, backward and the M-step are O(#edges) – transitions outside the edge set stay exactly zero through EM, so the structure is preserved. Build edges yourself or with left_to_right_edges() / banded_edges().

Parameters:: n_states (int)

forward(alpha)[source]: Push a state-belief row vector through the sparse transition.

backward(v)[source]: Pull a vector backward through the sparse transition.

as_matrix()[source]: Materialize the sparse transition as a dense matrix.

new_accumulator()[source]: Create one expected-count slot per allowed edge.

accumulate(acc, alpha_t, w_next, scale)[source]: Accumulate one sparse expected-transition contribution.

estimate(acc)[source]: Estimate a sparse transition over the same allowed edge set.

class InputOutputHMM(emissions, pi, transitions, emission_estimators=None, name=None, terminal_states=None)[source]

Bases: object

Input-output HMM (IOHMM): an exogenous discrete input u_t selects which transition governs each step. Holds one TransitionOperator per input symbol; the emission is per-state. Data is (obs_seq, input_seq) pairs where input_seq[t] in {0..M-1} drives the transition from t to t+1.

Lets a covariate steer the dynamics – regime switching driven by an observed control, the difference between a plain HMM and a controlled Markov model. (Input-dependent emissions are a natural extension; here emissions depend on state only.)

seq_log_density(x, input_seqs=None)[source]: Per-sequence forward log-likelihood. Two call forms: - seq_log_density(obs_seqs, input_seqs) – the explicit two-list API; or - seq_log_density(records) – one list of (obs, input)-pair sequences (the 5-part contract).

viterbi(seq, inputs=None)[source]: Most-likely state path (Viterbi / max-product), conditioned on the input/control sequence: step t -> t+1 maximizes over the transition inputs[t] selects. Call as viterbi(record) on one (observation, input)-pair sequence or as viterbi(obs_seq, input_seq). Uses the per-input transition matrices, so it works for any operator; O(T K^2) – a read-out, not the EM hot loop.

posterior_decode(seq, inputs=None)[source]: Per-position MAP state argmax_k P(z_t = k | x, u) from the forward-backward posteriors gamma.

state_posteriors(seq, inputs=None)[source]: The full smoothing posteriors gamma[t,k] = P(z_t = k | x, u), conditioned on the inputs.

sampler(seed=None)[source]: Return a sampler for (observation, input)-pair records along a given control sequence.

fit(obs_seqs, input_seqs, *, max_its=50, tol=1e-6, weights=None)[source]

Fit the IOHMM by weighted Baum-Welch and return a diagnostics-bearing result.

Parameters:

max_its (int)
tol (float)

log_density(seq)[source]: Return the log likelihood of one (observation, input) sequence.

dist_to_encoder()[source]: Return the pass-through IOHMM sequence encoder.

estimator(pseudo_count=None)[source]: Return the estimator for this IOHMM structure.

to_dict()[source]

Return a safe JSON-compatible representation of this IOHMM (decodes via load_models).

Return type:: dict[str, Any]

class ExplicitDurationHMM(emissions, pi, transition_matrix, durations, max_duration, name=None)[source]

Bases: object

Hidden semi-Markov model (explicit-duration HMM): each state emits for a random duration drawn from a per-state duration distribution, then switches state (the transition matrix has a zero diagonal – dwell time is modeled explicitly, not as a self-loop). This captures non-geometric state durations a plain HMM cannot.

durations is one length-max_duration probability vector per state (over d = 1..max_duration). A sequence has an exogenous fixed observation horizon. Its final latent duration is right-censored when it extends beyond that horizon, exactly matching sample(length). Forward/EM are O(T * K * max_duration).

forward_loglik(seq)[source]: Fixed-horizon log likelihood, marginalizing a possibly right-censored final duration.

fit(seqs, *, max_its=50, tol=1e-6, weights=None)[source]

Fit the explicit-duration HMM by weighted Baum-Welch with a diagnostics receipt.

Parameters:

max_its (int)
tol (float)

log_density(seq)[source]: Return the explicit-duration HMM log likelihood for one sequence.

seq_log_density(x)[source]: Score a batch of observation sequences.

dist_to_encoder()[source]: Return the pass-through explicit-duration sequence encoder.

estimator(pseudo_count=None)[source]: Return the estimator for this explicit-duration HMM structure.

to_structured_hmm(len_dist=None)[source]: The HSMM as an EQUIVALENT StructuredHMM via the remaining-duration expansion: K*D sub-states (k, r) = “state k with r steps left in the segment”. The expanded chain emits from state k at every sub-state, decrements deterministically (k,r)->(k,r-1), and at (k,1) switches segment with A[k,k’]*dur[k’](d’). Reading the first T expanded-chain emissions exactly represents the right-censored fixed horizon, so no final-state constraint is applied. This hands the HSMM the full StructuredHMM read-out API and, with len_dist, enumeration. O(K*D) states.

enumerator(len_dist)[source]: Enumerate fixed-horizon observation sequences in descending marginal probability, given a len_dist over total sequence length. Built on the exact right-censored HMM expansion; .top_k(k) -> [(sequence, log_prob), …].

state_posteriors(seq)[source]: Per-position smoothing posteriors gamma[t, j] = P(z_t = j | obs), marginalizing the durations (sum the posterior of every segment that covers position t). Rows sum to 1.

posterior_decode(seq)[source]: Per-position MAP state argmax_j P(z_t = j | obs).

viterbi_segments(seq)[source]: Most-likely segmentation (max-product over the segment lattice): a list of (state, start, observed_duration) segments covering the sequence, O(T K D). The last tuple describes the observed portion of a right-censored latent duration.

sampler(seed=None)[source]: Return a sampler for explicit-duration HMM sequences.

class HMMFitDiagnostics(algorithm, converged, iterations, termination_reason, log_likelihood_trace, initial_log_likelihood, final_log_likelihood, final_absolute_delta, final_relative_delta, monotone, n_sequences, total_weight, approximate)[source]

Bases: object

Machine-readable receipt for a structured-family EM fit.

Parameters:

algorithm (str)
converged (bool)
iterations (int)
termination_reason (str)
log_likelihood_trace (tuple[float, ...])
initial_log_likelihood (float)
final_log_likelihood (float)
final_absolute_delta (float | None)
final_relative_delta (float | None)
monotone (bool)
n_sequences (int)
total_weight (float)
approximate (bool)

class HMMFitResult(model, trace, diagnostics)[source]

Bases: tuple

Backward-compatible (model, trace) result with a fit diagnostics receipt.

Parameters:

model (Any)
trace (list[float])
diagnostics (HMMFitDiagnostics)

property model: Return the fitted model.

property log_likelihood_trace: Return the accepted model log-likelihood trajectory.

jit_forward_loglik(hmm)[source]

Compile the scaled forward log-likelihood recursion to a single jax.jit XLA program (lax.scan over time). Returns a callable score(seq) -> float: emission log-densities are evaluated on the host (arbitrary emissions), then the forward scan runs jitted on the transition matrix. Works for any operator (uses as_matrix()); the win is large T / K. Requires the JAX optional extra.

Precision follows the caller’s ambient JAX policy rather than mixle’s: with the default jax_enable_x64=False the scan runs in float32, so the returned score agrees with seq_log_density to roughly float32 relative precision, not to float64. Enable x64 in your own process if you need more – mixle does not set it for you (MXR-080-0147 removed the import-time global mutation that used to make this path silently float64).

Parameters:: hmm (StructuredHMM)

stationary_initial(op, *, iters=2000, tol=1e-13)[source]

The transition’s stationary distribution (pi @ A == pi), by power iteration through op.forward – so it is O(K r) for a low-rank op, never forming A. Use it to COUPLE a StructuredHMM’s initial state to its transition (pi = stationary_initial(transition)): the chain starts in its long-run distribution instead of a free, separately-estimated pi. Answers “do the initial states match the transition?” – they can, by construction.

Parameters:

op (TransitionOperator)
iters (int)
tol (float)

Return type:

sticky_transition(a, kappa)[source]

A dense transition with a STICKY self-transition prior: kappa pseudocounts on the diagonal favor staying in a state (longer dwell times, cleaner segmentation – the sticky-HMM idea).

Parameters:: kappa (float)
Return type:: DenseTransition

dirichlet_transition(a, alpha)[source]

A dense transition with a symmetric Dirichlet(alpha) smoothing prior on every row (MAP).

Parameters:: alpha (float)
Return type:: DenseTransition

kron_initial(pi1, pi2)[source]

Factorized initial distribution pi1 (x) pi2 for a factorial (Kronecker) HMM – the two chains start independently. Matches a KroneckerTransition so the joint initial respects the factors.

Return type:: ndarray

left_to_right_edges(n_states, skip=1)[source]

Edges for a left-to-right (Bakis) HMM: each state may stay or advance up to skip states.

Parameters:

n_states (int)
skip (int)

banded_edges(n_states, bandwidth=1)[source]

Edges for a banded transition: state i connects to i-bandwidth .. i+bandwidth (local time-series).

Parameters:

n_states (int)
bandwidth (int)

exception HiddenMarkovNonterminationError(*, mode, max_steps, last_state=None)[source]

Bases: RuntimeError

Raised when bounded stopping-time sampling does not reach its terminal event.

Parameters:

mode (str)
max_steps (int)
last_state (int | None)

Return type:

None

class HiddenMarkovModelDistribution(topics=MISSING, w=MISSING, transitions=MISSING, taus=None, len_dist=NullDistribution(), name=None, terminal_values=None, use_numba=None, weights=MISSING, prior=None, terminal_states=None, components=MISSING)[source]

Bases: SequenceEncodableProbabilityDistribution

Hidden Markov model distribution for variable-length observation sequences.

Parameters:

topics (Sequence[SequenceEncodableProbabilityDistribution])
w (Sequence[float] | np.ndarray)
transitions (list[list[float]] | np.ndarray)
taus (list[list[float]] | np.ndarray | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
terminal_values (set[T] | None)
use_numba (bool | None)
weights (Sequence[float] | np.ndarray)
terminal_states (set[int] | Sequence[int] | None)
components (Sequence[SequenceEncodableProbabilityDistribution])

get_prior()[source]

Returns the chain conjugate prior in (init_prior, row_priors) form (or None).

Per-state emission component priors are owned by the emission distributions themselves.

set_prior(prior)[source]

Set the conjugate Dirichlet chain prior and precompute its digamma expectations.

With Dirichlet init_prior and Dirichlet row_priors (over the fixed hidden states 0..S-1) this caches the digamma expectations E[ln p_k] = psi(alpha_k) - psi(sum alpha) used by expected_log_density and sets has_conj_prior accordingly. prior=None leaves the distribution a plain point model.

Parameters:: prior – (init_prior, row_priors) tuple or None.
Return type:: None

expected_log_density(x)[source]

Forward log-likelihood with digamma-expected initial/transition log-probabilities and the topics’ expected_log_density emissions.

Falls back to the plug-in log_density(x) when no conjugate prior is set. Not supported for the taus/topic-mixture parameterization (falls back to log_density there).

Parameters:: x (List[T]) – Observed sequence of HMM emissions.
Returns:: Expected log-density of the observed HMM sequence x.
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density() at sequence-encoded input x.

Falls back to seq_log_density(x) when no conjugate prior is set or for the taus parameterization.

Parameters:: x (tuple[tuple[int, list[tuple[int, int]], list[ndarray], ndarray, ndarray, ndarray, Any], Any, Any | None] | tuple[tuple[ndarray, ndarray, ndarray], Any | None]) – Encoded sequences from seq_encode().
Returns:: Numpy array of expected log-densities, one per sequence.
Return type:: ndarray

compute_capabilities()[source]: Return compute-backend metadata for HMM scoring and Baum-Welch updates.

compute_declaration()[source]: Return the symbolic declaration for HMM chain, emission, and length statistics.

density(x)[source]

Returns the density of HMM for an observed sequence x.

See ‘HiddenMarkovDistribution.log_density()’ for details.

Parameters:: x (List[T]) – Observed sequence of HMM emissions.
Returns:: Density of HMM for observed sequence x.
Return type:: float

log_density(x)[source]

Returns the log-density of HMM for observed sequence x.

Density for a sequence of length N is given by recursively evaluating the conditional density,

p_mat(x_mat(0),x_mat(1),....,x_mat(t)) = p_mat(x_mat(t) given x_mat(0),...,x_mat(t-1)) = p_mat(x_mat(t) given Z(t)) * p_mat(Z(t) given Z(t-1)) * p_mat(Z(t-1) given x_mat(0),....,x_mat(t-1))

for t = 1,2,…,N-1. p_mat(Z(0)) is given by ‘w’, p_mat(x_mat(t)|Z(t)) is given by emission distribution ‘topics’ for t = 0,1,…,N-1.

The returned density is given by

p_mat(x_mat) = p_mat(x_mat(0),x_mat(1),….,x_mat(t))*P_len(N).

where P_len(N) is the length distribution ‘len_dist’, if assigned. Note: All calculations are done on the log scale with log-sum-exp used to prevent numerical underflow.

If ‘has_topics’ is true, ‘weighed_log_sum_exp’ and ‘log_sum’ calls from mixle.utils.vector are used to handle the emission distributions being treated as mixture distributions with weights ‘log_taus’.

Parameters:: x (List[T]) – Observed sequence of HMM emissions.
Returns:: Log-density of observed HMM sequence x.
Return type:: float

seq_log_density(x)[source]

Return one HMM log-density value per encoded observation sequence.

Impossible observation/state combinations are reported as -inf in the returned vector. Valid finite inputs should not produce NaN in the public result.

Parameters:: x (tuple[tuple[int, list[tuple[int, int]], list[ndarray], ndarray, ndarray, ndarray, Any], Any, Any | None] | tuple[tuple[ndarray, ndarray, ndarray], Any | None])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral forward scores for non-numba encoded HMM batches.

The compiled/numba encoding remains on the legacy NumPy path. The standard blocked encoding is converted through the active engine and composes child distribution-owned backend scores.

Parameters:

x (tuple[tuple[int, list[tuple[int, int]], list[ndarray], ndarray, ndarray, ndarray, Any], Any, Any | None] | tuple[tuple[ndarray, ndarray, ndarray], Any | None])
engine (Any)

Return type:

seq_posterior(x, filtered=False)[source]

Return per-sequence posterior state probabilities for encoded observations.

Each returned array holds the forward-backward SMOOTHING marginals P(z_t = k | x_1..T) (one row per position), matching every other seq_posterior in the package. Pass filtered=True for the forward-only filtered probabilities P(z_t = k | x_1..t).

Parameters:

x (tuple[tuple[ndarray, ndarray, ndarray], Any | None])
filtered (bool)

Return type:

list[ndarray] | None

viterbi(x)[source]

Return the most likely latent-state path for a single observation sequence.

The path is recovered by backpointer backtracking (max-product / Viterbi), so it is the jointly most probable state SEQUENCE – not the per-position argmax of the score matrix.

Parameters:: x (list[T])
Return type:: ndarray

latent_posterior(x)[source]

Return the exact chain posterior q(z | x) over hidden states for one observation sequence.

The returned MarkovChainLatentPosterior can .marginals() (forward-backward smoothing probabilities), .sample(rng) a full state path by FFBS, .mode() (the Viterbi path), or .entropy() (the exact chain entropy).

Parameters:: x (list[T])
Return type:: MarkovChainLatentPosterior

posterior_predictive(x, seed=None)[source]

Draw a new observation sequence conditioned on x.

Sample a full hidden-state path from the posterior q(z | x) by FFBS, then emit a fresh observation from each state’s emission distribution – “given the sequence I saw, draw a new sequence from the states it most likely passed through”. Returns a list the length of x.

Parameters:

x (list[T])
seed (int | None)

Return type:

list[Any]

seq_viterbi(x)[source]

Return maximum-likelihood hidden-state assignments for encoded sequences.

Each sequence’s assignment is its Viterbi path, recovered by backpointer backtracking. The result is indexed in the encoder’s flattened sequence layout (time-banded for the blocked encoding, sequence-contiguous for the numba encoding). Use the data encoder metadata to map flattened assignments back to individual sequences when working directly with encoded data.

Parameters:: x (tuple[tuple[int, list[tuple[int, int]], list[ndarray], ndarray, ndarray, ndarray, Any], Any, Any | None] | tuple[tuple[ndarray, ndarray, ndarray], Any | None])

to_fisher(**kwargs)[source]: Return a Fisher view backed by HMM forward-backward statistics.

density_semantics()[source]: Return joined density semantics over emissions and the optional length distribution.

sampler(seed=None)[source]

Create a sampler for hidden paths and emitted observations.

Sampling requires either a length distribution or terminal-state stopping behavior. When a length distribution is present, it should be a sequence-encodable distribution over nonnegative integers.

Parameters:: seed (int | None) – Optional seed for the sampler’s random state.
Returns:: A HiddenMarkovSampler configured with the model parameters.
Return type:: HiddenMarkovSampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this hidden Markov distribution.

Parameters:: pseudo_count (Optional[float]) – Prior mass used to smooth transition and emission statistics.
Returns:: Estimator configured with matching emission and length estimators.
Return type:: HiddenMarkovEstimator

decomposition()[source]

The HMM splits along its STATE axis (the per-state emission distributions).

Unlike a mixture this is NOT suff-stat-separable – the forward-backward couples all states across time – so the executor does not reduce it; instead the per-state emission scoring and accumulation (the dominant cost for rich emissions) are distributed inside the Baum-Welch E-step (host-shard mode, engine_axis=None), while the recursion stays serial. Exposing the axis lets the balance planner use the cluster for a massive HMM even on a single observation sequence.

dist_to_encoder()[source]

Return an encoder for HMM observation sequences and optional lengths.

Return type:: HiddenMarkovDataEncoder

enumerator()[source]

Return an enumerator over observation sequences in descending marginal probability order.

Return type:: HiddenMarkovModelEnumerator

determinize(max_states=1 << 16, max_denominator=10**9)[source]

Weighted determinization (Mohri 1997; Mohri & Riley 2002) of this terminal-value HMM into a DeterminizedSequenceDistribution.

Rebuilds the (possibly ambiguous) machine over belief states so each sequence has a single path and edge weights multiply to the exact marginal – giving exact, duplicate-free n-best sequences and sub-linear structural seek, where ranking the original HMM gives n-best paths. Float probabilities are rationalized (max_denominator) for decidable belief-equality. Requires terminal_values and finite/enumerable emissions; raises EnumerationError if not finitely determinizable within max_states (the twins property fails – keep the original HMM’s exact O(index) path instead).

Parameters:

max_states (int)
max_denominator (int)

quantized_count_index(quantizer, max_fine_bucket)[source]

BoundedCount for the MARGINAL HMM law: a forward count DP over the trellis with an iterative emission-split unrank, reaching a 2**M budget structurally.

log p(x) = logsumexp over latent paths. We count (state-path, observation) PAIRS by their joint cost log w_{s0} + sum_t log trans(s_t|s_{t-1}) + sum_t log emit_{s_t}(x_t): the forward DP pools paths into a per-(length, end-state) count histogram, where each step convolves the prefix histogram with the emission’s count index (choosing the emitted symbol). This is the HMM analogue of the Mixture bound – a conservative UPPER bound that does NOT deduplicate an observation produced by multiple paths and bins by the joint (dominant-path / tropical) cost rather than the exact logsumexp; every unranked value still carries its exact marginal log_density. Unranking is one iterative backward walk over t: each step does a local times-split (recover the emitted symbol + bucket split) and a plus-choice (recover the predecessor state) – O(L), no recursion. Falls back to capped enumerate-and-bin for non-plain HMMs (taus / terminal_values) or emissions that cannot count structurally.

Parameters:: max_fine_bucket (int)

is_canonical_copy(value, coarse_bin, quantizer)[source]

Stateless dedup: keep an observation only at its min-cost (canonical) path’s bin.

The structural index emits an observation once per state-path that can generate it; the canonical copy is the one at the minimal joint fine bucket. A min-plus forward pass over the trellis computes that minimum exactly (mirroring the count-index’s fine-bucket sums), so the check is O(L * n_states^2) with no state. Falls back to True for non-plain HMMs.

Parameters:: coarse_bin (int)
Return type:: bool

class HiddenMarkovEstimator(estimators, len_estimator=NullEstimator(), pseudo_count=(None, None), name=None, keys=(None, None, None), use_numba=None, prior=None, steady_state_init=False, terminal_states=None)[source]

Bases: ParameterEstimator

Estimator for HMM initial, transition, emission, and optional length distributions.

Parameters:

estimators (list[ParameterEstimator])
len_estimator (ParameterEstimator | None)
pseudo_count (float | tuple[float | None, float | None] | None)
name (str | None)
keys (tuple[str | None, str | None, str | None] | None)
use_numba (bool | None)
steady_state_init (bool)
terminal_states (set[int] | Sequence[int] | None)

accumulator_factory()[source]: Return a factory that accumulates Baum-Welch statistics for this estimator.

get_prior()[source]

Returns the chain conjugate prior in (init_prior, row_priors) form (or None).

Per-state emission component priors are owned by the topic estimators themselves.

set_prior(prior)[source]

Set the conjugate Dirichlet chain prior and flag whether it admits the conjugate update.

Parameters:: prior – (init_prior, row_priors) tuple or None; has_conj_prior is set when both the initial-state prior and all row priors are Dirichlet.
Return type:: None

model_log_density(model)[source]

Log-density of the model parameters under the priors (ELBO global term).

Sums the Dirichlet log-densities of the initial-state and transition probabilities (floored at a tiny constant so boundary MAP estimates score finitely) plus each topic estimator’s model_log_density of its emission distribution. Returns the emission-only sum without a conjugate chain prior.

Parameters:: model (HiddenMarkovModelDistribution) – Model to score.
Returns:: Prior log-density of the model parameters.
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate HiddenMarkovModel from aggregated sufficient statistics contained in arg ‘suff_stat’.

Sufficient statistics in arg ‘suff_stat’ are a Tuple containing:

suff_stat[0] (int): Number of hidden states.
suff_stat[1] (np.ndarray): Initial state counts.
suff_stat[2] (np.ndarray): State counts.
suff_stat[3] (np.ndarayy): State transition counts.
suff_stat[4] (List[T1]): List of Sufficient statistics for the emission distribution accumulators.
    Each having type S0.
suff_stat[5] (Optional[T2]): Optional sufficient statistics of the length distribution.

Note: T1 is the type for the sufficient statistics of the emission accumulators. T2 is the type for the length accumulator.

If pseudo_count[0] is not None, the initial counts in ‘suff_stat’ is re-weighted in estimation. If pseudo_count[1] is not None, the transition counts in ‘suff_stat’ are re-weighted in estimation.

Parameters:

nobs (Optional[float]) – Number of observations used in estimation.
suff_stat (tuple[int, ndarray, ndarray, ndarray, list[T1], T2 | None]) – See above for details.

Returns:

HiddenMarkovModelDistribution object.

Return type:

HiddenMarkovModelDistribution

class HiddenMarkovModelEnumerator(dist, topics=None, log_w=None, log_transitions=None, len_dist=None, path_root=None)[source]

Bases: DistributionEnumerator

Best-first enumerator over HMM observation sequences marginalized over hidden states.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
topics (Sequence[SequenceEncodableProbabilityDistribution] | None)
log_w (np.ndarray | None)
log_transitions (np.ndarray | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
path_root (str | None)

HiddenMarkovModelEstimator: alias of HiddenMarkovEstimator

class QuantizedHiddenMarkovModelDistribution(theta, levels, transition_exponents, emission_exponents, initial_exponents=None, init_mode='quantized', k_max=None, len_dist=NullDistribution(), name=None, terminal_values=None, use_numba=None, terminal_states=None, fit_diagnostics=None)[source]

Bases: HiddenMarkovModelDistribution

Hidden Markov model distribution with quantized observation summaries.

Parameters:

theta (float)
levels (Sequence[Any])
transition_exponents (Sequence[Sequence[int]] | np.ndarray)
emission_exponents (Sequence[Sequence[int]] | np.ndarray)
initial_exponents (Sequence[int] | np.ndarray | None)
init_mode (str)
k_max (int | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
terminal_values (set | None)
use_numba (bool | None)
terminal_states (set[int] | Sequence[int] | None)
fit_diagnostics (QuantizedHMMFitDiagnostics | None)

compute_declaration()[source]: Return the generated-compute declaration for the quantized HMM.

classmethod left_to_right(theta, levels, transition_exponents, emission_exponents, initial_exponents=None, **kwargs)[source]

Construct a left-to-right (upper-triangular) quantized HMM.

transition_exponents must be upper triangular: every entry strictly below the diagonal is a structural zero (negative exponent), so the hidden-state path is monotone non-decreasing (a Bakis chain). This makes a sentence’s state paths exactly its monotone segmentations – only polynomially many in the length (O(L^{n-1})) rather than the n^L of a general HMM – which bounds the path/sequence ambiguity. When the per-state emission supports are additionally disjoint the model is unambiguous (one path per sentence); then the structural descending-probability seek/unrank coincides with the exact marginal order (up to quantization granularity, no path over-count), which a general HMM’s structural seek cannot.

Raises:

ValueError – if transition_exponents is not square or not upper triangular.

Parameters:

theta (float)
levels (Sequence[Any])
transition_exponents (Sequence[Sequence[int]] | ndarray)
emission_exponents (Sequence[Sequence[int]] | ndarray)
initial_exponents (Sequence[int] | ndarray | None)
kwargs (Any)

Return type:

QuantizedHiddenMarkovModelDistribution

to_fisher(**kwargs)[source]: Forward-backward Fisher view for the quantized HMM.

estimator(pseudo_count=None)[source]

Return an estimator matching this quantized HMM configuration.

Parameters:: pseudo_count (Optional[float]) – Per-cell pseudo count for the initial, transition, and emission expected counts. When None, unobserved cells become structural zeros.
Returns:: QuantizedHiddenMarkovEstimator object.
Return type:: QuantizedHiddenMarkovEstimator

enumerator()[source]

Return an exact descending-probability enumerator over observation sequences.

For the ordinary (length-distribution) case this is the quantized-HMM-specialized enumerator, which avoids constructing per-state categorical streams and uses the cached quantized emission log-probability matrix directly. For the terminal_values stopping-time case it delegates to HiddenMarkovModelEnumerator, which implements that support (the quantized specialization only covers the length-distribution path).

determinize(max_states=1 << 16)[source]

Weighted determinization (Mohri 1997; Mohri & Riley 2002) of this terminal-value quantized HMM into a DeterminizedSequenceDistribution.

Rebuilds the machine over belief states (exact rational arithmetic) so each sequence has a single path and edge weights multiply to the exact marginal – yielding exact, duplicate-free n-best sequences (not n-best paths). Requires terminal_values. Raises EnumerationError if the belief expansion exceeds max_states (the twins property fails – not finitely determinizable; keep the original HMM’s exact O(index) enumerate-and-bin path instead).

Parameters:: max_states (int)

class QuantizedHiddenMarkovEstimator(num_states, levels=None, pseudo_count=None, k_max=None, fixed_theta=None, init_mode='quantized', len_estimator=NullEstimator(), name=None, keys=(None, None, None), use_numba=None, max_quant_its=50, split_collapsed=False, split_nats=math.log(2.0))[source]

Bases: ParameterEstimator

Estimate quantized hidden Markov models from accumulated sufficient statistics.

Parameters:

num_states (int)
levels (Sequence[Any] | None)
pseudo_count (float | None)
k_max (int | None)
fixed_theta (float | None)
init_mode (str)
len_estimator (ParameterEstimator | None)
name (str | None)
keys (tuple[str | None, str | None, str | None] | None)
use_numba (bool | None)
max_quant_its (int)
split_collapsed (bool)
split_nats (float)

accumulator_factory()[source]

Returns a HiddenMarkovAccumulatorFactory with categorical emission accumulators.

Return type:: HiddenMarkovAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a QuantizedHiddenMarkovModelDistribution from Baum-Welch expected counts.

Sufficient statistics in arg ‘suff_stat’ are the HiddenMarkovAccumulator value:: suff_stat[0] (int): Number of hidden states. suff_stat[1] (np.ndarray): Initial state counts. suff_stat[2] (np.ndarray): State counts. suff_stat[3] (np.ndarray): State transition counts. suff_stat[4] (Sequence[Dict[Any, float]]): Per-state categorical emission counts. suff_stat[5] (Optional[Any]): Optional sufficient statistics of the length distribution.

Parameters:

nobs (Optional[float]) – Number of observations used in estimation.
suff_stat (tuple[int, ndarray, ndarray, ndarray, Sequence[dict[Any, float]], Any | None]) – See above for details.

Returns:

QuantizedHiddenMarkovModelDistribution object.

Return type:

QuantizedHiddenMarkovModelDistribution

class QuantizedHiddenMarkovModelEnumerator(dist)[source]

Bases: DistributionEnumerator

Exact best-first enumerator specialized for QuantizedHiddenMarkovModelDistribution.

Parameters:: dist (QuantizedHiddenMarkovModelDistribution)

QuantizedHiddenMarkovModelEstimator: alias of QuantizedHiddenMarkovEstimator

class HierarchicalMixtureDistribution(topics, mixture_weights, topic_weights, len_dist=NullDistribution(), name=None, keys=(None, None))[source]

Bases: SequenceEncodableProbabilityDistribution

Outer mixture over sequence mixtures with shared topic distributions.

Data type: Sequence[T], where T is the data type of the topic distributions.

Parameters:

topics (Sequence[SequenceEncodableProbabilityDistribution])
mixture_weights (list[float] | ndarray)
topic_weights (list[list[float]] | ndarray)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
keys (tuple[str | None, str | None] | None)

compute_capabilities()[source]: Declare generated-compute support inherited from topics and length model.

compute_declaration()[source]: Return the generated-compute declaration for the hierarchical mixture.

density(x)[source]

Evaluate the density of an observation from hierarchical mixture distribution.

Parameters:: x (Sequence[T]) – A sequence of type data type T’s.
Returns:: Density evaluated at x.
Return type:: float

log_density(x)[source]

Evaluate the log density of an observation from hierarchical mixture distribution.

Note: Observation is a sequence.

Parameters:: x (Sequence[T]) – A sequence of type data type T’s.
Returns:: Log-density evaluated at x.
Return type:: float

posterior(x)[source]

Compute the posterior over the mixture components for the outer-mixture at observed value x.

Parameters:: x (Sequence[T]) – An observed sequence of data type T.
Returns:: Numpy array of length ‘num_mixtures’.
Return type:: ndarray

component_log_density(x)[source]

Evaluate the component-wise log-density for an observation from a hierarchical mixture model.

Parameters:: x (Sequence[T]) – An observation from a hierarchical mixture model.
Returns:: Numpy array length of ‘num_mixtures’.
Return type:: ndarray

to_mixture()[source]

Return the equivalent flat mixture of sequence distributions.

Return type:: MixtureDistribution

seq_component_log_density(x)[source]

Vectorized evaluation of the outer-mixture component-wise log-density for an encoded sequence x.

This returns a numpy array with shape (rv[0], ‘num_mixtures’).

Note: This density is a Mixture of Sequence of Mixture, so the data must be bin-counted as last step in code.

Encoded sequence ‘x’ is a Tuple of length 5 containing:: x[0] (int): Number of independent observations. x[1] (ndarray[int]): Observation sequence index for each value in flattened x. x[2] (ndarray[int]): Length of each observation in x. x[3] (E): Encoded sequence of flattened observed values (has type E). x[4] (Optional[E2]): Encoded sequence of lengths (has type E2).

Parameters:

x (tuple[int, ndarray, ndarray, E1, E2 | None]) – Encoded sequence of iid hierarchical mixture model observations.

Returns:

Numpy array of dimensions ‘rv[0]’ by ‘num_mixtures’, containing the log-density for each component of the: outer mixture.

Return type:

seq_log_density(x)[source]

Vectorized evaluation of the log-density for an encoded sequence of observations in x.

Encoded sequence ‘x’ is a Tuple of length 5 containing:: x[0] (int): Number of independent observations. x[1] (ndarray[int]): Observation sequence index for each value in flattened x. x[2] (ndarray[int]): Length of each observation in x. x[3] (E): Encoded sequence of flattened observed values (has type E). x[4] (Optional[E2]): Encoded sequence of lengths (has type E2).

Parameters:: x (tuple[int, ndarray, ndarray, E1, E2 | None]) – Encoded sequence of observations of hierarchical mixture model.
Returns:: Log-density evaluated at each observation in the encoded sequence x.
Return type:: ndarray

backend_seq_component_log_density(x, engine)[source]

Engine-neutral outer-component log densities for hierarchical-mixture encoded sequences.

Parameters:

x (tuple[int, ndarray, ndarray, E1, E2 | None])
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral hierarchical-mixture log-density for encoded sequences.

Parameters:

x (tuple[int, ndarray, ndarray, E1, E2 | None])
engine (Any)

Return type:

seq_posterior(x)[source]

Vectorized evaluation of the posterior over each outer-mixture component for an encoded sequence x.

Encoded sequence ‘x’ is a Tuple of length 5 containing:: x[0] (int): Number of independent observations. x[1] (ndarray[int]): Observation sequence index for each value in flattened x. x[2] (ndarray[int]): Length of each observation in x. x[3] (E): Encoded sequence of flattened observed values (has type E). x[4] (Optional[E2]): Encoded sequence of lengths (has type E2).

Parameters:: x (tuple[int, ndarray, ndarray, E1, E2 | None]) – See above for details.
Returns:: Numpy array of dimension (x[0], ‘num_mixtures’).
Return type:: ndarray

to_fisher(**kwargs)[source]: Reuse the equivalent flat mixture’s Fisher view.

density_semantics()[source]: Return exact-or-approximate density semantics joined from child models.

sampler(seed=None)[source]

Return a sampler for this hierarchical mixture.

Parameters:: seed (int | None)
Return type:: HierarchicalMixtureSampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this hierarchical mixture.

Parameters:: pseudo_count (Optional[float]) – Prior mass used to smooth mixture and topic weights during estimation.
Returns:: Estimator configured with matching topic and length estimators.
Return type:: HierarchicalMixtureEstimator

dist_to_encoder()[source]

Return a data encoder for iid hierarchical-mixture observations.

Return type:: HierarchicalMixtureDataEncoder

enumerator()[source]

Returns a HierarchicalMixtureEnumerator iterating sequences in descending probability order.

Return type:: HierarchicalMixtureEnumerator

class HierarchicalMixtureEstimator(estimators, num_mixtures, len_estimator=NullEstimator(), len_dist=None, suff_stat=None, pseudo_count=None, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

Estimate hierarchical-mixture distributions from sufficient statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
num_mixtures (int)
len_estimator (ParameterEstimator | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
suff_stat (ndarray | None)
pseudo_count (float | None)
name (str | None)
keys (tuple[str | None, str | None] | None)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: HierarchicalMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a hierarchical mixture from aggregated sufficient statistics.

suff_stat is a four-item tuple containing:

suff_stat[0] (ndarray[float]): Aggregated token-level component counts with shape
    (num_mixtures, num_topics). Row-normalized into the topic weights taus.
suff_stat[1] (ndarray[float]): Aggregated document-level outer-posterior sums with length
    num_mixtures. Normalized into the outer weights w -- the EM maximizer for w
    is the document-level posterior sum, NOT the (length-weighted) token-level row sums.
suff_stat[2] (Tuple[SS1,...]): One sufficient-statistic value per topic.
suff_stat[3] (Optional[SS2]): Sufficient statistics for the length estimator.

Parameters:

nobs (Optional[float]) – Number of observations used in accumulation of ‘suff_stat’.
suff_stat (tuple[ndarray, ndarray, SS1, SS2 | None]) – See above for details.

Returns:

Estimated distribution.

Return type:

HierarchicalMixtureDistribution

class HierarchicalMixtureEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates the support of a HierarchicalMixtureDistribution in descending probability order.

Parameters:: dist (HierarchicalMixtureDistribution)

class IndianBuffetProcessDistribution(num_features, alpha=1.0, beta_params=None, feature_probs=None, min_prob=1.0e-128, name=None, keys=None, data_format='auto')[source]

Bases: SequenceEncodableProbabilityDistribution

Finite-truncated Indian buffet process over binary feature rows.

Parameters:

num_features (int) – Truncation level K.
alpha (float) – IBP concentration parameter.
beta_params (Sequence[Sequence[float]] | ndarray | None) – Optional (K, 2) variational Beta parameters for q(pi_k). If omitted, the prior Beta(alpha / K, 1) is used.
feature_probs (Sequence[float] | ndarray | None) – Optional plug-in feature probabilities. When supplied without beta_params, a lightweight Beta posterior with matching mean is created for expected-log-density calls.
min_prob (float) – Minimum plug-in probability used when feature_probs are given.
name (str | None) – Optional distribution name.
keys (str | None) – Optional key for tying sufficient statistics.
data_format (str) – ‘dense’, ‘sparse’, or ‘auto’ input interpretation.

classmethod compute_capabilities()[source]: Declare generic table-kernel capabilities for finite IBP rows.

classmethod compute_declaration()[source]: Return the structured declaration for finite IBP parameters and statistics.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (Any)
Return type:: float

density_semantics()[source]: Return that plug-in densities use posterior mean feature probabilities.

log_density(x)[source]

Plug-in log-density of one feature row using E_q[pi_k].

Parameters:: x (Any)
Return type:: float

expected_log_density(x)[source]

VB expected log-density E_q[log p(z | pi)] for one observed row.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized plug-in log-density for encoded feature rows.

Parameters:

x (ndarray)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked finite-IBP parameters for equal-feature mixtures.

Parameters:

dists (Sequence[IndianBuffetProcessDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of finite-IBP component log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked legacy (feature_counts, total_count, alpha) statistics.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

seq_expected_log_density(x)[source]

Return vectorized expected log-density values for encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

seq_local_elbo(x)[source]

Per-row VB contribution; rows are observed, so there is no local entropy.

Parameters:: x (ndarray)
Return type:: ndarray

enumerator()[source]

Enumerate feature rows in descending probability order.

The plug-in row density factorizes over features – log p(z) = sum_k [z_k log pi_k + (1-z_k) log(1-pi_k)] with pi_k = E_q[feature_probs] – so the truncated IBP row is a product of independent Bernoulli features and enumerates by best-first over the per-feature supports (the same structure as the Erdos-Renyi graph). Rows are emitted in the configured data_format (a dense 0/1 list, or a sorted list of active feature indices when sparse), each carrying its exact log_density.

Return type:: DistributionEnumerator

to_fisher(**kwargs)[source]: Return this distribution’s own Fisher view.

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: IndianBuffetProcessSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: IndianBuffetProcessEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: IndianBuffetProcessDataEncoder

class IndianBuffetProcessEstimator(num_features, alpha=1.0, pseudo_count=None, suff_stat=None, estimate_alpha=True, min_alpha=1.0e-12, max_alpha=1.0e12, min_prob=1.0e-128, name=None, keys=None, data_format='auto')[source]

Bases: ParameterEstimator

Variational Bayes estimator for the finite-truncated IBP.

pseudo_count follows the convention used by other mixle.stats Bernoulli estimators: if suff_stat is supplied, it is treated as a prior probability vector and re-weighted by pseudo_count; otherwise pseudo_count is centered at the IBP prior mean alpha / (alpha + K).

Parameters:

num_features (int)
alpha (float)
pseudo_count (float | None)
suff_stat (Sequence[float] | ndarray | None)
estimate_alpha (bool)
min_alpha (float)
max_alpha (float)
min_prob (float)
name (str | None)
keys (str | None)
data_format (str)

accumulator_factory()[source]

Return a factory for finite IBP sufficient-statistic accumulators.

Return type:: IndianBuffetProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Update the variational Beta posterior and optional concentration parameter.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, float, float | None])

Return type:

IndianBuffetProcessDistribution

model_log_density(model)[source]

Global VB term E_q[log p(pi | alpha)] + H[q(pi)].

Parameters:: model (IndianBuffetProcessDistribution)
Return type:: float

class IntegerChowLiuTreeDistribution(dependency_list, conditional_log_densities, feature_order=None, name=None, keys=None, pseudo_count=None, enumeration_item_budget=_DEFAULT_ENUMERATION_ITEM_BUDGET)[source]

Bases: SequenceEncodableProbabilityDistribution

Integer Chow-Liu tree distribution factorizing a joint over fixed-length integer vectors along a tree.

Data type: Union[Sequence[int], np.ndarray] (fixed-length vector of non-negative integers).

Parameters:

dependency_list (list[int | None])
conditional_log_densities (Sequence[float] | ndarray)
feature_order (Sequence[int] | None)
name (str | None)
keys (str | None)
pseudo_count (float | None)
enumeration_item_budget (int | None)

classmethod compute_capabilities()[source]: Declare backend support for integer Chow-Liu generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the integer Chow-Liu tree.

density(x)[source]

Density of integer Chow-Liu tree distribution at observation x.

See log_density() for details.

Parameters:: x (Union[Sequence[int], np.ndarray]) – Fixed-length vector of non-negative integers.
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of integer Chow-Liu tree distribution at observation x.

Sums the conditional log-densities of each feature given its parent in the dependency tree (the root feature contributes its marginal log-density).

Parameters:: x (Union[Sequence[int], np.ndarray]) – Fixed-length vector of non-negative integers.
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (np.ndarray) – 2-d numpy array of N integer vectors with num_features columns.
Returns:: Numpy array of log-density (float) of length N.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized table lookup for fixed integer tree factors.

Parameters:

x (ndarray)
engine (Any)

Return type:

sampler(seed=None)[source]

Create a sampler for this integer Chow-Liu tree distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: Sampler bound to this distribution.
Return type:: IntegerChowLiuTreeSampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this integer Chow-Liu tree distribution.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: Estimator configured with the same feature count and state count.
Return type:: IntegerChowLiuTreeEstimator

dist_to_encoder()[source]

Return a data encoder for integer Chow-Liu tree observations.

Return type:: IntegerChowLiuTreeDataEncoder

enumerator(max_items=None)[source]

Returns IntegerChowLiuTreeEnumerator iterating fixed-length integer vectors in descending probability order.

Parameters:: max_items (int | None)
Return type:: IntegerChowLiuTreeEnumerator

support_size()[source]

Return the finite Cartesian event-space size.

Return type:: int

class IntegerChowLiuStatistics(num_features, num_states, counts, marginal_counts)[source]

Bases: NamedTuple

Versioned, tuple-compatible integer Chow–Liu statistics.

Parameters:

num_features (int)
num_states (int)
counts (ndarray)
marginal_counts (ndarray)

num_features: int: Alias for field number 0

num_states: int: Alias for field number 1

counts: ndarray: Alias for field number 2

marginal_counts: ndarray: Alias for field number 3

property schema_version: int: Return the serialized statistic schema version.

class IntegerChowLiuTreeEstimator(num_features=None, num_states=None, pseudo_count=None, suff_stat=None, keys=None, name=None, enumeration_item_budget=_DEFAULT_ENUMERATION_ITEM_BUDGET)[source]

Bases: ParameterEstimator

Estimator for the IntegerChowLiuTreeDistribution. Learns the dependency tree with the Chow-Liu algorithm.

Parameters:

num_features (int | None)
num_states (int | None)
pseudo_count (float | None)
suff_stat (Any | None)
keys (str | None)
name (str | None)
enumeration_item_budget (int | None)

accumulator_factory()[source]: Return an accumulator factory configured from this estimator.

estimate(nobs, suff_stat)[source]

Estimate an IntegerChowLiuTreeDistribution from sufficient statistics via the Chow-Liu algorithm.

Pairwise mutual information is computed from the (optionally smoothed) joint and marginal counts, a maximum mutual information spanning tree is extracted, and conditional densities are computed along the tree rooted at feature 0.

Parameters:

nobs (Optional[float]) – Number of observations (unused).
suff_stat (Tuple[int, int, np.ndarray, np.ndarray]) – Tuple of number of features, number of states, pairwise joint counts, and marginal counts.

Returns:

IntegerChowLiuTreeDistribution object.

class IntegerChowLiuTreeEnumerator(dist, max_items=_DEFAULT_ENUMERATION_ITEM_BUDGET)[source]

Bases: DistributionEnumerator

Enumerates the finite support of an integer Chow-Liu tree.

Parameters:

dist (IntegerChowLiuTreeDistribution)
max_items (int | None)

property receipt: dict[str, object]: Return enumeration budget and progress metadata.

class IgnoredDistribution(dist, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Fixed-parameter wrapper that delegates the wrapped distribution’s likelihood exactly.

Parameters:

dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)

compute_capabilities()[source]: Return the compute capabilities delegated from the wrapped distribution.

compute_declaration()[source]: Return a declaration that marks this wrapper as carrying no estimable statistics.

get_prior()[source]

Delegate to the wrapped distribution’s get_prior (Ignored owns no prior).

Return type:: Any

set_prior(prior)[source]

Delegate to the wrapped distribution’s set_prior; None keeps existing behavior.

Parameters:: prior (Any)
Return type:: None

expected_log_density(x)[source]

Delegate prior-expected log-density to the wrapped distribution.

Parameters:: x (T)
Return type:: float

seq_expected_log_density(x)[source]

Delegate vectorized prior-expected log-density to the wrapped distribution.

Parameters:: x (E)
Return type:: ndarray

density(x)[source]

Evaluate the density of the IgnoredDistribution at x.

Parameters:: x (T) – Type corresponding to attribute ‘dist’.
Returns:: Density of attribute ‘dist’ at x
Return type:: float

log_density(x)[source]

Evaluate the log-density of the IgnoredDistribution at x.

Parameters:: x (T) – Type corresponding to attribute ‘dist’.
Returns:: log-density of attribute ‘dist’ at x.

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (E)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density delegated to the wrapped distribution.

Parameters:

x (E)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child parameters for homogeneous ignored-wrapper mixtures.

Parameters:

dists (Sequence[IgnoredDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of delegated child log densities.

Parameters:

x (E)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return empty legacy statistics for each ignored component.

Parameters:

x (E)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: IgnoredSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: IgnoredEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: IgnoredDataEncoder

class IgnoredEstimator(dist=None, pseudo_count=None, suff_stat=None, keys=None, name=None)[source]

Bases: ParameterEstimator

Estimator that returns the wrapped distribution unchanged inside an ignored wrapper.

Parameters:

dist (SequenceEncodableProbabilityDistribution | None)
pseudo_count (float | None)
suff_stat (Any | None)
keys (str | None)
name (str | None)

accumulator_factory()[source]: Return a factory that creates no-op ignored accumulators.

get_prior()[source]

Delegate to the wrapped distribution’s get_prior (Ignored estimates nothing of its own).

Return type:: Any

set_prior(prior)[source]

Delegate to the wrapped distribution’s set_prior; None keeps existing behavior.

Parameters:: prior (Any)
Return type:: None

estimate(nobs, suff_stat)[source]

Return the wrapped distribution unchanged inside IgnoredDistribution.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

IgnoredDistribution

class IntegerBernoulliEditDistribution(log_edit_pmat, init_dist=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Bernoulli edit set distribution: each integer independently transitions in/out between two sets.

Parameters:

log_edit_pmat (Sequence[tuple[float, float]] | ndarray)
init_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare backend support for integer Bernoulli-edit generated kernels.

density(x)[source]

Density of the Bernoulli edit set distribution at observation x.

See log_density() for details.

Parameters:: x (Tuple[Sequence[int], Sequence[int]]) – Observed (prev set, next set) pair of integer sets.
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of the joint observation (x[0], x[1]).

Computes log p(x[1] | x[0]) by summing per-integer edit log-probabilities for kept, added, and removed elements, plus log p(x[0]) under init_dist.

Parameters:: x (Tuple[Sequence[int], Sequence[int]]) – Observed (prev set, next set) pair of integer sets.
Returns:: Log-density at observation x.
Return type:: float

conditional_log_density(previous, next_set)[source]

Return log p(next_set | previous) without an initial-law factor.

Parameters:

previous (Sequence[int] | ndarray)
next_set (Sequence[int] | ndarray)

Return type:

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (E) – Sequence encoded (prev set, next set) observations from IntegerBernoulliEditDataEncoder.seq_encode().
Returns:: Numpy array of log-density values, one per encoded observation.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded integer edit-set observations.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, tuple[ndarray, ndarray, ndarray], E1 | None])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked integer edit-set parameters for shared support and init policy.

Parameters:

dists (Sequence[IntegerBernoulliEditDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of integer edit-set component log densities.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, tuple[ndarray, ndarray, ndarray], E1 | None])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy (edit_counts, total_weight, init_stat) statistics.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, tuple[ndarray, ndarray, ndarray], E1 | None])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

sampler(seed=None)[source]

Create a sampler for this integer Bernoulli edit distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: Sampler bound to this distribution.
Return type:: IntegerBernoulliEditSampler

estimator(pseudo_count=None)[source]

Create an IntegerBernoulliEditEstimator with matching num_vals.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight sufficient statistics in estimation.
Returns:: Estimator configured with matching support size.
Return type:: IntegerBernoulliEditEstimator

dist_to_encoder()[source]

Return a data encoder for integer Bernoulli edit observations.

Return type:: IntegerBernoulliEditDataEncoder

enumerator()[source]

Returns IntegerBernoulliEditEnumerator iterating set-pairs in descending probability order.

Return type:: IntegerBernoulliEditEnumerator

exception IntegerBernoulliEditFitError[source]

Bases: RuntimeError

Raised when edit statistics do not identify a valid transition law.

class IntegerBernoulliEditEstimator(num_vals=MISSING, init_estimator=None, min_prob=1.0e-128, pseudo_count=None, suff_stat=None, name=None, keys=None, num_values=MISSING)[source]

Bases: ParameterEstimator

Estimate integer Bernoulli edit distributions from aggregated sufficient statistics.

Parameters:

num_vals (int)
init_estimator (ParameterEstimator | None)
min_prob (float)
pseudo_count (float | None)
suff_stat (ndarray | None)
name (str | None)
keys (str | None)
num_values (int)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: IntegerBernoulliEditAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an IntegerBernoulliEditDistribution from aggregated sufficient statistics.

Parameters:

nobs (Optional[float]) – Unused (kept for protocol consistency).
suff_stat (Tuple[np.ndarray, float, Optional[SS1]]) – Edit counts, total weight, and init suff stats.

Returns:

IntegerBernoulliEditDistribution object.

Return type:

IntegerBernoulliEditDistribution

class IntegerBernoulliEditEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates finite previous/next integer-set pairs in descending probability order.

Parameters:: dist (IntegerBernoulliEditDistribution)

class IntegerStepBernoulliEditDistribution(log_edit_pmat, init_dist=None, name=None, keys=None)[source]

Bases: IntegerBernoulliEditDistribution

Step Bernoulli edit set distribution: each integer independently transitions in/out between two sets.

Identical in form to IntegerBernoulliEditDistribution; only the estimator (a two-level step fit) differs.

Parameters:

log_edit_pmat (Sequence[tuple[float, float]] | ndarray)
init_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
keys (str | None)

sampler(seed=None)[source]

Create a sampler for this integer step Bernoulli edit distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: Sampler bound to this distribution.
Return type:: IntegerStepBernoulliEditSampler

estimator(pseudo_count=None)[source]

Create an IntegerStepBernoulliEditEstimator with matching num_vals.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight sufficient statistics in estimation.
Returns:: Estimator configured with matching support size.
Return type:: IntegerStepBernoulliEditEstimator

dist_to_encoder()[source]

Return a data encoder for integer step Bernoulli edit observations.

Return type:: IntegerStepBernoulliEditDataEncoder

enumerator()[source]

Returns IntegerStepBernoulliEditEnumerator iterating set-pairs in descending probability order.

Return type:: IntegerStepBernoulliEditEnumerator

class IntegerStepBernoulliEditEstimator(num_vals=MISSING, init_estimator=None, min_prob=1.0e-128, pseudo_count=None, suff_stat=None, name=None, keys=None, num_values=MISSING)[source]

Bases: IntegerBernoulliEditEstimator

Estimate integer step Bernoulli edit distributions with a two-level edit-probability fit.

Parameters:

num_vals (int)
init_estimator (ParameterEstimator | None)
min_prob (float)
pseudo_count (float | None)
suff_stat (ndarray | None)
name (str | None)
keys (str | None)
num_values (int)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: IntegerStepBernoulliEditAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an IntegerStepBernoulliEditDistribution from aggregated sufficient statistics.

Per-element edit probabilities are estimated as in the non-step edit estimator, then the addition and removal probabilities are each replaced by a two-level step-function fit.

Parameters:

nobs (Optional[float]) – Unused (kept for protocol consistency).
suff_stat (Tuple[np.ndarray, float, Optional[SS1]]) – Edit counts, total weight, and init suff stats.

Returns:

IntegerStepBernoulliEditDistribution object.

Return type:

IntegerStepBernoulliEditDistribution

class IntegerStepBernoulliEditEnumerator(dist)[source]

Bases: IntegerBernoulliEditEnumerator

Enumerates finite previous/next integer-set pairs for the step edit-set distribution.

Parameters:: dist (IntegerBernoulliEditDistribution)

class IntegerHiddenAssociationDistribution(state_prob_mat, cond_weights, alpha=0.0, prev_dist=NullDistribution(), len_dist=NullDistribution(), name=None, keys=(None, None), use_numba=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Integer hidden association model: words of a second set are emitted through hidden states conditioned on words of a first set.

Parameters:

state_prob_mat (list[list[float]] | ndarray)
cond_weights (list[list[float]] | ndarray)
alpha (float)
prev_dist (SequenceEncodableProbabilityDistribution | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
keys (tuple[str | None, str | None])
use_numba (bool | None)

compute_capabilities()[source]: Return backend capability metadata for this concrete integer association model.

compute_declaration()[source]: Return the generated-compute declaration for integer hidden association.

log_density(x)[source]

Log-density of the integer hidden association model at observation x.

For each emitted word in x[1], marginalizes over the given words in x[0] (weighted by count) and the hidden states, mixing with a uniform density with probability alpha. Adds the log-density of x[0] under prev_dist and of the total emission count under len_dist.

Parameters:: x (Tuple[List[Tuple[int, float]], List[Tuple[int, float]]]) – Grouped-count observation ([(S1 word, count)], [(S2 word, count)]).
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (E) – Sequence encoded observations from IntegerHiddenAssociationDataEncoder.seq_encode(). Uses the numba kernel when the encoding was produced with use_numba=True.
Returns:: Numpy array of log-density values, one per encoded observation.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Evaluate encoded log-densities using a backend-neutral compute engine.

Parameters:

x (tuple[tuple[list[tuple[ndarray, ...]], E2 | None, E1 | None], None] | tuple[None, tuple[tuple[ndarray, ...], E1 | None, E2 | None]])
engine (Any)

Return type:

conditional_word_log_probs(s1)[source]

Log of the per-emission word distribution q(.|S1) for a given S1 bag, or None if empty.

q(w|S1) = (1-alpha) * sum_u (c_u/n1) * sum_s cond_weights[u,s] * state_prob_mat[s,w] + alpha/W – the smoothed mixture the model uses to score each emitted word. Returns None for an empty S1 (n1 = 0), whose conditional is degenerate (the model’s own density is undefined there).

Parameters:: s1 (list[tuple[int, float]])
Return type:: ndarray | None

enumerator()[source]

Enumerate (S1, S2) observations in descending probability order.

The model factors as prev_dist(S1) * [prod_w q(w|S1)^{c_w}] * P_len(n2): the emitted bag S2 is a trial-count multinomial whose word distribution q(.|S1) depends on the given bag S1. Enumeration is a conditional product – the outer stream enumerates S1 from prev_dist and, for each S1, the inner stream enumerates S2 by the multinomial bag search under len_dist, merged by descending total score with prev_dist(S1) as the outer frontier bound. Requires an enumerable, non-null prev_dist so the S1 support is defined.

Return type:: DistributionEnumerator

sampler(seed=None)[source]

Return a sampler for iid integer hidden-association observations.

Requires non-null prev_dist and len_dist.

Parameters:: seed (int | None) – Optional random seed.
Returns:: A configured integer hidden-association sampler.
Return type:: IntegerHiddenAssociationSampler

estimator(pseudo_count=None)[source]

Return an estimator with matching dimensions and child estimators.

Parameters:: pseudo_count (float | None) – Unused; accepted for protocol consistency.
Returns:: A configured integer hidden-association estimator.
Return type:: IntegerHiddenAssociationEstimator

dist_to_encoder()[source]

Return an encoder for integer hidden-association observations.

Return type:: IntegerHiddenAssociationDataEncoder

class IntegerHiddenAssociationEstimator(num_vals, num_states, alpha=0.0, prev_estimator=NullEstimator(), len_estimator=NullEstimator(), suff_stat=None, pseudo_count=None, use_numba=None, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

Estimator for integer hidden-association distributions.

Parameters:

num_vals (list[int] | tuple[int, int] | int)
num_states (int)
alpha (float)
prev_estimator (ParameterEstimator | None)
len_estimator (ParameterEstimator | None)
suff_stat (Any | None)
pseudo_count (float | None)
use_numba (bool | None)
name (str | None)
keys (tuple[str | None, str | None] | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: IntegerHiddenAssociationAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an IntegerHiddenAssociationDistribution from aggregated sufficient statistics.

Parameters:

nobs (Optional[float]) – Number of observations, passed to the prev and length estimators.
suff_stat (Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[SS1], Optional[SS2]]) – Init counts, weight counts, state counts, prev suff stats, and size suff stats.

Returns:

IntegerHiddenAssociationDistribution object.

Return type:

IntegerHiddenAssociationDistribution

class IntegerMarkovChainDistribution(num_values, cond_dist, lag=1, init_dist=NullDistribution(), len_dist=NullDistribution(), keys=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Markov-chain distribution over integer-valued states.

Parameters:

num_values (int)
cond_dist (list[list[float]] | ndarray)
lag (int)
init_dist (SequenceEncodableProbabilityDistribution | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
keys (str | None)
name (str | None)

compute_capabilities()[source]: Declare generated-compute support inherited from initial and length distributions.

compute_declaration()[source]: Return the generated-compute declaration for the integer Markov chain.

density_semantics()[source]: Classify missing initial/length laws as conditional likelihood factors.

density(x)[source]

Density of integer Markov chain evaluated at x.

See log_density() for details.

Parameters:: x (Sequence[int]) – An integer markov chain observation.
Returns:: Density evaluated at x.
Return type:: float

log_density(x)[source]

Log-density of integer Markov chain evaluated at x.

The initial child scores exactly the first lag states, each later state is scored by its lag-indexed transition row, and the length child scores the actual sequence length. Shorter observations are rejected.

Parameters:: x (Sequence[int]) – An integer markov chain observation.
Returns:: Log-density evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at every observation in encoded sequence.

See log_density() for details on likelihood evaluation.

Sequence encoded arg ‘x’ is a Tuple of length 7 containing:: seq_len (ndarray[int]): Actual observed sequence lengths. init_idx (ndarray[int]): Observed sequence index of chains with lengths >= lag. seq_idx (ndarray[int]): Observed sequence index of chains with transitions. u_seq_idx (ndarray[object]): Numpy array of tuples containing the unique transitions. u_seq_values (ndarray[object]): Numpy array of tuples containing the transitions. init_enc (Optional[E]): Sequence encoding of initial values (has type E). len_enc (Optional[E2]): Sequence encoding of length values (has type E2).

Parameters:: x (tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, E1 | None, E2 | None]) – See above for details.
Returns:: Log-density evaluated at each observation in encoded sequence.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for grouped integer Markov-chain encodings.

Parameters:

x (tuple[ndarray, ndarray, ndarray, ndarray, ndarray, E1 | None, E2 | None])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked integer Markov-chain parameters for shared support/lag.

Parameters:

dists (Sequence[IntegerMarkovChainDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of integer Markov-chain log densities.

Parameters:

x (tuple[ndarray, ndarray, ndarray, ndarray, ndarray, E1 | None, E2 | None])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component versioned fixed-support sufficient statistics.

Parameters:

x (tuple[ndarray, ndarray, ndarray, ndarray, ndarray, E1 | None, E2 | None])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

sampler(seed=None)[source]

Return a sampler for this integer Markov chain.

Parameters:: seed (int | None)
Return type:: IntegerMarkovChainSampler

transition_sampler(seed=None)[source]

Return a sampler exposing only sample_given for conditional transition use.

Parameters:: seed (int | None)
Return type:: IntegerMarkovChainSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this integer Markov chain.

Parameters:: pseudo_count (float | None)

dist_to_encoder()[source]

Return a data encoder for iid integer Markov-chain observations.

Return type:: IntegerMarkovChainDataEncoder

enumerator()[source]

Returns IntegerMarkovChainEnumerator iterating integer sequences in descending probability order.

Return type:: IntegerMarkovChainEnumerator

class IntegerMarkovChainEstimator(num_values, lag=1, init_estimator=NullEstimator(), len_estimator=NullEstimator(), init_dist=None, len_dist=None, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate integer Markov-chain transition probabilities and child models.

Parameters:

num_values (int)
lag (int)
init_estimator (ParameterEstimator | None)
len_estimator (ParameterEstimator | None)
init_dist (SequenceEncodableProbabilityDistribution | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
pseudo_count (float | None)
name (str | None)
keys (str | None)

get_prior()[source]

Returns the implicit per-row symmetric-Dirichlet prior pseudo_count induces, or None.

pseudo_count smoothing (cond_mat += pseudo_count before row-normalizing in estimate()) is the exact MAP point estimate under an independent SymmetricDirichletDistribution(pseudo_count + 1) prior on each row of the conditional matrix – see model_log_density(). Lets mixle.inference.estimation.optimize() auto-detect the 'map' objective instead of silently tracking plain (unpenalized) MLE for a pseudo-count-regularized fit.

model_log_density(model)[source]

Log-density of the fitted conditional matrix under the implicit row prior (see get_prior()), plus init_dist/len_dist’s own model_log_density when the estimator that actually fit them (rather than a fixed, caller-supplied distribution) exposes one. Returns 0.0 (a plain MLE fit) when pseudo_count is None.

Parameters:: model (IntegerMarkovChainDistribution)
Return type:: float

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: IntegerMarkovChainAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an integer Markov-chain distribution from versioned sufficient statistics.

Parameters:

nobs (Optional[float]) – Number of observations used in aggregation of ‘suff_stat’.
suff_stat (IntegerMarkovChainStatistics) – See above for details.

Returns:

IntegerMarkovChainDistribution object.

Return type:

IntegerMarkovChainDistribution

class IntegerMarkovChainEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates integer Markov-chain sequences in descending probability order.

Parameters:: dist (IntegerMarkovChainDistribution)

class IntegerMarkovChainStatistics(schema_version, num_values, lag, transition_counts, initial_nobs, initial, length_nobs, length)[source]

Bases: NamedTuple

Immutable sufficient statistics for one fixed integer-chain support.

Parameters:

schema_version (int)
num_values (int)
lag (int)
transition_counts (tuple[tuple[tuple[int, ...], int, float], ...])
initial_nobs (float)
initial (Any | None)
length_nobs (float)
length (Any | None)

schema_version: int: Alias for field number 0

num_values: int: Alias for field number 1

lag: int: Alias for field number 2

transition_counts: tuple[tuple[tuple[int, ...], int, float], ...]: Alias for field number 3

initial_nobs: float: Alias for field number 4

initial: Any | None: Alias for field number 5

length_nobs: float: Alias for field number 6

length: Any | None: Alias for field number 7

exception NonGenerativeIntegerMarkovChainError[source]

Bases: TypeError

Raised when a conditional integer-chain factor is asked to generate sequences.

class IntegerProbabilisticLatentSemanticIndexingDistribution(state_word_mat, doc_state_mat, doc_vec, len_dist=NullDistribution(), name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Integer-valued probabilistic latent semantic indexing distribution.

Parameters:

state_word_mat (list[list[float]] | ndarray)
doc_state_mat (list[list[float]] | ndarray)
doc_vec (list[float] | ndarray)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)

compute_capabilities()[source]: Return backend capability metadata for this concrete PLSI instance.

compute_declaration()[source]: Return the symbolic distribution declaration for code generation and PPL introspection.

density(x)[source]

Evaluate the density of PLSI model for an observation x.

See log_density() for details on the density evaluation.

Parameters:: x (Tuple[int, Sequence[Tuple[int, float]]]) – Single observation of integer PLSI.
Returns:: Density evaluated at observed value x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of PLSI model for an observation of x.

Consider an Integer PLSI model for a corpus of documents with S states, V word values, and D documents ids (authors).

Let x (Tuple[int, Sequence[Tuple[int, float]]]) be an observation from a PLSI model, consisting of x = (d, [(v_0, c_0), (v_1, c_1), …, (v_{k-1}, c_{k-1})]), where the ‘d’ is some document d_id in the corpus and each tuple (v_i, c_i) corresponds to a value-count couple in the corpus. The log-likelihood is given by

log(p_mat(x)) = log(p_mat(d)) + sum_{j=0}^{k-1} c_k*log( sum_{s=0}^{S-1} p_mat(d|s)p_mat(s|v_k) ) + log(P_len(nn)),

where P_len(nn) is the density of the length distribution for ‘nn’ representing the total number of words in the document.

Parameters:: x (Tuple[int, Sequence[Tuple[int, float]]]) – (doc_id, [(value_id, count_for_value)]). See above for details.
Returns:: Log-density evaluated at a single observation x.
Return type:: float

component_log_density(x)[source]

Evaluate the log-density for each state in the PLSI.

Returns count*log(p_mat(W|S)) for each word-count pair in the document. Returned value is S by 1 where S is the number of components in the model.

Parameters:: x (Tuple[int, Sequence[Tuple[int, float]]]) – Single PLSI observation of form (doc_id, [(value_id, count_for_value)]).
Returns:: Numpy array of length S (num_states).
Return type:: ndarray

seq_log_density(x)[source]

Vectorized evaluation of the log-density for an encoded sequence of iid observation from a PLSI model.

See log_density() function for details on the log-likelihood.

The encoded sequence ‘x’ is a Tuple length 2. The first component contains data type Optional[T1] corresponding to the sequence encoding of the lengths. The second component is a Tuple of length 6 containing

xv (ndarray[int]): Numpy array of flattened word values.
xc (ndarray[float]): Numpy array of flattened counts for word values above.
xd (ndarray[int]): Document id for each word-count pair in the arrays above.
xi (ndarray[int]): Observed sequence index for each word-count pair in the arrays above.
xn (ndarray[float]): Numpy array of the total number of words in each document.
xm (ndarray[float]): Flattened array of document id's for the lengths above (len = len(x)).

Parameters:: x (tuple[T1 | None, tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]]) – Encoded sequence of iid observations of PLSI model. See above for details.
Returns:: Numpy array of log-density evaluated at each observation in the encoded sequence.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Evaluate encoded PLSI log densities using a backend-neutral compute engine.

Parameters:

x (tuple[T1 | None, tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]])
engine (Any)

Return type:

seq_component_log_density(x)[source]

Vectorized evaluation of the component log-density for each observation in an encoded sequence of iid PLSI: observations.

See component_log_density() function for details on component log-likelihood evaluation.

xv (ndarray[int]): Numpy array of flattened word values.
xc (ndarray[float]): Numpy array of flattened counts for word values above.
xd (ndarray[int]): Document id for each word-count pair in the arrays above.
xi (ndarray[int]): Observed sequence index for each word-count pair in the arrays above.
xn (ndarray[float]): Numpy array of the total number of words in each document.
xm (ndarray[float]): Flattened array of document id's for the lengths above (len = len(x)).

Parameters:: x (tuple[T1 | None, tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]]) – Encoded sequence of iid observations of PLSI model. See above for details.
Returns:: 2-d numpy array containing N rows of num_state sized arrays.
Return type:: ndarray

enumerator()[source]

Enumerate PLSI observations (doc_id, bag) in descending probability order.

A PLSI observation factors as P(doc) * [prod_w q_d(w)^{c_w}] * P_len(n) where q_d is the per-document word distribution prob_mat @ state_mat[d] and n the total word count, so it is a document-labelled mixture of trial-count multinomials: for each document the bags enumerate by a multiset best-first search under a length frontier driven by len_dist (the real trial-count distribution), and the per-document streams are merged by descending score with the document log-probability as offset. Requires a modelled len_dist unless every per-document word distribution is sub-stochastic-free; an absent length distribution leaves the bag support infinite and is enumerated by the multinomial term alone.

Return type:: DistributionEnumerator

sampler(seed=None)[source]

Return a sampler for iid integer PLSI observations.

Parameters:: seed (int | None)
Return type:: IntegerProbabilisticLatentSemanticIndexingSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s dimensions.

Parameters:: pseudo_count (float | None) – Optional smoothing count for topic, word, and document counts.
Returns:: A configured integer PLSI estimator.
Return type:: IntegerProbabilisticLatentSemanticIndexingEstimator

dist_to_encoder()[source]

Return an encoder for integer PLSI observations.

Return type:: IntegerProbabilisticLatentSemanticIndexingDataEncoder

class IntegerProbabilisticLatentSemanticIndexingEstimator(num_vals, num_states, num_docs, len_estimator=NullEstimator(), pseudo_count=(None, None, None), suff_stat=(None, None, None), name=None, keys=(None, None, None))[source]

Bases: ParameterEstimator

Estimator for integer PLSI word/state/document probabilities and the optional length model.

Parameters:

num_vals (int)
num_states (int)
num_docs (int)
len_estimator (ParameterEstimator | None)
pseudo_count (float | tuple[float | None, float | None, float | None] | None)
suff_stat (tuple[ndarray | None, ndarray | None, ndarray | None] | None)
name (str | None)
keys (tuple[str | None, str | None, str | None] | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: IntegerProbabilisticLatentSemanticIndexingAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an integer PLSI distribution from aggregated sufficient statistics.

Parameters:

nobs (float | None) – Optional observation count, accepted for the estimator interface.
suff_stat (tuple[ndarray, ndarray, ndarray, SS1 | None]) – Aggregated word, topic, document, and length statistics.

Returns:

A fitted integer PLSI distribution.

Return type:

IntegerProbabilisticLatentSemanticIndexingDistribution

class IntegerUniformSpikeDistribution(k, num_vals, p, min_val=0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Uniform integer distribution with extra probability mass at one value.

Parameters:

k (int)
num_vals (int)
p (float)
min_val (int | None)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare backend support for integer-uniform-spike generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the integer uniform spike.

density(x)[source]

Density of the integer uniform spike distribution at observation x.

See log_density() for details.

Parameters:: x (int) – Integer observation.
Returns:: Density at x.
Return type:: float

log_density(x)[source]

Log-density of the integer uniform spike distribution at observation x.

Returns log(p) if x equals the spike value k, log((1-p)/(num_vals-1)) for any other integer in [min_val, max_val], and -inf outside the range.

Parameters:: x (int) – Integer observation.
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (np.ndarray) – Numpy array of integer observations.
Returns:: Numpy array of log-density (float) of len(x).
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral log-density for encoded integer spike observations.

Parameters:

x (ndarray)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked integer-uniform-spike parameters for a shared support.

Parameters:

dists (list[IntegerUniformSpikeDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of integer-uniform-spike log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked legacy (min_val, count_vec) statistics.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Create an IntegerUniformSpikeSampler from parameters of this distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: IntegerUniformSpikeSampler object.
Return type:: IntegerUniformSpikeSampler

estimator(pseudo_count=None)[source]

Create an IntegerUniformSpikeEstimator for the current integer range.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: IntegerUniformSpikeEstimator object.
Return type:: IntegerUniformSpikeEstimator

dist_to_encoder()[source]

Returns an IntegerUniformSpikeDataEncoder for encoding sequences of iid integer observations.

Return type:: IntegerUniformSpikeDataEncoder

enumerator()[source]

Returns an IntegerUniformSpikeEnumerator iterating the support in descending probability order.

Return type:: IntegerUniformSpikeEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index directly from the finite integer support.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over finite integer spike supports.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over two integer spike supports.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class IntegerUniformSpikeEstimator(min_val=None, max_val=None, pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for integer-uniform-spike distributions from weighted counts.

Parameters:

min_val (int | None)
max_val (int | None)
pseudo_count (float | None)
suff_stat (tuple[int, float | None] | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Returns an IntegerUniformSpikeAccumulatorFactory consistent with this estimator.

Return type:: IntegerUniformSpikeAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an IntegerUniformSpikeDistribution by maximizing the spike location and weight.

The spike location k is chosen to maximize the likelihood of the accumulated counts (with optional pseudo_count regularization from the estimator configuration).

Parameters:

nobs (Optional[float]) – Weighted number of observations.
suff_stat (Tuple[int, np.ndarray]) – Minimum value and count vector.

Returns:

IntegerUniformSpikeDistribution object.

Return type:

IntegerUniformSpikeDistribution

class IntegerUniformSpikeEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates the support [min_val, max_val] in descending probability order.

The spike value k is yielded first when p >= (1-p)/(num_vals-1), otherwise last; the remaining values share the same probability and are yielded in ascending integer order. Zero-probability values are skipped.

Parameters:: dist (IntegerUniformSpikeDistribution)

class IntegerMultinomialDistribution(min_val=0, p_vec=None, len_dist=NullDistribution(), name=None, keys=None, prob_vec=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Multinomial distribution over integer-keyed count maps.

Parameters:

min_val (int)
p_vec (list[float])
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
keys (str | None)
prob_vec (list[float])

compute_capabilities()[source]: Declare generated-compute support inherited from the trial-count distribution.

compute_declaration()[source]: Return the generated-compute declaration for the integer multinomial.

static exp_family_sufficient_statistics(x, engine)[source]

Return a shape-only fallback; category-aware count vectors come from ..._from_params.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics_from_params(x, params, engine)[source]

Return the per-category count vector T(x) of shape (sz, K) (counts of in-support values).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the natural parameter eta = log(p_vec) (one entry per category).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the log partition A = 0 (normalization is carried by eta = log p).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure_from_params(x, params, engine)[source]

Return the multinomial log coefficient in support and -inf outside support.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

density(x)[source]

Evaluate the density of IntegerMultinomialDistribution at observed value x.

Parameters:: x (Sequence[Tuple[int, float]]) – Sequence of Tuple(s) containing the integer category value and number of successes.
Returns:: Density at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of IntegerMultinomialDistribution at observed value x.

Normalized conditional count-vector log-mass given by

log(p_mat(x)) = log(n!) - sum_k log(x_k!) + sum_k x_k*log(p_k) + log(p_mat(n)), for x having k integer categories and n the total trial count.

Note: x has k integer values and p_k denotes the probability of success for integer-category x_k. The len_dist defaults to NullDistribution, whose log-density is zero for any input; this gives a conditional count-vector mass at each observed total, while a real length law makes it a joint mass.

Parameters:: x (Sequence[Tuple[int, float]]) – Sequence of Tuple(s) containing the integer category value and number of successes.
Returns:: Log-density at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density for an encoded sequence of iid observations from integer multinomial: distribution.

Arg ‘x’ is a Tuple of length 5 containing:

sz (int): Total number of observed integermultinomial samples.
idx (ndarray): Numpy index array for each Tuple[value, count] in flattened x.
cnt (ndarray): Number of successes for each value in flattened x.
val (ndarray): Integer-category value array in flattened x.
tcnt (Optional[T1]): Sequence encoded number of trials for each sequence (length sz), with type T if
    length DataSequenceEncoder is not NullDataEncoder and returns type T. Else None.

Parameters:: x (See above for details) – Sequence encoding of iid integer multinomial observation.
Returns:: Numpy array of log-density evaluated at each observation in encoding.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded integer count vectors.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, E0 | None])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked integer-count-vector parameters for homogeneous mixture kernels.

Parameters:

dists (Sequence[IntegerMultinomialDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of integer-multinomial log densities.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, E0 | None])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy (min_val, count_vec, length_stat) statistics.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, E0 | None])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

sampler(seed=None)[source]

Create a sampler for this integer multinomial distribution.

Parameters:: seed (Optional[int]) – Set seed on random number generator used in sampling.
Returns:: Sampler bound to this distribution.
Return type:: IntegerMultinomialSampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this distribution.

Parameters:: pseudo_count (Optional[float]) – Optional prior mass assigned to this distribution’s current category probabilities during estimation.
Returns:: Estimator configured with the same support, name, and length estimator.
Return type:: IntegerMultinomialEstimator

dist_to_encoder()[source]

Return a data encoder using the encoder supplied by len_dist.

Return type:: IntegerMultinomialDataEncoder

enumerator(*, max_outcomes_per_length=100_000)[source]

Returns IntegerMultinomialEnumerator iterating count vectors in descending log-density order.

Parameters:: max_outcomes_per_length (int)
Return type:: IntegerMultinomialEnumerator

class DirichletMultinomialDistribution(alpha, n, name=None, keys=None, *, max_recurrence_cells=_DEFAULT_MAX_RECURRENCE_CELLS, max_frontier_entries=_DEFAULT_MAX_FRONTIER_ENTRIES)[source]

Bases: SequenceEncodableProbabilityDistribution

Dirichlet-multinomial over K-category count vectors summing to n (concentration alpha).

Parameters:

alpha (ndarray)
n (int)
name (str | None)
keys (str | None)
max_recurrence_cells (int)
max_frontier_entries (int)

density(x)[source]

Return the probability mass at a single count vector x.

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

Return the log-mass at x (-inf if any count is negative, non-integer, or the total is not n – a fractional category count is not a valid Dirichlet-multinomial outcome even when the (real-valued) total happens to sum to n).

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Vectorized log-mass for a stack of count vectors, shape (N, K) (-inf rows where any count is negative, non-integer, or the row total is not n).

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing count vectors from this distribution.

Parameters:: seed (int | None)
Return type:: DirichletMultinomialSampler

estimator(pseudo_count=None)[source]

Return a Minka fixed-point MLE estimator for alpha at the fixed number of trials n.

Parameters:: pseudo_count (float | None)
Return type:: DirichletMultinomialEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: DirichletMultinomialDataEncoder

enumerator(*, max_recurrence_cells=None, max_frontier_entries=None)[source]

Return an enumerator over count vectors summing to n in descending probability order.

Parameters:

max_recurrence_cells (int | None)
max_frontier_entries (int | None)

Return type:

DirichletMultinomialEnumerator

class DirichletMultinomialEstimator(dim, n, max_iter=500, tol=1.0e-9, pseudo_count=None, name=None, keys=None, min_alpha=_DEFAULT_MIN_ALPHA, max_recurrence_cells=_DEFAULT_MAX_RECURRENCE_CELLS, max_frontier_entries=_DEFAULT_MAX_FRONTIER_ENTRIES)[source]

Bases: ParameterEstimator

Minka fixed-point maximum-likelihood estimator for the Dirichlet-multinomial concentration.

Parameters:

dim (int)
n (int)
max_iter (int)
tol (float)
pseudo_count (float | None)
name (str | None)
keys (str | None)
min_alpha (float)
max_recurrence_cells (int)
max_frontier_entries (int)

accumulator_factory()[source]

Return an accumulator factory for Dirichlet-multinomial statistics.

Return type:: DirichletMultinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate concentration parameters by Minka’s fixed-point update.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, float, int])

Return type:

DirichletMultinomialDistribution

class IntegerMultinomialEstimator(min_val=None, max_val=None, len_estimator=NullEstimator(), len_dist=None, name=None, pseudo_count=None, suff_stat=None, keys=None)[source]

Bases: ParameterEstimator

Estimate integer-category multinomial probabilities from count statistics.

Parameters:

min_val (int | None)
max_val (int | None)
len_estimator (ParameterEstimator | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
pseudo_count (float | None)
suff_stat (tuple[int, ndarray] | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: IntegerMultinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from aggregated sufficient statistics.

If pseudo_count is not set, prior sufficient statistics are ignored during estimation.

suff_stat contains:: suff_stat[0] (int): Minimum integer category represented by the count vector. suff_stat[1] (np.ndarray): Weighted counts for consecutive integer categories. suff_stat[2] (Optional[SS0]): Sufficient statistics for the length estimator.

Parameters:

nobs (Optional[float]) – Number of observations in accumulated data.
suff_stat (tuple[int, ndarray, SS0 | None]) – See above for details.

Returns:

Estimated distribution.

Return type:

IntegerMultinomialDistribution

class IntegerMultinomialEnumerator(dist, *, max_outcomes_per_length=100_000)[source]

Bases: DistributionEnumerator

Enumerate normalized integer count-vector masses with a modeled trial-count law.

Parameters:

dist (IntegerMultinomialDistribution)
max_outcomes_per_length (int)

class IntegerCategoricalDistribution(min_val, p_vec=MISSING, name=None, keys=None, prob_vec=MISSING, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Categorical distribution over a bounded integer range.

Parameters:

min_val (int)
p_vec (list[float] | ndarray)
name (str | None)
keys (str | None)
prob_vec (list[float] | ndarray)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Return compute-backend metadata for integer-categorical scoring.

classmethod compute_declaration()[source]: Return the symbolic declaration for bounded integer-categorical probabilities.

static exp_family_sufficient_statistics(x, engine)[source]

Return raw values; category-aware one-hot statistics come from ..._from_params.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics_from_params(x, params, engine)[source]

Return the one-hot category indicator T(x) of shape (n, K) (zeros off support).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the natural parameter eta = log(p_vec) (one entry per category).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the log partition A = 0 (normalization is carried by eta = log p).

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure_from_params(x, params, engine)[source]

Return log h(x) = 0 on the support [min_val, min_val+K) and -inf outside it.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

get_parameters()[source]

Return the probability vector p_vec (lets it be scored by a Dirichlet conjugate prior).

Return type:: ndarray

get_prior()[source]

Return the conjugate parameter prior over the probability vector (or None).

Return type:: SequenceEncodableProbabilityDistribution | None

set_prior(prior)[source]

Attach a parameter prior and precompute conjugate-prior expectations.

With a Dirichlet(alpha) (or SymmetricDirichlet(alpha)) prior over the probability vector this caches the variational expected log-probabilities E[log p_k] = digamma(alpha_k) - digamma(sum_k alpha_k) so that expected_log_density(x) = E[log p_{x - min_val}]. Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x)] under the (symmetric) Dirichlet prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (int)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Evaluate the density of the integer categorical at observation x.

p_mat(x_mat=x) = p_vec[x] if x in support [min_val, max_val], else 0.0.

Parameters:: x (int) – Integer value.
Returns:: Density at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of the integer categorical at observation x.

log_p(x_mat=x) = log_p_vec[x] if x in support [min_val, max_val], else -np.inf.

Parameters:: x (int) – Integer value.
Returns:: Log-density at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of IntegerCategorical log_density() for sequence encoded iid observations x.

Parameters:: x (np.ndarray[int]) – Sequence encoded iid observation of integer categorical distribution.
Returns:: Numpy array of floats containing log_density() evaluated at each observation in x.
Return type:: ndarray

static backend_log_density_from_params(x, min_val, log_p_vec, engine)[source]

Engine-neutral integer-categorical log-density from explicit parameters.

Parameters:

x (Any)
min_val (int)
log_p_vec (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked integer-categorical parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[IntegerCategoricalDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of integer-categorical log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked legacy (min_val, count_vec) statistics.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

support_size()[source]

Number of integer values in the range.

Return type:: int

to_fisher(**kwargs)[source]: Return the integer-categorical one-hot Fisher view.

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional random seed.
Return type:: IntegerCategoricalSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution.

When pseudo_count is provided, the distribution’s probabilities are used as prior sufficient statistics during estimation.

Parameters:: pseudo_count (float | None) – Weight assigned to the distribution’s current probability vector during estimation.
Return type:: IntegerCategoricalEstimator

dist_to_encoder()[source]

Return the encoder for iid integer categorical observations.

Return type:: IntegerCategoricalDataEncoder

enumerator()[source]

Return IntegerCategoricalEnumerator iterating the support in descending probability order.

Return type:: IntegerCategoricalEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index directly from the finite integer support.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over integer categorical ranges.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over two integer categorical ranges.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class IntegerCategoricalEstimator(min_val=None, max_val=None, pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimator for bounded integer-categorical probability vectors.

Parameters:

min_val (int | None)
max_val (int | None)
pseudo_count (float | None)
suff_stat (tuple[int, ndarray] | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

get_prior()[source]

Return the conjugate parameter prior over the probability vector (or None).

Return type:: SequenceEncodableProbabilityDistribution | None

set_prior(prior)[source]

Set the conjugate parameter prior over the probability vector.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

model_log_density(model)[source]

Log-density of the model probability vector under the (symmetric) Dirichlet prior.

Parameters:: model (IntegerCategoricalDistribution)
Return type:: float

accumulator_factory()[source]

Return an accumulator factory configured from this estimator’s support and keys.

Note: If min_val and max_val are BOTH not None, these values are passed to IntegerCategoricalAccumulatorFactory. Else, they are obtained from member variable suff_stat. One of these conditions must be satisfied.

Returns:

Return type:: IntegerCategoricalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an integer-categorical distribution from weighted counts.

nobs is accepted for estimator API consistency but is not used. suff_stat is (min_val, count_vec). When pseudo_count and a prior statistic are present, the estimate combines observed counts with the weighted prior probability vector.

Parameters:

nobs (float | None)
suff_stat (tuple[int, ndarray] | None)

Return type:

IntegerCategoricalDistribution

class IntegerCategoricalEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerator over bounded integer support in descending probability order.

Parameters:: dist (IntegerCategoricalDistribution)

class IntegerBernoulliSetDistribution(log_pvec, log_nvec=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Distribution over finite sets of integer-valued Bernoulli outcomes.

Parameters:

log_pvec (Sequence[float] | ndarray)
log_nvec (Sequence[float] | ndarray | None)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare the generic table-kernel capabilities for integer-set likelihoods.

classmethod compute_declaration()[source]: Return the structured compute declaration for Bernoulli-set statistics.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (Sequence[int] | ndarray)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (Sequence[int] | ndarray)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[int, ndarray, ndarray])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral log-density for encoded integer Bernoulli-set observations.

Parameters:

x (tuple[int, ndarray, ndarray])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked integer Bernoulli-set parameters for shared support size.

Parameters:

dists (Sequence[IntegerBernoulliSetDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of integer Bernoulli-set log densities.

Parameters:

x (tuple[int, ndarray, ndarray])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked legacy (inclusion_counts, total_weight) statistics.

Parameters:

x (tuple[int, ndarray, ndarray])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: IntegerBernoulliSetSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: IntegerBernoulliSetEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: IntegerBernoulliSetDataEncoder

enumerator()[source]

Returns IntegerBernoulliSetEnumerator iterating subsets in descending probability order.

Return type:: IntegerBernoulliSetEnumerator

exception IntegerBernoulliSetFitError[source]

Bases: RuntimeError

Raised when integer Bernoulli-set statistics do not identify a fit.

class IntegerBernoulliSetEstimator(num_vals=MISSING, min_prob=1.0e-128, pseudo_count=None, suff_stat=None, name=None, keys=None, num_values=MISSING)[source]

Bases: ParameterEstimator

Estimate per-integer Bernoulli inclusion probabilities from aggregate counts.

Parameters:

num_vals (int)
min_prob (float)
pseudo_count (float | None)
suff_stat (ndarray | None)
name (str | None)
keys (str | None)
num_values (int)

accumulator_factory()[source]

Return a factory for integer Bernoulli-set sufficient-statistic accumulators.

Return type:: IntegerBernoulliSetAccumulatorFactory

estimate(nobs, suff_stat=None)[source]

Estimate an integer Bernoulli-set distribution from inclusion-count statistics.

Parameters:

nobs (float | None)
suff_stat (ndarray | None)

Return type:

IntegerBernoulliSetDistribution

class IntegerBernoulliSetEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate integer subsets in descending probability order.

Parameters:: dist (IntegerBernoulliSetDistribution)

class JointMixtureDistribution(components1, components2, w1=None, w2=None, taus12=None, taus21=None, keys=(None, None, None), name=None, joint_weights=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Joint mixture distribution over paired observations.

Observations are (x1, x2) tuples. The first tuple element is scored by components1 and the second by components2.

Parameters:

components1 (Sequence[SequenceEncodableProbabilityDistribution])
components2 (Sequence[SequenceEncodableProbabilityDistribution])
w1 (Sequence[float] | np.ndarray | None)
w2 (Sequence[float] | np.ndarray | None)
taus12 (list[list[float]] | np.ndarray | None)
taus21 (list[list[float]] | np.ndarray | None)
keys (tuple[str | None, str | None, str | None] | None)
name (str | None)
joint_weights (list[list[float]] | np.ndarray | None)

compute_capabilities()[source]: Intersect generated-compute backend support across all child components.

compute_declaration()[source]: Return the generated-compute declaration for the paired latent mixture.

density(x)[source]

Evaluate the density of a joint mixture observation x.

See log_density() for details.

Parameters:: x (Tuple[T0, T1]) – A single (X1, X2) observation.
Returns:: Density evaluated at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of a joint mixture observation x.

The log-density at x = (x1, x2) is

log(sum_{i=1}^{N} w_i * f_i(x1) * sum_{j=1}^{M} tau12_{ij} * g_j(x2)),

evaluated with a log-sum-exp for numerical stability.

Parameters:: x (Tuple[T0, T1]) – A single (X1, X2) observation.
Returns:: Log-density evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of the log-density for an encoded sequence of observations x.

Encoded sequence ‘x’ is a Tuple of length 3 containing:: x[0] (int): Number of observations. x[1] (E0): Encoded sequence of X1 values. x[2] (E1): Encoded sequence of X2 values.

Parameters:: x (tuple[int, E0, E1]) – Encoded sequence of iid joint mixture observations.
Returns:: Log-density evaluated at each observation in the encoded sequence x.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral log-density for encoded joint-mixture observations.

Parameters:

x (tuple[int, E0, E1])
engine (Any)

Return type:

to_fisher(**kwargs)[source]: Structural Fisher view for the joint mixture.

density_semantics()[source]: Return exact-or-approximate density semantics joined from child components.

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional random seed.
Returns:: A configured JointMixtureSampler.
Return type:: JointMixtureSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s components.

Parameters:: pseudo_count (float | None) – Optional smoothing count for latent-state counts.
Returns:: A JointMixtureEstimator.
Return type:: JointMixtureEstimator

dist_to_encoder()[source]

Return an encoder for paired joint-mixture observations.

Return type:: DataSequenceEncoder

enumerator()[source]

Return an enumerator over pairs in descending probability order.

Return type:: JointMixtureEnumerator

class JointMixtureEstimator(estimators1, estimators2, suff_stat=None, pseudo_count=None, keys=(None, None, None), name=None)[source]

Bases: ParameterEstimator

Estimator for paired latent mixture distributions.

Parameters:

estimators1 (Sequence[ParameterEstimator])
estimators2 (Sequence[ParameterEstimator])
suff_stat (tuple[np.ndarray, np.ndarray, np.ndarray, tuple[E0, ...], tuple[E1, ...]] | None)
pseudo_count (float | tuple[float, float, float] | None)
keys (tuple[str | None, str | None, str | None] | None)
name (str | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: JointMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a joint mixture distribution from aggregated sufficient statistics.

The tuple is interpreted as (x1_counts, x2_counts, joint_counts, x1_child_stats, x2_child_stats).

Parameters:

nobs – Weighted number of observations, accepted for the estimator interface.
suff_stat (tuple[ndarray, ndarray, ndarray, tuple[E0, ...], tuple[E1, ...]]) – Aggregated joint-mixture sufficient statistics.

Returns:

A fitted joint mixture distribution.

Return type:

JointMixtureDistribution

class JointMixtureEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates the support of a JointMixtureDistribution in descending probability order.

Parameters:: dist (JointMixtureDistribution)

class LogGaussianDistribution(mu, sigma2, name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Log-normal distribution where log(X) is Gaussian with mean mu and variance sigma2.

Parameters:

mu (float)
sigma2 (float)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for generated log-Gaussian density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the log-Gaussian distribution.

static exp_family_sufficient_statistics(x, engine)[source]

Return log-Gaussian sufficient statistics for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row log-Gaussian sufficient statistics in accumulator order.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return log-Gaussian natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return log-Gaussian log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return log-Gaussian base measure for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

set_prior(prior)[source]

Attach a parameter prior and precompute conjugate-prior expectations.

With a NormalGamma(mu0, lam, a, b) prior over (mu, tau=1/sigma2) of log(X) this caches the variational expected natural parameters [ea, eb, e1, e2] exactly as in the Gaussian case, so that expected_log_density(x) = y*(e1 + y*e2) - ea + eb - y with y = log(x). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | mu, tau)] under the NormalGamma prior.

With a conjugate prior this is the Gaussian VB expected log-likelihood evaluated at log(x), plus the Jacobian term -log(x); without a prior it falls back to log_density(x).

Parameters:: x (float)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded (logged) observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Density of Log-Gaussian distribution at observation x.

See log_density() for details.

Parameters:: x (float) – Positive real-valued number.
Returns:: Density of Log-Gaussian at x.
Return type:: float

log_density(x)[source]

Log-density of log-Gaussian distribution at observation x.

Log-density of log-Gaussian with log-mean mu and log-variance sigma2 given by,: log(f(x;mu, sigma2)) = -0.5*log(2*pi*sigma2) - log(x) - 0.5*(log(x)-mu)^2/sigma2, for positive x.

Parameters:: x (float) – Positive valued observation of log-Gaussian.
Returns:: Log-density at observation x.
Return type:: float

seq_ld_lambda()[source]

Return vectorized log-density callables for fast scoring.

Return type:: list[Callable]

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (np.ndarray) – Numpy array of floats.
Returns:: Numpy array of log-density (float) of len(x).
Return type:: ndarray

static backend_log_density_from_params(x, mu, sigma2, engine)[source]

Engine-neutral log-Gaussian log-density on log-encoded data.

Parameters:

x (Any)
mu (Any)
sigma2 (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for log-encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

gradient_log_prior(priors, prior_strength, torch, engine)[source]

Distribution-owned MAP prior contribution for log-Gaussian parameters.

Parameters:

priors (Any)
prior_strength (float)
torch (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked log-Gaussian parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[LogGaussianDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of log-Gaussian log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked log-Gaussian sufficient statistics using engine-resident arrays.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:: q (float)
Return type:: float

to_fisher(**kwargs)[source]: Return this distribution’s own Fisher view.

mean()[source]

Mean exp(mu + sigma2/2).

Return type:: float

variance()[source]

Variance (exp(sigma2) - 1) * exp(2 mu + sigma2).

Return type:: float

entropy()[source]

Differential entropy mu + 0.5*log(2*pi*e*sigma2).

Return type:: float

sampler(seed=None)[source]

Create a sampler from this log-Gaussian distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: LogGaussianSampler object.
Return type:: LogGaussianSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s parameters.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: LogGaussianEstimator object.
Return type:: LogGaussianEstimator

dist_to_encoder()[source]

Return the encoder for log-Gaussian observations.

Return type:: LogGaussianDataEncoder

class LogGaussianEstimator(pseudo_count=(None, None), suff_stat=(None, None), min_covar=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate log-Gaussian location and variance from accumulated log moments.

The variance is formed from shift-anchored log moments whenever the accumulated statistics carry that payload (see LogGaussianAccumulator), which makes the fit SCALE-EQUIVARIANT: estimating on a * x returns mu + log(a) with sigma2 unchanged, for any positive a the data can carry. A large multiplicative scale is a large additive offset on log(x), which is the same cancellation the sibling location-scale families repaired; here it costs ~1.4e-7 of sigma2 on values around 1e6 with a 0.2% spread. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones that arrived already reduced from an engine kernel or an older serialization – the historical raw path is used bit-identically, and estimate warns rather than returning a variance it cannot stand behind.

Parameters:

pseudo_count (float | tuple[float | None, float | None])
suff_stat (tuple[float | None, float | None])
min_covar (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Return GaussianAccumulatorFactory with name and keys passed.

Return type:: LogGaussianAccumulatorFactory

model_log_density(model)[source]

Log-density of the model parameters under the NormalGamma prior (ELBO global term).

The prior is over (mu, tau=1/sigma2) of log(X), so the model’s (mu, sigma2) is mapped.

Parameters:: model (LogGaussianDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a log-Gaussian distribution from accumulated log moments.

suff_stat is (sum_log_x, sum_log_x2, count, count2). nobs is accepted for estimator API consistency but is not used.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float, float])

Return type:

LogGaussianDistribution

class MarkovChainDistribution(init_prob_map, transition_map, len_dist=NullDistribution(), default_value=0.0, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Markov-chain distribution over finite-state sequences.

Parameters:

init_prob_map (dict[T, float])
transition_map (dict[T, dict[T, float]])
len_dist (SequenceEncodableProbabilityDistribution | None)
default_value (float)
name (str | None)

get_prior()[source]: Returns the conjugate prior in (states, init_prior, row_priors) form (or None).

set_prior(prior)[source]

Set the conjugate Dirichlet prior and precompute its digamma expectations.

With Dirichlet init_prior and Dirichlet row_priors (each over the fixed ordered states) this caches the digamma expectations E[ln p_k] = psi(alpha_k) - psi(sum alpha) used by expected_log_density and sets has_conj_prior accordingly. prior=None leaves the distribution a plain point model.

Parameters:: prior – (states, init_prior, row_priors) tuple or None.
Return type:: None

expected_log_density(x)[source]

Variational E_q[log p(x)] under the Dirichlet priors over a state sequence.

Replaces the initial/transition log-probabilities with their digamma expectations E[ln p_k] = psi(alpha_k) - psi(sum alpha); the length term is added as in log_density(). Falls back to the plug-in log_density(x) when no conjugate prior is set.

Parameters:: x (List[T]) – An observed Markov chain state sequence.
Returns:: Expected log-density of the Markov chain at x.
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density() at sequence-encoded input x.

Falls back to seq_log_density(x) when no conjugate prior is set.

Parameters:: x (tuple[int, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, Any]) – Encoded sequences from seq_encode().
Returns:: Numpy array of expected log-densities, one per sequence.
Return type:: ndarray

compute_capabilities()[source]: Return compute-backend metadata inherited from the optional length distribution.

density_semantics()[source]: Classify a chain without a length law as a conditional fixed-length factor.

compute_declaration()[source]: Return the symbolic declaration for Markov-chain transition and length statistics.

density(x)[source]

Return density of MarkovChainDistribution at observed sequence x.

Returns exponential of log_density(x). See log_density() for details.

Parameters:: x (List[T]) – An observed Markov chain sequence of data type T.
Returns:: Density of Markov chain at x.
Return type:: float

log_density(x)[source]

Return log-density of MarkovChainDistribution at observed sequence x.

Density of Markov chain is given by for sequence of length n, x=[x[0],x[1],…,x[n-1]]

p_mat(x) = p_mat(x[0])*p_mat(x[1]|x[0])*…*p_mat(x[n-1]|x[n-2])*P_len(n)

where p_mat(x[i+1]|x[i]) is the transition probability, p_mat(x[0]) is the init-probability, and P_len(n) is given by the length distribution density.

Note if len(x) = 0, only log(P_len(0)) is returned.

Parameters:: x (List[T]) – An observed Markov chain sequence of data type T.
Returns:: Log-density of Markov chain at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log_density of Markov Chain for an encoded sequence of observations x.

Computationally efficient implementation of log_density() for sequence encoded data x.

The arg value x is a Tuple of length 8 with entries:

x[0] (int): Number of total observations (number of Markov sequences).
x[1] (ndarray[int]): Sequence index for initial state observations.
x[2] (ndarray[int]): Sequence index for non-initial state observations in a sequence greater than len 1.
x[3] (ndarray[int]): Numpy array of observations index in inv_key_map for initial states.
x[4] (ndarray[int]): State-to-state index value of inv_key_map for initial state value.
x[5] (ndarray[int]): State-to-state index value of inv_key_map for transition.
x[6] (ndarray[T]): Maps integer index value to value in state-space (T).
x[7] (Optional[T1]): Encoded sequence of lengths from len_encoder. None if no length distribution to be
    estimated.

Parameters:: x (tuple[int, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, Any]) – See above for details.
Returns:: Numpy of length x[0], containing the log-density of Markov chain at each observation in x.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded Markov-chain sequences.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked fixed-support Markov-chain parameters.

Parameters:

dists (Sequence[MarkovChainDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Markov-chain sequence log densities.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return versioned per-component fixed-layout Markov statistics.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, Any])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[MarkovChainStatistics, …]

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for fixed-support autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for this Markov-chain distribution.

Raises exception if length distribution (len_dist) was not specified in initialization.

Parameters:: seed (Optional[int]) – Used to set the seed of random number generator for sampling.
Returns:: MarkovChainSampler object.
Return type:: MarkovChainSampler

path_sampler(seed=None)[source]

Return a sampler for caller-supplied path lengths.

Parameters:: seed (int | None)
Return type:: MarkovChainSampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this Markov-chain distribution.

Parameters:: pseudo_count (Optional[float]) – Prior mass used to smooth initial and transition counts.
Returns:: Estimator configured with the same length estimator and prior.
Return type:: MarkovChainEstimator

dist_to_encoder()[source]

Create a data encoder for Markov-chain observation sequences.

Note: len_encoder is passed as NullDataEncoder() if len_dist is not to be estimated.

Returns:: Encoder using this distribution’s length encoder.
Return type:: MarkovChainDataEncoder

enumerator()[source]

Returns MarkovChainEnumerator iterating state sequences in descending probability order.

Return type:: MarkovChainEnumerator

quantized_count_index(quantizer, max_fine_bucket)[source]

Structural count index: a forward DP carrying a count histogram per (length, end-state).

log p(x) = log p_init(x0) + sum_i log p_trans(x_i|x_{i-1}) + log p(len). The forward recursion is lifted into the count semiring: alpha[t][s] is the histogram (over the fine bucket of accumulated log probability) of length-t prefixes ending in state s, with alpha[1][s] = delta(bucket(log p_init(s))) and alpha[t+1][s'] = sum_s alpha[t][s].shift(bucket(log p_trans(s'|s))). Per length L the sequence histogram pools the end states and shifts by the length term; the total pools lengths. Sequences are unranked by choosing the end state, then walking the trellis backward choosing predecessors by count.

Parameters:: max_fine_bucket (int)

class MarkovChainStatistics(schema_version, states, initial_counts, transition_counts, length_nobs, length)[source]

Bases: NamedTuple

Immutable, versioned sufficient statistics over one closed state layout.

Parameters:

schema_version (int)
states (tuple[Any, ...])
initial_counts (tuple[float, ...])
transition_counts (tuple[tuple[float, ...], ...])
length_nobs (float)
length (Any | None)

schema_version: int: Alias for field number 0

states: tuple[Any, ...]: Alias for field number 1

initial_counts: tuple[float, ...]: Alias for field number 2

transition_counts: tuple[tuple[float, ...], ...]: Alias for field number 3

length_nobs: float: Alias for field number 4

length: Any | None: Alias for field number 5

exception NonGenerativeMarkovChainError[source]

Bases: TypeError

Raised when a fixed-length Markov factor is asked to generate whole sequences.

class MarkovChainEstimator(pseudo_count=None, levels=None, len_estimator=NullEstimator(), name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimator for finite-state Markov-chain transition maps and optional length law.

Parameters:

pseudo_count (float | None)
levels (Iterable[T] | None)
len_estimator (ParameterEstimator | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Returns MarkovChainAccumulatorFactory for creating MarkovChainAccumulator.

Return type:: MarkovChainAccumulatorFactory

get_prior()[source]: Returns the conjugate prior in (states, init_prior, row_priors) form (or None).

set_prior(prior)[source]

Set the conjugate Dirichlet prior and flag whether it admits the conjugate update.

Parameters:: prior – (states, init_prior, row_priors) tuple or None; has_conj_prior is set when all priors are Dirichlet.
Return type:: None

model_log_density(model)[source]

Log-density of the model’s probabilities under the Dirichlet priors.

Sums the Dirichlet log-densities of the initial-state probabilities and each transition row (floored at a tiny constant so MAP estimates that sit on the simplex boundary score finitely). Returns 0.0 without a conjugate prior.

Parameters:: model (MarkovChainDistribution) – Model to score.
Returns:: Prior log-density of the model parameters.
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate MarkovChainDistribution from aggregated sufficient statistics from observed data.

Arg suff_stat is a Tuple of length three containing,: suff_stat[0] (Dict[T, float]): Maps initial state values to their aggregated counts. suff_stat[1] (Dict[T, Dict[T, List[float]]]): Maps state to state transition counts. suff_stat[2] (T1): Sufficient statistic value of length accumulator. (Assumed type T1).

If member variable pseudo_count is set estimate1() is called to aggregated weighted sufficient statistics. Else estimate0() is called to obtain estimates for MarkovChainDistribution directly from arg ‘suff_stat’.

Parameters:

nobs (Optional[float]) – Number of observations. Passed to estimate1() or estimate2().
suff_stat (MarkovChainStatistics) – Seed above for details.

Returns:

MarkovChainDistribution object.

Return type:

MarkovChainDistribution

estimate0(nobs, suff_stat)[source]

Estimate MarkovChainDistribution from aggregated sufficient statistics from observed data.

Maximum likelihood estimates for initial state probabilities, transition probabilities, and the length distribution are obtained directly from aggregated data in ‘suff_stat’.

A state with no outgoing transition evidence gets a uniform transition row. That row appears in no likelihood factor, so it is one of the (many) exact maximizers rather than a guess, but it is not a row the data chose: every such state is reported through MarkovChainDistribution.numerical_repairs() on the returned model, as markov-row-uniform(no outgoing transitions: ...).

Arg suff_stat is a Tuple of length three containing,: suff_stat[0] (Dict[T, float]): Maps initial state values to their aggregated counts. suff_stat[1] (Dict[T, Dict[T, List[float]]]): Maps state to state transition counts. suff_stat[2] (T1): Sufficient statistic value of length accumulator. (Assumed type T1).

Parameters:

nobs (Optional[float]) – Number of observations. Passed to estimate1() or estimate2().
suff_stat (MarkovChainStatistics) – Seed above for details.

Returns:

MarkovChainDistribution object.

Return type:

MarkovChainDistribution

estimate1(nobs, suff_stat)[source]

Estimate MarkovChainDistribution from aggregated sufficient statistics from observed data.

Maximum likelihood estimates for initial state probabilities, transition probabilities, and the length distribution are obtained by a weighted aggregation of sufficient statistics in ‘suff_stat’, and member variables of MarkovChainEstimator object.

Arg suff_stat is a Tuple of length three containing,: suff_stat[0] (Dict[T, float]): Maps initial state values to their aggregated counts. suff_stat[1] (Dict[T, Dict[T, List[float]]]): Maps state to state transition counts. suff_stat[2] (T1): Sufficient statistic value of length accumulator. (Assumed type T1).

Parameters:

nobs (Optional[float]) – Number of observations. Passed to estimate1() or estimate2().
suff_stat (MarkovChainStatistics) – Seed above for details.

Returns:

MarkovChainDistribution object.

Return type:

MarkovChainDistribution

class MarkovChainEnumerator(dist)[source]

Bases: DistributionEnumerator

Best-first enumerator for finite-state sequences with a modeled length law.

Parameters:: dist (MarkovChainDistribution)

class ProbabilisticPCADistribution(w, mu, sigma2, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Probabilistic PCA: x ~ N(mu, W W^T + sigma2 I) with q latent factors.

Parameters:

w (Sequence[Sequence[float]] | ndarray)
mu (Sequence[float] | ndarray)
sigma2 (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Return compute-backend metadata for PPCA scoring.

property w: ndarray: Return an owned snapshot of the factor loadings.

property mu: ndarray: Return an owned snapshot of the mean.

property sigma2: float: Return the immutable isotropic noise variance.

property inv_covar: ndarray: Return an owned snapshot of the cached covariance inverse.

transform(x)[source]

Return the posterior mean of the latent factors E[z | x] = M^{-1} W^T (x - mu).

Parameters:: x (Sequence[float] | ndarray)
Return type:: ndarray

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (Sequence[float] | ndarray)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation.

Parameters:: x (Sequence[float] | ndarray)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (ndarray)
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: ProbabilisticPCASampler

estimator(pseudo_count=None)[source]

Return a closed-form ML estimator with the latent dimension fixed at this model’s q.

Parameters:: pseudo_count (float | None)
Return type:: ProbabilisticPCAEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: ProbabilisticPCADataEncoder

class ProbabilisticPCAEstimator(latent_dim, dim=None, min_sigma2=_MIN_SIGMA2, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form maximum-likelihood estimator for PPCA (Tipping & Bishop eigen-solution).

Parameters:

latent_dim (int)
dim (int | None)
min_sigma2 (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for PPCA sufficient-statistic accumulators.

Return type:: ProbabilisticPCAAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate PPCA parameters from weighted first and second moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray | None, ndarray | None])

Return type:

ProbabilisticPCADistribution

class MixtureDistribution(components, w=MISSING, name=None, weights=MISSING, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Finite mixture over homogeneous component distributions.

components define both the conditional families p(x | z=k) and the observation type accepted by the mixture. w contains the component probabilities and is cached as log_w for stable scalar and vectorized scoring. Zero-weight components are retained for structural compatibility but contribute -inf to log-density calculations.

Parameters:

components (Sequence[SequenceEncodableProbabilityDistribution]) – Component distributions. Each component should support the same raw observation shape and sequence-encoding contract.
w (np.ndarray | list[float]) – Component weights. The values are interpreted as simplex weights and should sum to one.
name (str | None) – Optional display name for diagnostics and generated artifacts.
weights (np.ndarray | list[float]) – Alias for w.
prior (SequenceEncodableProbabilityDistribution | None) – Optional joint mixture prior or weight prior.

components: Component distribution objects.

w: Component weights as a NumPy array.

zw: Boolean mask for zero-weight components.

log_w: Log weights, with zero-weight entries represented as -inf.

num_components: Number of mixture components.

compute_capabilities()[source]: Return compute-backend metadata shared by all mixture components.

compute_declaration()[source]: Return the symbolic declaration for mixture weights and component statistics.

get_prior()[source]

Return the joint mixture prior, or None for a plain point model.

When a weight prior is attached the joint prior is the (weight_prior, tuple(component priors)) pair produced by mixture_prior(); otherwise None.

Return type:: SequenceEncodableProbabilityDistribution | None

set_prior(prior)[source]

Attach a weight prior (and optional per-component priors), caching weight expectations.

With a (symmetric) Dirichlet weight prior this caches the variational weight expectations E[log w_k] = digamma(alpha_k) - digamma(sum_j alpha_j) used by expected_log_density. Component priors, when supplied, are delegated to each component via component.set_prior. prior=None (the default) leaves the mixture a plain point model (byte-identical MLE behaviour).

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Return the optimized local variational log-evidence bound.

This compatibility name does not compute the generally intractable E[log(sum_k w_k p_k(x))]. With conjugate priors it returns logsumexp_k(E[log w_k] + E[log p_k(x)]), the optimized local variational lower bound. Use variational_log_evidence_bound() when the semantic distinction matters. Without a conjugate weight prior it falls back to the plug-in log_density.

Parameters:: x (T)
Return type:: float

variational_log_evidence_bound(x)[source]

Return the local variational lower bound for one observation.

Parameters:: x (T)
Return type:: float

seq_expected_log_density(x)[source]

Return vectorized local variational log-evidence bounds.

This is the sequence form of variational_log_evidence_bound(), retained under the framework-wide compatibility name.

Parameters:: x (T1)
Return type:: ndarray

seq_variational_log_evidence_bound(x)[source]

Return local variational lower bounds for encoded observations.

Parameters:: x (T1)
Return type:: ndarray

density(x)[source]

Return the mixture density at one raw observation.

Parameters:: x (T) – Observation accepted by every component family.
Returns:: exp(log_density(x)).
Return type:: float

density_semantics()[source]: Return joined density semantics over all mixture components.

log_density(x)[source]

Return the mixture log-density at one raw observation.

The calculation is logsumexp_k(log p_k(x) + log w_k). Component families are responsible for returning -inf for observations outside support; the mixture combines those values without converting them to NaN.

Parameters:: x (T) – Observation accepted by every component family.
Returns:: Finite log-density when at least one positive-weight component can score the observation, otherwise -inf.
Return type:: float

conditional(observed)[source]

Return the conditional mixture over the unobserved coordinates given observed.

The conditional of a mixture is itself a mixture: for sum_k w_k f_k observing x_o,

P(x_u | x_o) = sum_k w’_k f_k(x_u | x_o), w’_k proportional to w_k f_k.marginal(x_o)(x_o),

i.e. the component responsibilities are updated by how well each component explains the observed coordinates and each component is replaced by its own conditional. Because the result is a full MixtureDistribution you can both score it and .sampler(seed).sample() from it – the latter is given=-style conditional sampling that first draws a component from the posterior responsibilities, then draws the unobserved coordinates from that component’s conditional.

Requires each component to support marginal(indices) and condition(observed) (e.g. the multivariate Gaussian / Student-t). observed maps coordinate index to its fixed value.

Parameters:: observed (dict[int, float])
Return type:: MixtureDistribution

component_log_density(x)[source]

Return component-wise log densities for one raw observation.

Parameters:: x (T) – Observation accepted by every component family.
Returns:: One log-density per component, before mixture weights are applied.
Return type:: ndarray

posterior(x)[source]

Return component responsibilities for one raw observation.

Responsibilities are proportional to w[k] * p_k(x). An observation outside every component’s support receives zero responsibility and therefore cannot fabricate component statistics.

Parameters:: x (T) – Observation accepted by every component family.
Returns:: Responsibility vector over component labels. It sums to one when the evidence is possible and is all zero otherwise.
Return type:: ndarray

seq_component_log_density(x)[source]

Return vectorized component log densities for encoded observations.

x must be produced by MixtureDataEncoder.seq_encode or by an equivalent component encoder. The output has shape (n, k) where n is the number of encoded observations and k is the number of mixture components.

Parameters:: x (T1) – Encoded observation batch.
Returns:: Component log-density matrix before mixture weights are applied.
Return type:: ndarray

seq_log_density(x)[source]

Return vectorized mixture log densities for encoded observations.

Each row is evaluated with a row-wise log-sum-exp over component scores plus log weights. Rows for which every positive-weight component is impossible return -inf.

Parameters:: x (T1) – Encoded observation batch.
Returns:: One log-density per encoded observation.
Return type:: ndarray

backend_seq_component_log_density(x, engine)[source]

Engine-neutral component log densities for encoded data.

Parameters:

x (T1)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral mixture log-density for encoded data.

Parameters:

x (T1)
engine (Any)

Return type:

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

seq_posterior(x)[source]

Return vectorized component responsibilities for encoded observations.

Each row is proportional to w[k] * p_k(x_i). Rows where all positive-weight components are impossible receive zero responsibility, matching posterior() without inventing latent assignments.

Parameters:: x (T1) – Encoded observation batch.
Returns:: (n, k) responsibility matrix. Possible rows sum to one; impossible rows sum to zero.
Return type:: ndarray

latent_posterior(x)[source]

Return the latent posterior q(z | x) over component labels for raw observations x.

q(z) is the exact independent-categorical posterior whose marginals are the EM responsibilities. The returned CategoricalLatentPosterior can .marginals() (the responsibilities), .sample(rng) component labels, .mode() (the MAP labels), or .entropy().

Parameters:: x (Sequence[T])
Return type:: CategoricalLatentPosterior

posterior_predictive(x, seed=None)[source]

Draw posterior-predictive observations conditioned on x.

For each observed x_i the component is sampled from the latent posterior q(z_i | x_i) and a fresh observation is emitted from that component – i.e. “given I saw x_i, draw a new point from the same mixture component it likely came from”. Returns a list the length of x. Draws are grouped by component and scattered (vectorized) via the shared sampling helper.

Parameters:

x (Sequence[T])
seed (int | None)

Return type:

list[Any]

support_size()[source]

Upper bound on distinct support points: the sum over components (union <= sum).

Return type:: int | None

tropical_displacement_bits()[source]

log2(#positive-weight components) – the tropical-vs-marginal cost gap (in bits).

The marginal log p(x) = logsumexp_k (log w_k + log p_k(x)) is bounded by its largest term M(x) = max_k (log w_k + log p_k(x)) via M(x) <= log p(x) <= M(x) + log K, where K is the number of components that can contribute (positive weight). The structural seek bins by the tropical cost M(x); mixle.enumeration.density_rank.marginal_seek() widens its smear window by this many bits so the reported rank bracket provably contains the TRUE marginal rank. K <= 1 means the marginal is a single term -> 0.0 (the seek is then exact). When the component supports are provably disjoint every value lands in one component, so M(x) equals the marginal and there is likewise no displacement -> 0.0 (the seek is exact and tight).

Return type:: float

to_fisher(**kwargs)[source]: Structural Fisher view for the mixture.

sampler(seed=None)[source]

Return a sampler that draws from the mixture distribution.

Parameters:: seed (int | None) – Optional RandomState seed for reproducible draws.
Returns:: MixtureSampler bound to this distribution.
Raises:: ValueError – If this mixture is a likelihood factor rather than a normalized law.
Return type:: MixtureSampler

A component may be a scaled law – an unnormalized categorical, an open-world smoothed emission, a component that won zero responsibility – and _owned_generative_components admits those deliberately, because a constant scale cancels in the E-step’s responsibility normalization. It does NOT cancel in the composite: a mass-0.75 component under weight 0.5 leaves the mixture with total mass 0.875, and density_semantics() reports LIKELIHOOD_FACTOR to say so. The sampler used to ignore that and draw as though the weights described a law, so the scorer and the sampler described different objects (MXR-080-1857).

Refusing here rather than at construction is the point: scoring such a mixture is legitimate and tested (an open-world component has infinite total mass and no finite scale to absorb), so the object must remain constructible. What it cannot do is pretend to be a generative law.

estimator(pseudo_count=None)[source]

Return an estimator with matching component structure.

Parameters:: pseudo_count (float | None) – Optional smoothing mass applied through the estimator path.
Returns:: MixtureEstimator suitable for fitting observations of the same type as this distribution.
Return type:: MixtureEstimator

decomposition()[source]: Mixture components split along the component axis. Responsibilities (logsumexp) are computed INSIDE a shard; across shards the per-component sufficient stats SUM-reduce plus one scalar total-count all-reduce – the homogeneous stacked-kernel + DTensor path (engine_axis=0).

dist_to_encoder()[source]

Return an encoder that delegates observation encoding to components.

Return type:: MixtureDataEncoder

enumerator()[source]

Return an enumerator over the union of component supports.

Return type:: MixtureEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index from a global mixture frontier.

The primary path pulls candidates from weighted component enumerator heads. The log-sum of those heads bounds every unseen value, so construction stops when the live global frontier falls below 2**(-max_bits). This avoids the looser per-component log2(K) candidate expansion. If a component cannot enumerate, the method falls back to the structured cross-index path.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_count_index(quantizer, max_fine_bucket)[source]

BoundedCount for the MARGINAL mixture law: pool weight-scaled component count indices.

log p(x) = logsumexp_k (log w_k + log p_k(x)) has no exact structural count – overlapping component supports would need value-level deduplication. This builds the count semiring’s plus-fold over scale(component_index, log w_k) instead, which:

reaches a 2**M budget structurally (no enumeration), and

is a conservative UPPER bound – a value shared by several components is counted once per component, and each value is binned by its dominant weighted component (the tropical cost, within log2(K) bits of the exact logsumexp).

Every unranked value still carries its exact mixture log_density (re-evaluated by the budget builder). For an exact small-budget index (best-first union with dedup), use quantized_index. Components that cannot count structurally raise EnumerationError.

Parameters:: max_fine_bucket (int)

structural_fine_bucket(value, quantizer)[source]

Dominant weighted-component structural bucket (mirrors the plus-of-scaled-children index).

Return type:: int

is_canonical_copy(value, coarse_bin, quantizer)[source]

Stateless dedup: keep value only at its dominant (best-weighted) component’s bin.

The canonical bin is the coarse bin of the minimum, over components, of the component’s structural fine bucket shifted by the weight term. O(K) model evaluations, no state.

Parameters:: coarse_bin (int)
Return type:: bool

class ResponsibilityAttentionDistribution(key_means, emission, position_prior=None, sigma2=1.0, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

One generative-gate attention head; a mixture over context positions (EM-able).

Parameters:

key_means (np.ndarray)
emission (np.ndarray)
position_prior (np.ndarray | None)
sigma2 (float)
name (str | None)

density(x)[source]

Density p(query, target | context) at one observation.

Parameters:: x (tuple[Any, Any, int])
Return type:: float

log_density(x)[source]

Log conditional density log p(query, target | context) at one observation (ctx, y, t).

Parameters:: x (tuple[Any, Any, int])
Return type:: float

seq_log_density(x)[source]

Vectorized log p(query, target | context) over an encoded batch -> (n,).

Parameters:: x (tuple[ndarray, ndarray, ndarray])
Return type:: ndarray

predict_proba(context, query)[source]

Predictive target distribution p(target | context, query) (target marginalized over z).

Attention here does not see the target: a_i ∝ pi_i N(query; K[c_i]), then p(target) = sum_i a_i emission[c_i, :]. Accepts a single example or a batch.

Returns:

(T,) for a single example, or (n, T) for a batch.

Parameters:

context (ndarray)
query (ndarray)

Return type:

sampler(seed=None)[source]

Return a sampler for synthetic responsibility-attention observations.

Parameters:: seed (int | None)
Return type:: ResponsibilityAttentionSampler

estimator(pseudo_count=None)[source]

Return a closed-form EM estimator for this attention head.

Parameters:: pseudo_count (float | None)
Return type:: ResponsibilityAttentionEstimator

dist_to_encoder()[source]

Return the encoder for contexts, query vectors, and targets.

Return type:: ResponsibilityAttentionDataEncoder

class ResponsibilityAttentionEstimator(num_symbols, context_length, query_dim, num_targets, *, sigma2=1.0, estimate_sigma2=False, min_sigma2=1e-6, emission_smoothing=1e-6, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate a ResponsibilityAttentionDistribution by closed-form EM M-steps.

Parameters:

num_symbols (int)
context_length (int)
query_dim (int)
num_targets (int)
sigma2 (float)
estimate_sigma2 (bool)
min_sigma2 (float)
emission_smoothing (float)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for responsibility-attention sufficient-statistic accumulators.

Return type:: ResponsibilityAttentionAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate key means, emissions, position prior, and optional gate variance.

Parameters:: nobs (float | None)
Return type:: ResponsibilityAttentionDistribution

sequence_to_triples(tokens, context_length, *, num_symbols=None, embeddings=None)[source]

Unroll a token sequence into the (context, query, target) triples this head consumes.

For each prediction point p (with a full window behind it and a next token ahead), emits context = tokens[p-N+1 : p+1] (the N most recent tokens, including the current one), query derived from the current token tokens[p] (its embedding, or a one-hot), and target = tokens[p+1]. This is the bridge from a real sequence to the iid-triple leaf.

Scope: with the single-hop leaf this yields an attention-weighted next-token model whose predictive is a function of the current token (an attention-flavoured bigram) – because the emission is keyed by the attended token’s identity, the prediction depends only on which token the query selects. In-context copy / induction (example-specific values) is what the multi-hop / stackable extension adds; this helper is the plumbing both share.

Parameters:

tokens (Sequence[int]) – a 1-D sequence of integer token ids.
context_length (int) – the attention window N.
num_symbols (int | None) – vocabulary size (for the one-hot query dim); inferred from tokens if omitted.
embeddings (ndarray | None) – optional (S, D) embedding table; if given the query is embeddings[token], otherwise a one-hot of dimension num_symbols.

Returns:

A list of (context, query, target) triples ready for mixle.inference.optimize().

Return type:

list[tuple[ndarray, ndarray, int]]

class VariationalEmbeddingAttentionDistribution(mean, log_var, emission, position_prior, sigma2=0.5, name=None, optimizer_state=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Responsibility-attention head over tied latent embeddings (mean-field posterior).

Parameters:

mean (np.ndarray)
log_var (np.ndarray)
emission (np.ndarray)
position_prior (np.ndarray)
sigma2 (float)
name (str | None)
optimizer_state (AttentionOptimizerState | dict[str, Any] | None)

density(x)[source]

Return the posterior-mean probability of one attention observation.

Parameters:: x (tuple[Any, int, int])
Return type:: float

log_density(x)[source]

Plug-in (posterior-mean) log conditional density log p(target | context, query).

Parameters:: x (tuple[Any, int, int])
Return type:: float

seq_log_density(x)[source]

Posterior-mean log density over an encoded batch -> (n,) (uses e = m).

Parameters:: x (tuple[ndarray, ndarray, ndarray])
Return type:: ndarray

predict_proba(context, query)[source]

Predictive target distribution from posterior-mean attention; (T,) or (n, T).

Parameters:

context (ndarray)
query (ndarray)

Return type:

embeddings()[source]

The learned (posterior-mean) tied embedding table (S, D).

Return type:: ndarray

sampler(seed=None)[source]

Sample iid observations from the posterior-mean plug-in law used by scoring.

Parameters:: seed (int | None)
Return type:: VariationalEmbeddingAttentionSampler

posterior_predictive_sampler(seed=None)[source]

Sample iid observations, independently drawing an embedding table for every event.

Parameters:: seed (int | None)
Return type:: VariationalEmbeddingAttentionSampler

estimator(pseudo_count=None)[source]

Return a variational EM estimator initialized with this model’s dimensions.

Parameters:: pseudo_count (float | None)
Return type:: VariationalEmbeddingAttentionEstimator

dist_to_encoder()[source]

Return the encoder for contexts, queries, and targets.

Return type:: VariationalEmbeddingAttentionDataEncoder

class VariationalEmbeddingAttentionEstimator(num_symbols, context_length, embed_dim, num_targets, *, sigma2=0.5, lr=0.05, mc=6, prior_strength=1.0, emission_smoothing=1e-4, seed=0, name=None, keys=None)[source]

Bases: ParameterEstimator

Stateless variational-EM estimator consuming explicit model-carried Adam state.

Parameters:

num_symbols (int)
context_length (int)
embed_dim (int)
num_targets (int)
sigma2 (float)
lr (float)
mc (int)
prior_strength (float)
emission_smoothing (float)
seed (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for variational embedding attention accumulators.

Return type:: VariationalEmbeddingAttentionAccumulatorFactory

estimate(nobs, suff_stat)[source]

Apply one variational EM update and return the updated attention distribution.

Parameters:: nobs (float | None)
Return type:: VariationalEmbeddingAttentionDistribution

class ChainedAttentionDistribution(keys, emission, sigma2=0.1, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

An L-hop stack of responsibility-attention heads (chained, content-addressed).

Parameters:

keys (np.ndarray)
emission (np.ndarray)
sigma2 (float)
name (str | None)

density(x)[source]

Return the probability of one chained-attention observation.

Parameters:: x (tuple[Any, Any, int, int])
Return type:: float

log_density(x)[source]

Return the log-probability of one context/query/target observation.

Parameters:: x (tuple[Any, Any, int, int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded chained-attention observations.

Return type:: ndarray

predict_proba(context_keys, context_values, query)[source]

Predictive target distribution (target marginalized); (T,) or (n, T).

Parameters:

context_keys (ndarray)
context_values (ndarray)
query (ndarray)

Return type:

sampler(seed=None)[source]

Return a sampler for synthetic chained-attention observations.

Parameters:: seed (int | None)
Return type:: ChainedAttentionSampler

estimator(pseudo_count=None)[source]

Return a closed-form EM estimator for this attention chain.

Parameters:: pseudo_count (float | None)
Return type:: ChainedAttentionEstimator

dist_to_encoder()[source]

Return the encoder for context keys, values, query symbols, and targets.

Return type:: ChainedAttentionDataEncoder

class ChainedAttentionEstimator(n_hops, num_symbols, num_targets, *, sigma2=0.1, emission_smoothing=1e-4, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form EM estimator: per-hop key tables (GMM means of one-hot queries) + emission counts.

Parameters:

n_hops (int)
num_symbols (int)
num_targets (int)
sigma2 (float)
emission_smoothing (float)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for chained-attention sufficient-statistic accumulators.

Return type:: ChainedAttentionAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate key tables and emissions from accumulated forward-backward statistics.

Parameters:: nobs (float | None)
Return type:: ChainedAttentionDistribution

class VariationalMultiHopAttentionDistribution(mean, log_var, emission, sigma2=0.3, name=None, optimizer_state=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A 2-hop chain over tied latent embeddings (mean-field posterior).

Parameters:

sigma2 (float)
name (str | None)
optimizer_state (AttentionOptimizerState | dict[str, Any] | None)

density(x)[source]

Return the probability of one context/query/target observation.

Return type:: float

log_density(x)[source]

Return the log-probability of one context/query/target observation.

Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded two-hop attention observations.

Return type:: ndarray

predict_proba(context_keys, context_values, query)[source]

Predictive target distribution (posterior-mean embeddings); (T,) or (n, T).

Return type:: ndarray

embeddings()[source]

Return posterior mean embeddings for the tied latent symbols.

Return type:: ndarray

sampler(seed=None)[source]

Sample iid observations from the posterior-mean plug-in law used by scoring.

Parameters:: seed (int | None)
Return type:: VariationalMultiHopAttentionSampler

posterior_predictive_sampler(seed=None)[source]

Sample iid observations, independently drawing an embedding table for every event.

Parameters:: seed (int | None)
Return type:: VariationalMultiHopAttentionSampler

estimator(pseudo_count=None)[source]

Return a variational EM estimator initialized with this model’s dimensions.

Parameters:: pseudo_count (float | None)
Return type:: VariationalMultiHopAttentionEstimator

dist_to_encoder()[source]

Return the encoder for context keys, values, query symbols, and targets.

Return type:: VariationalMultiHopAttentionDataEncoder

class VariationalMultiHopAttentionEstimator(num_symbols, embed_dim, num_targets, *, sigma2=0.3, lr=0.05, mc=5, prior_strength=0.1, anneal_iters=100, emission_smoothing=1e-4, seed=0, name=None, keys=None)[source]

Bases: ParameterEstimator

Stateless variational-EM estimator with model-carried Adam state and prior annealing.

Parameters:

num_symbols (int)
embed_dim (int)
num_targets (int)
sigma2 (float)
lr (float)
mc (int)
prior_strength (float)
anneal_iters (int)
emission_smoothing (float)
seed (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]: Return a factory for variational multi-hop attention accumulators.

estimate(nobs, suff_stat)[source]: Apply one variational EM update and return the updated attention distribution.

class Posterior[source]

Bases: ABC

A model-derived distribution exposing one uniform interface for draws and summaries.

Only sample() (a single draw) is required. samples() loops it by default; vectorized subtypes override it. mean / mode / marginals / entropy / interval raise NotImplementedError unless a subtype defines them, so each realization implements exactly the summaries that are meaningful for it.

abstractmethod sample(rng=None)[source]

Draw a single sample from the posterior (rng is a seed, RandomState, or None).

Parameters:: rng (Any)
Return type:: Any

samples(n, rng=None)[source]

Draw n samples; loops sample() by default (override for a vectorized draw).

Parameters:

n (int)
rng (Any)

Return type:

mean()[source]

The posterior mean E[.] (not defined for every realization).

Return type:: Any

mode()[source]

The maximum-a-posteriori configuration (not defined for every realization).

Return type:: Any

marginals()[source]

Per-component marginals – e.g. the EM E-step responsibilities (not always defined).

Return type:: Any

entropy()[source]

The entropy H[q] (not always defined).

Return type:: Any

interval(level=0.9)[source]

A central credible interval at the given level (not always defined).

Parameters:: level (float)
Return type:: Any

class LatentPosterior[source]

Bases: Posterior

The posterior q(z | x) over a model’s latent variables (exact or mean-field).

abstractmethod marginals()[source]

Per-latent marginal responsibilities – the quantity the EM M-step consumes.

Return type:: Any

abstractmethod sample(rng=None)[source]

Draw the latent variables z ~ q(z | x) (rng is a seed, RandomState, or None).

Parameters:: rng (Any)
Return type:: Any

abstractmethod mode()[source]

The maximum-a-posteriori latent configuration.

Return type:: Any

abstractmethod entropy()[source]

The entropy H[q] (per latent / per observation).

Return type:: Any

class CategoricalLatentPosterior(responsibilities, support=None)[source]

Bases: LatentPosterior

Independent categorical latents q(z) = prod_i Cat(z_i; r_i).

The exact posterior for a finite mixture’s component labels (and the per-token topic factor of an LDA document). responsibilities is the row-stochastic (N, K) matrix r_ik = q(z_i = k | x_i); support maps column k to its latent label (default 0..K-1).

Parameters:

responsibilities (ndarray)
support (Any)

marginals()[source]

The (N, K) responsibility matrix.

Return type:: ndarray

sample(rng=None)[source]

Draw one latent label per observation; returns an (N,) array of support labels.

Parameters:: rng (Any)
Return type:: ndarray

mode()[source]

The most-probable latent label per observation, (N,).

Return type:: ndarray

entropy()[source]

Per-observation entropy -sum_k r_ik log r_ik, (N,).

Return type:: ndarray

class MarkovChainLatentPosterior(log_pi, log_A, log_b)[source]

Bases: LatentPosterior

Chain-structured latents q(z_1..z_T | x) for an HMM – exact, via forward-backward.

Built from the log initial distribution log_pi (K,), the log transition matrix log_A (K, K) (row j -> column k), and the per-position emission log-likelihoods log_b (T, K). The latents are coupled (a Markov chain), so:

marginals() -> the (T, K) forward-backward smoothing probabilities q(z_t = k | x) sample(rng) -> a full state path (T,) by forward-filter / backward-sample (FFBS) mode() -> the Viterbi (max-product) path (T,) entropy() -> the exact scalar chain entropy H[q(z_1..z_T | x)]

Parameters:

log_pi (ndarray)
log_A (ndarray)
log_b (ndarray)

log_likelihood()[source]

The sequence log-likelihood log p(x) (the forward normalizer).

Return type:: float

property is_impossible: bool: Whether the supplied evidence has zero probability under the chain model.

marginals()[source]

The (T, K) smoothing probabilities q(z_t = k | x).

Return type:: ndarray

sample(rng=None)[source]

Draw a state path z ~ q(z | x) via FFBS; returns (T,) state indices.

Parameters:: rng (Any)
Return type:: ndarray

mode()[source]

The Viterbi (max-product) MAP path (T,).

Return type:: ndarray

entropy()[source]

Exact scalar chain entropy via the FFBS factorization q = q(z_T) prod_t q(z_t|z_{t+1}).

Return type:: float

to_dataframe()[source]

Return the per-position state posterior as a pandas.DataFrame.

One row per sequence position t with columns t (position), state (the Viterbi MAP state from mode()), and one state_{k}_prob column per latent state holding the forward-backward smoothing probability from marginals(). Deterministic: unlike sample(), mode/marginals are exact closed-form quantities, not random draws. Requires the pandas extra (pip install mixle[pandas]).

Return type:: Any

to_parquet(path, **kwargs)[source]

Write the per-position state posterior to a Parquet file; see to_dataframe().

kwargs forward to DataFrame.to_parquet (e.g. engine=, compression=). Needs a Parquet engine in addition to pandas – pip install mixle[arrow] (pyarrow) or fastparquet.

Parameters:

path (Any)
kwargs (Any)

Return type:

None

class MeanFieldLDAPosterior(gamma, phi, counts)[source]

Bases: LatentPosterior

Mean-field variational posterior for one LDA document: q(theta, z) = Dir(theta; gamma) prod_n Cat(z_n; phi_n).

The Blei-Ng-Jordan variational factorization made into an object instead of loose gamma/phi arrays. gamma (K,) is the document’s variational Dirichlet parameter (q(theta)); phi (W, K) the per-distinct-word topic responsibilities (q(z_n), rows sum to 1); counts (W,) the word counts. Note the latents are heterogeneous (continuous theta + discrete z), so sample returns the pair (theta, z) and entropy is a scalar.

Parameters:

gamma (ndarray)
phi (ndarray)
counts (ndarray)

topic_proportions()[source]

The mean document-topic distribution E_q[theta] = gamma / sum(gamma) (K,).

Return type:: ndarray

marginals()[source]

The (W, K) per-distinct-word topic responsibilities q(z_n).

Return type:: ndarray

sample(rng=None)[source]

Draw the full latent (theta, z): theta ~ Dir(gamma) and per-token topics z from phi.

Parameters:: rng (Any)
Return type:: tuple[ndarray, ndarray]

mode()[source]

The MAP topic per distinct word, argmax_k phi_wk (W,).

Return type:: ndarray

entropy()[source]

Mean-field entropy H[q(theta)] + sum_w count_w H[Cat(phi_w)] (scalar).

Return type:: float

exception ImpossiblePosteriorError[source]

Bases: ValueError

Raised when an operation requires a posterior law but the evidence has zero probability.

class ImpossiblePosteriorResult(reason, log_evidence=-inf)[source]

Bases: object

Typed explanation that a model/evidence pair does not define a conditional probability law.

Parameters:

reason (str)
log_evidence (float)

class MixtureEstimator(estimators, fixed_weights=None, suff_stat=None, pseudo_count=None, name=None, keys=(None, None), prior=None, w_min=0.0, robust=False, init=None)[source]

Bases: ParameterEstimator

Estimator for mixture weights and component distributions from EM sufficient statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
fixed_weights (list[float] | np.ndarray | None)
suff_stat (np.ndarray | None)
pseudo_count (float | None)
name (str | None)
keys (tuple[str | None, str | None])
prior (SequenceEncodableProbabilityDistribution | None)
w_min (float)
robust (bool)
init (str | None)

accumulator_factory()[source]

Return a mixture accumulator factory matching the component estimators.

Return type:: MixtureAccumulatorFactory

get_prior()[source]

Return the joint mixture prior, or None for a plain MLE estimator.

When a weight prior is attached the joint prior is the (weight_prior, tuple(component priors)) pair produced by mixture_prior().

Return type:: SequenceEncodableProbabilityDistribution | None

set_prior(prior)[source]

Attach a weight prior (and optional per-component priors).

With a (symmetric) Dirichlet weight prior the estimator switches to the conjugate MAP weight update; component priors, when supplied, are delegated to each component estimator via estimator.set_prior (those carry out their own conjugate updates). prior=None leaves the estimator a plain MLE estimator (byte-identical behaviour).

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

model_log_density(model)[source]

Log density of the model parameters under this estimator’s prior (ELBO global term).

Returns the Dirichlet weight-prior log-density evaluated at model.w plus the sum of each component estimator’s model_log_density at the corresponding component model. Returns 0.0 for a plain MLE estimator with no priors anywhere.

Parameters:: model (MixtureDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a mixture distribution from EM sufficient statistics.

suff_stat is (component_counts, component_suff_stats). Component parameters are delegated to the child estimators. Mixture weights follow the fixed-weight, conjugate-prior, pseudo-count, or plain-MLE path selected by the estimator configuration. Plain-MLE weights may be floored by w_min and are always renormalized.

Parameters:

nobs (float | None) – Unused compatibility argument from ParameterEstimator.
suff_stat (tuple[ndarray, tuple[Any, ...]]) – Serialized mixture sufficient statistics.

Returns:

Fitted MixtureDistribution.

Return type:

MixtureDistribution

class MixtureEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerator over the deduplicated union of weighted component supports.

Parameters:: dist (MixtureDistribution)

class MultivariateGaussianDistribution(mu, covar=MISSING, name=None, keys=None, covariance=MISSING, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Multivariate normal distribution with mean vector mu and full covariance matrix covar.

Parameters:

mu (list[float] | ndarray)
covar (list[list[float]] | ndarray)
name (str | None)
keys (str | None)
covariance (list[list[float]] | ndarray)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for multivariate Gaussian generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the multivariate Gaussian.

static exp_family_sufficient_statistics(x, engine)[source]

Return vector/matrix sufficient statistics for generated MVN scoring.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return natural parameters for generated MVN scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return the full-covariance Gaussian log partition.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return row-wise legacy accumulator statistics for generated resident reductions.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

set_prior(prior)[source]

Attach a parameter prior and precompute conjugate-prior expectations.

With a NormalWishart(m0, kappa, W, nu) prior over (mu, Lambda=covar^-1) this caches the prior parameters and E[ln|Lambda|], the quantities needed by expected_log_density. Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | mu, Lambda)] under the NormalWishart prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Evaluate the density at x.

Parameters:: x (np.ndarray) – Observation from multivariate Gaussian distribution.
Returns:: Density at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density at x.

The log-density is given by

log(p(x)) = -0.5*k*log(2*pi) - 0.5*log|covar| - 0.5*(x-mu)’ covar^{-1} (x-mu).

Parameters:: x (np.ndarray) – Observation from multivariate Gaussian distribution.
Returns:: Log-density at x.
Return type:: float

density_cumulative(x)[source]

Exact probability-ordered cumulative G(x) = P(p(Y) >= p(x)) – the highest-density-region mass whose boundary passes through x (the multivariate analogue of a CDF; a coordinate-wise CDF is undefined without a total order on R^d).

For a multivariate Gaussian p(y) >= p(x) iff the squared Mahalanobis distance is no larger, and that distance is chi-square with dim degrees of freedom, so G(x) = chi2.cdf(maha2, dim). Used by mixle.enumeration.density_rank.density_rank() to return an EXACT cumulative for the MVN.

Parameters:: x (ndarray)
Return type:: float

density_quantile(q)[source]

Inverse of density_cumulative(): a representative point at cumulative-density index q.

The multivariate analogue of a quantile / inverse-CDF: a coordinate-wise quantile is undefined without a total order on R^d, but the density ordering gives one. q is the highest-density region mass, so the boundary is the squared-Mahalanobis level chi2.ppf(q, dim); we return a representative point on that contour, mu + sqrt(level) * L[:, 0] where covar = L L^T (so its Mahalanobis distance is exactly the level). Sweeping q enumerates the support in descending density.

Parameters:: q (float)
Return type:: ndarray

seq_log_density(x)[source]

Vectorized evaluation of the log-density at a sequence-encoded input x.

Parameters:: x (np.ndarray) – Encoded data matrix with shape (sz, dim) from MultivariateGaussianDataEncoder.seq_encode().
Returns:: Numpy array of length sz containing the log-density of each encoded observation.
Return type:: ndarray

static backend_log_density_from_params(x, mu, inv_covar, log_det, engine)[source]

Engine-neutral multivariate Gaussian log-density from inverse covariance.

Parameters:

x (Any)
mu (Any)
inv_covar (Any)
log_det (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked full-covariance Gaussian parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[MultivariateGaussianDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of full-covariance Gaussian log densities.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked legacy sufficient statistics on the active engine.

The weighted second moment sum_n w[n,k] x_n x_n^T is accumulated per component as a gemm (x * w[:, k]).T @ x instead of reducing a per-sample, per-component (n, k, dim, dim) outer-product tensor. That intermediate is N*K*dim*dim (~20 GB at n=2e4, k=8, dim=128 — it OOMs a GPU); the per-component gemm holds only an (n, dim) temporary and hands the reduction to BLAS/cuBLAS. The first moment is likewise w.T @ x rather than a reduced (n, k, dim) tensor.

Parameters:

x (Any)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

to_fisher(**kwargs)[source]: Return this distribution’s own Fisher view.

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional seed for the sampler’s random state.
Returns:: A configured MultivariateGaussianSampler.

condition(observed)[source]

Return the conditional distribution over the unobserved dimensions given observed.

observed maps dimension index to its fixed value; the result is the closed-form Gaussian conditional over the remaining dimensions (in increasing index order):

mu_{u|o} = mu_u + Sigma_uo Sigma_oo^{-1} (x_o - mu_o), Sigma_{u|o} = Sigma_uu - Sigma_uo Sigma_oo^{-1} Sigma_ou.

Sampling the result is given=-style conditional sampling (draw the unobserved coordinates consistent with the observed ones). Raises if no dimension is left unobserved.

Parameters:: observed (dict[int, float])
Return type:: MultivariateGaussianDistribution

marginal(keep)[source]

Return the marginal Gaussian over dimensions keep.

N(mu, Sigma) marginalized to index set keep is N(mu[keep], Sigma[keep, keep]). The order of keep is preserved, so the result’s dimensions follow the given order.

Parameters:: keep (Sequence[int])
Return type:: MultivariateGaussianDistribution

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s shape.

If pseudo_count is passed, the current mean and covariance are used to regularize the estimate.

Parameters:: pseudo_count (float | None) – Optional smoothing count applied to mean and covariance estimates.
Returns:: A MultivariateGaussianEstimator.

dist_to_encoder()[source]

Return an encoder for iid multivariate Gaussian observations.

Return type:: MultivariateGaussianDataEncoder

class MultivariateGaussianEstimator(dim=None, pseudo_count=(None, None), suff_stat=(None, None), name=None, keys=None, prior=None, min_covar=None, ridge=None, track_conditioning=False, degenerate_ratio=1.0e-6)[source]

Bases: ParameterEstimator

Estimator for multivariate Gaussian distributions.

The fitted covariance is NOT the raw maximum-likelihood estimate unless ridge=0.0 is passed: by default the M-step regularizes each diagonal entry of the empirical covariance as cov_ii + eps_i with eps_i = ridge * cov_ii (default ridge=1e-6) so a singular empirical covariance – e.g. an EM component holding fewer than d points – remains factorizable. Each eps_i is RELATIVE to its own coordinate’s variance, so the ridge is a negligible ~1e-6 relative perturbation whatever the units, per column: the fit is equivariant under any per-coordinate change of units, and heterogeneous-unit data is no longer penalized (the former trace-scaled ridge priced a microscale column’s jitter off the macroscale columns, inflating the smallest variances – and with them the log-likelihood and AIC – by up to ~5 orders of magnitude, T1-05). A coordinate with no positive variance of its own gets its jitter from the mean of the coordinates that have one; the absolute min_covar (default 1e-8) is the last resort for a covariance with no scale at all (all-zero diagonal, or ridge=0.0) and becomes a hard per-coordinate floor as soon as it is passed explicitly.

A materially binding ridge is recorded on the fitted distribution as a covariance-ridged(...) entry in numerical_repairs() – and therefore in fit_provenance().repairs. “Materially” means the jitter exceeded _RIDGE_MATERIAL_RATIO of the smallest raw variance (an explicit min_covar dominating a small variance, or manufactured jitter on a variance-free coordinate – never the default per-coordinate ridge on a full-rank fit), or the raw covariance was not positive-definite on its own and the ridge is what makes it factorable – the rank-deficient case this ridge exists for. Pass ridge=0.0 to recover the exact MLE up to the min_covar absolute jitter floor.

The fit is SHIFT-EQUIVARIANT: fit(x + c) returns the covariance of x + c to within a few ulps for any constant c the data can carry, epoch seconds (~1.7e9) included. That is not free from the declared (sum, sum2, count) statistics – their covariance is the cancellation-prone E[xx^T] - mu mu^T, which at offset 1e7 fitted a visibly wrong correlation and at 1e8 a matrix so far from positive-definite that the constructor refused it – so MultivariateGaussianAccumulator carries a conditioning-gated shift-anchored moment track and this estimator reads it. Statistics that arrive already reduced and WITHOUT that track (an engine kernel’s stacked moments, a hand-built tuple) cannot be corrected here and take the historical path; when they are too ill-conditioned for it, estimate warns rather than returning a covariance it cannot stand behind.

Parameters:

dim (int | None)
pseudo_count (float | tuple[float | None, float | None] | None)
suff_stat (tuple[ndarray | None, ndarray | None] | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)
min_covar (float | None)
ridge (float | None)
track_conditioning (bool)
degenerate_ratio (float)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: MultivariateGaussianAccumulatorFactory

model_log_density(model)[source]

Log-density of the model parameters under the NormalWishart prior (ELBO global term).

The prior is over (mu, Lambda=covar^-1), so the model’s covariance is inverted before scoring.

Parameters:: model (MultivariateGaussianDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a multivariate normal distribution with from aggregated sufficient statistics.

Suff_stat is a Tuple of size 3 containing:: suff_stat[0] (np.ndarray): Component-wise sum of weighted observation values. suff_stat[1] (np.ndarray): Component-wise sum of weighted squared observation values. suff_stat[2] (float): Sum of weights for each observation.

Parameters:

nobs (Optional[float]) – Weighted number of observations used in aggregation of suff stats.
suff_stat (Tuple[np.ndarray, np.ndarray, float]) – See above for details.

Returns:

MultivariateGaussianDistribution

Return type:

MultivariateGaussianDistribution

class NullDistribution(name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Non-generative likelihood identity assigning log-score zero to every observation.

Parameters:: name (str | None)

classmethod compute_capabilities()[source]: Declare backend support for the zero-cost null distribution.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the null distribution.

density(x)[source]

Density of NullDistribution. Always 1.0.

Parameters:: x (Optional[Any]) – Observation of any type (ignored).
Returns:: 1.0 for any input.
Return type:: float

density_semantics()[source]: Identify this exact score as a non-generative likelihood factor.

log_density(x)[source]

Log-density of NullDistribution. Always 0.0.

Parameters:: x (Optional[Any]) – Observation of any type (ignored).
Returns:: 0.0 for any input.
Return type:: float

seq_log_density(x)[source]

Vectorized log-density evaluated at sequence encoded input x. Always 0.0.

Parameters:: x (Optional[Any]) – Sequence encoded data; NullDataEncoder returns the sequence length.
Returns:: A zero vector with one entry per encoded observation.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density: zero for every encoded row.

Parameters:

x (Any | None)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for homogeneous null mixtures.

Parameters:

dists (tuple[NullDistribution, ...])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) zero matrix for null-component log densities.

Parameters:

x (Any | None)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return empty legacy statistics for each null component.

Parameters:

x (Any | None)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[None, …]

sampler(seed=None)[source]

Reject generation from a likelihood identity with no normalized sample space.

Parameters:: seed (int | None)
Return type:: NullSampler

estimator(pseudo_count=None)[source]

Create an estimator for the null distribution.

Parameters:: pseudo_count (Optional[float]) – Kept for interface consistency (has no effect on estimation).
Returns:: NullEstimator configured with this distribution’s name.
Return type:: NullEstimator

dist_to_encoder()[source]

Return the encoder used for null-distribution observations.

Return type:: NullDataEncoder

enumerator()[source]

Reject enumeration because a neutral factor has no probability support.

Return type:: NullEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Reject indexing because a neutral factor has no probability support.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Reject cross-indexing because neutral factors have no probability support.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Reject pairwise cross-indexing because neutral factors have no probability support.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class NullEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator that always produces a NullDistribution regardless of the data.

Parameters:

pseudo_count (float | None)
suff_stat (Any | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for null accumulators.

Return type:: NullAccumulatorFactory

estimate(nobs, suff_stat=None)[source]

Returns a NullDistribution; arguments are ignored.

Parameters:

nobs (Optional[float]) – Number of observations (ignored).
suff_stat (Optional[Any]) – Sufficient statistics (ignored).

Returns:

NullDistribution carrying this estimator’s name.

Return type:

NullDistribution

class NullEnumerator(dist)[source]

Bases: DistributionEnumerator

Deprecated guard that rejects enumeration of a neutral factor.

Parameters:: dist (NullDistribution)

exception NeutralFactorError[source]

Bases: TypeError

Raised when a neutral likelihood identity is used as a generative law.

marginalized(dist, missing_value=MISSING)[source]

Wrap dist so a missing_value entry is marginalized out (not modeled).

The wrapped field contributes log-density 0 and no sufficient statistics for missing observations, so estimation uses only the present ones. Equivalent to OptionalDistribution(dist, p=None, missing_value=missing_value) – this is the principled missing-at-random treatment, not a degenerate case.

Parameters:

dist (Any)
missing_value (Any)

Return type:

composite_with_missing(dists, missing_value=MISSING)[source]

Build a CompositeDistribution over dists in which every field tolerates missing_value.

Each field is wrapped with marginalized(), so any field of an observation tuple may be missing_value and is integrated out of the likelihood (scoring and EM). Build the composite once and pass MISSING for absent fields in your data – no per-field bookkeeping.

Parameters:

dists (Sequence[Any])
missing_value (Any)

Return type:

class OptionalDistribution(dist, p=None, missing_value=None, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Mixture-style wrapper that models missing observations explicitly.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
p (float | None)
missing_value (Any)
name (str | None)
prior (tuple[Any, Any] | None)

compute_capabilities()[source]: Return compute capabilities inherited from the observed-data distribution.

get_prior()[source]

Return the joint prior as (p_prior, dist_prior).

Return type:: tuple[Any, Any]

set_prior(prior)[source]

Distribute the joint prior (p_prior, dist_prior) to the missing probability and base dist.

prior=None is a no-op (point model, existing behavior byte-identical). Otherwise the first element is a conjugate Beta prior on p (caching the digamma expectations used by expected_log_density) and the second is pushed to the base distribution’s set_prior.

Parameters:: prior (tuple[Any, Any] | None)
Return type:: None

expected_log_density(x)[source]

Posterior-expected log-density E_q[log p(x)] at x.

With a conjugate Beta prior on p the expectation over p is available in closed form via digamma terms (missing => da - dab; observed => db - dab + dist.expected_log_density(x)); otherwise this falls back to the plug-in log_density.

Parameters:: x (T)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized posterior-expected log-density; falls back to seq_log_density without a prior.

Parameters:: x (tuple[int, ndarray, ndarray, E])
Return type:: ndarray

compute_declaration()[source]: Return a structured declaration for the optional missingness wrapper.

density(x)[source]

Evaluate the density of the Optional distribution at x.

See log_density() for details.

Parameters:: x (T) – Observation from base dist or missing value.
Returns:: Density at x.
Return type:: float

density_semantics()[source]: Return child semantics for a proper gate or likelihood-factor semantics for MAR.

property marginalized_core

Return the wrapped law when this is a pure marginalization, else None.

Without a missingness rate this distribution is a likelihood factor: it contributes 1 where the value is absent rather than a normalized density over values-plus-missing. That makes it non-generative, but only because p was not supplied – the wrapped law is untouched, and giving p makes the whole thing generative again. Callers that need to tell “unnormalized because we are marginalizing over missingness” apart from “intrinsically cannot generate” (a scoring-only leaf) read this: the former returns its core, the latter has no such attribute.

log_density(x)[source]

Evalute the log density of the Optional distribution at x.

If x is a missing value: return log(p) if p is not None, else return 0.0 If x is not the missing_value: if p is not None, return the log_denisty(x) at base dist + log(1-p) else: return log_density(x).

Parameters:: x (T) – Observation from base dist or missing value.
Returns:: Log-density at x.
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[int, ndarray, ndarray, E])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for optional encoded data.

Parameters:

x (tuple[int, ndarray, ndarray, E])
engine (Any)

Return type:

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked optional-wrapper parameters for homogeneous mixture kernels.

Parameters:

dists (Sequence[OptionalDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of optional-wrapper log densities.

Parameters:

x (tuple[int, ndarray, ndarray, E])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy optional-wrapper sufficient statistics.

Parameters:

x (tuple[int, ndarray, ndarray, E])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

to_fisher(**kwargs)[source]: Fisher view for the optional/missing-gate.

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: OptionalSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: OptionalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: OptionalDataEncoder

enumerator()[source]

Returns an OptionalEnumerator iterating the support (including the missing value) in descending probability order.

Return type:: OptionalEnumerator

class OptionalEstimator(estimator, missing_value=None, est_prob=False, pseudo_count=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate optional missingness probability and observed-data distribution parameters.

Parameters:

estimator (ParameterEstimator)
missing_value (Any)
est_prob (bool)
pseudo_count (float | None)
name (str | None)
keys (str | None)
prior (tuple[Any, Any] | None)

accumulator_factory()[source]

Return an accumulator factory for optional sufficient statistics.

Return type:: OptionalEstimatorAccumulatorFactory

get_prior()[source]

Return the joint prior as (p_prior, dist_prior) from this estimator and the base estimator.

Return type:: tuple[Any, Any]

set_prior(prior)[source]

Distribute (p_prior, dist_prior) to this estimator’s p prior and the base estimator.

prior=None is a no-op (empirical/pseudo-count path stays byte-identical). The first element is a conjugate Beta prior on p; the second is pushed to the base estimator via set_prior.

Parameters:: prior (tuple[Any, Any] | None)
Return type:: None

model_log_density(model)[source]

Sum the Beta-prior log-density at p and the base estimator’s term (ELBO global term).

Parameters:: model (OptionalDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate an OptionalDistribution from missing/observed sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[list[float], SS] | None)

Return type:

OptionalDistribution

exception NonGenerativeOptionalError[source]

Bases: TypeError

Raised when a marginalized optional likelihood factor is used to generate data.

class OptionalEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate the optional support by merging missing mass with observed support.

Parameters:: dist (OptionalDistribution)

class PoissonDistribution(lam, name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Poisson distribution over non-negative integer counts with rate lam.

Parameters:

lam (float)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for generated Poisson density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Poisson distribution.

static exp_family_sufficient_statistics(x, engine)[source]

Return Poisson sufficient statistics for generated scoring.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Poisson sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Poisson natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Poisson log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

static exp_family_base_measure(x, engine)[source]

Return Poisson base measure for generated scoring.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

set_prior(prior)[source]

Attach a parameter prior and cache the conjugate Gamma expectations.

With a Gamma(k, theta) prior over the rate lam this caches (k, theta) so that expected_log_density(x) = (psi(k) + ln theta)*x - k*theta - gammaln(x+1) (the VB E-step term using E[ln lam] = psi(k) + ln theta and E[lam] = k*theta). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | lam)] under the Gamma prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (float)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

density(x)[source]

Evaluate the density of Poisson distribution at observation x.

Calls np.exp(log_density(x)). See log_density() for details.

Parameters:: x (int) – Must be a non-negative integer value (0,1,2,….).
Returns:: Density of Poisson distribution evaluated at x.
Return type:: float

log_density(x)[source]

Log-density of Poisson distribution evaluated at x.

Log-density given by,

log(p_mat(x_mat=x; lam) = x*log(lam) - log(x!) - lam, for x in {0,1,2,…}

and -np.inf else.

Note: log(Gamma(x+1.0)) = log(x!), where Gamma is the gamma function.

Parameters:: x (int) – Must be a non-negative integer value (0,1,2,….).
Returns:: Log-density of Poisson distribution evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized log-density evaluated on sequence encoded x.

Arg value x (Tuple[np.ndarray[int], np.ndarray[float]]) is seq_encoded Poisson data from PoissonDataEncoder.seq_encode(), containing

x[0] (np.ndarray[int]): Non-negative integer valued Poisson iid observations,
x[1] (np.ndarray[float]): np.log(Gamma(x[0]+1.0)), Gamma is the gamma function.

Parameters:: x (tuple[ndarray, ndarray]) – See above for details.
Returns:: Numpy array of log-density evaluated at each encoded observation value x.
Return type:: ndarray

static backend_log_density_from_params(vals, log_fact, lam, engine)[source]

Engine-neutral Poisson log-density from explicit parameters.

Parameters:

vals (Any)
log_fact (Any)
lam (Any)
engine (Any)

Return type:

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Poisson parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[PoissonDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Poisson log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Poisson sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

to_fisher(**kwargs)[source]: Return the Poisson’s count-family Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x) = Q(floor(x)+1, lam).

Parameters:: x (float)
Return type:: float

skewness()[source]

Skewness 1/sqrt(lambda).

Return type:: float

kurtosis()[source]

Excess kurtosis 1/lambda.

Return type:: float

entropy()[source]

Shannon entropy in nats, by exact summation of the standard series.

The Poisson entropy -sum_k p_k log p_k has no closed form; the series is summed over the effective support k <= lam + 40 sqrt(lam) + 40, beyond which the remaining terms are far below double rounding (the tail mass decays super-geometrically).

Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) (via scipy poisson).

Parameters:: q (float)
Return type:: float

mode()[source]

Mode floor(lambda).

Return type:: float

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional seed for the sampler’s random state.
Returns:: A configured PoissonSampler.
Return type:: PoissonSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s shape.

Parameters:: pseudo_count (float | None) – Optional smoothing count applied to the current rate.
Returns:: A PoissonEstimator.
Return type:: PoissonEstimator

dist_to_encoder()[source]

Return an encoder for iid Poisson observations.

Return type:: PoissonDataEncoder

enumerator()[source]

Return an enumerator over nonnegative counts in descending probability order.

Return type:: PoissonEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index by walking the Poisson mode outward.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an aligned cross-bin view over bounded Poisson high-mass regions.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an aligned cross-bin view over two bounded Poisson high-mass regions.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class PoissonEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate Poisson rate parameters from accumulated sufficient statistics.

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: PoissonAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s rate under the Gamma prior (ELBO global term).

Parameters:: model (PoissonDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a Poisson distribution from aggregated sufficient statistics.

The tuple is interpreted as (count, sum).

Parameters:

nobs (float | None) – Unused; accepted for the ParameterEstimator interface.
suff_stat (tuple[float, float]) – Aggregated Poisson sufficient statistics.

Returns:

A fitted Poisson distribution.

Return type:

PoissonDistribution

class PoissonEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate Poisson support values in descending probability order.

Parameters:: dist (PoissonDistribution)

class PointMassDistribution(value, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Fixed Dirac/point-mass distribution assigning all mass to one value.

Parameters:

value (Any)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare generic NumPy/Torch scoring support for fixed atoms.

classmethod compute_declaration()[source]: Return the declaration for a fixed non-estimated atom.

property value: Any: Return an independent copy so callers cannot mutate the model’s atom.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density from encoded equality flags.

Parameters:

x (ndarray)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked point-mass parameters for identical fixed atoms.

Parameters:

dists (Sequence[PointMassDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of point-mass log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return per-component empty statistics for fixed point masses.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[None, …]

support_size()[source]

A single atom.

Return type:: int

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: PointMassSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: PointMassEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: PointMassDataEncoder

enumerator()[source]

Return an enumerator over the distribution support when available.

Return type:: PointMassEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Return a bounded quantized support index for this observation.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

class PointMassEstimator(value, pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator that always returns the configured point mass.

Parameters:

value (Any)
pseudo_count (float | None)
suff_stat (Any | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for point-mass no-op accumulators.

Return type:: PointMassAccumulatorFactory

estimate(nobs, suff_stat=None)[source]

Return the configured point mass unchanged.

Parameters:

nobs (float | None)
suff_stat (Any | None)

Return type:

PointMassDistribution

class PointMassEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate the single atom of a PointMassDistribution.

Parameters:: dist (PointMassDistribution)

class SelectDistribution(dists, choice_function, weights=None)[source]

Bases: SequenceEncodableProbabilityDistribution

SelectDistribution routes each observation to one child distribution via a choice function.

Two modes, set by weights:

Conditional (weights is None, the default) – the density is p(x) = p_{c(x)}(x): the choice function selects which child scores x and the result is that child’s density. There is no branch distribution, so this is a density conditioned on the branch and cannot be sampled as a standalone generative model.
Dispatch mixture (weights given) – the density is p(x) = w_{c(x)} * p_{c(x)}(x), a normalized mixture over the union of the child supports in which the choice function plays the role of an observed component label. This is the right model for data of disjoint types (e.g. a mix of strings and numbers, where the type identifies the component): unlike MixtureDistribution the component is observed, so fitting is closed-form (the weights are the branch proportions, each child is fit on its routed subset – no EM) and sampling draws a branch from weights then a value from that child.

For the dispatch-mixture density to be normalized the choice function must partition the observation space consistently with the children, i.e. every value a child can emit must route back to that child (choice_function(x) == k for x in child k’s support).

Parameters:

dists (Sequence[SequenceEncodableProbabilityDistribution])
choice_function (Callable[[T], int])
weights (Sequence[float] | None)

property count: int: Number of routed children, derived from the immutable child tuple.

classmethod by_type(children, weights='auto')[source]

Build a dispatch mixture that routes observations to children by their Python type.

The friendly constructor for heterogeneous-typed data: instead of hand-writing (and registering) a choice function, pass each child with the type(s) it emits and the routing is derived automatically via a serializable TypeDispatch.

Example – a mixture of strings and counts:

sel = SelectDistribution.by_type([(str, cat), (int, poisson)])
fitted = estimate(mixed_data, sel.estimator())   # learns branch weights + each child

Parameters:

children (Sequence[tuple[Any, SequenceEncodableProbabilityDistribution]]) – Sequence of (type_spec, distribution) pairs. type_spec is a type (str, int, float, …), a friendly name ('str', 'number', 'float', 'bytes', 'bool', 'complex'), or a tuple of these. Observations route to the FIRST matching child, so order more specific types first.
weights (Any) – 'auto' (default) seeds uniform branch weights, giving a fittable generative dispatch mixture whose .estimator() learns the true proportions; None gives the weightless conditional density; or pass an explicit weight sequence.

Returns:

SelectDistribution routing by a TypeDispatch choice function.

Return type:

SelectDistribution

compute_capabilities()[source]: Declare generated-compute support inherited from all selectable children.

density_semantics()[source]: Distinguish conditional routing factors from normalized dispatch mixtures.

compute_declaration()[source]: Return the generated-compute declaration for the select distribution.

density(x)[source]

Density of the child distribution selected for observation x.

In dispatch-mixture mode the selected child’s density is scaled by its branch weight.

Parameters:: x (T) – Observation compatible with the child selected by the choice function.
Returns:: Density of the selected child distribution at x.
Return type:: float

log_density(x)[source]

Log-density of the child distribution selected for observation x.

In dispatch-mixture mode the selected child’s log-density is offset by log(weight).

Parameters:: x (T) – Observation compatible with the child selected by the choice function.
Returns:: Log-density of the selected child distribution at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of the log-density on sequence encoded data x.

The encoding groups observations by choice index: x[1][i] is the choice index of group i, x[0][i] holds the original positions of the group’s observations, and x[2][i] is the group’s data encoded by the matching child encoder. Each group is scored by the child distribution its choice index selects.

Parameters:: x (tuple[tuple[ndarray, ...], tuple[int, ...], tuple[Any, ...]]) – Sequence encoded data produced by SelectDataEncoder.seq_encode().
Returns:: Numpy array of log-densities, one entry per encoded observation.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for choice-grouped encodings.

Parameters:

x (tuple[tuple[ndarray, ...], tuple[int, ...], tuple[Any, ...]])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child parameters for homogeneous select-wrapper mixtures.

Parameters:

dists (Sequence[SelectDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of choice-routed select log densities.

Parameters:

x (tuple[tuple[ndarray, ...], tuple[int, ...], tuple[Any, ...]])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy select sufficient statistics.

Parameters:

x (tuple[tuple[ndarray, ...], tuple[int, ...], tuple[Any, ...]])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[SelectStatistics, …]

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

to_fisher(**kwargs)[source]: Fisher view for the select combinator.

sampler(seed=None)[source]

Create a sampler that dispatches to the child distributions.

Parameters:: seed (Optional[int]) – Seed for the random number generator used in sampling.
Returns:: SelectSampler configured with this distribution’s routing function.
Return type:: SelectSampler

estimator(pseudo_count=None, estimate_weights=None)[source]

Creates a SelectEstimator with one child estimator per child distribution.

Parameters:

pseudo_count (Optional[float]) – Passed through to each child estimator.
estimate_weights (Optional[bool]) – Whether the fitted distribution carries branch weights (the dispatch-mixture model). When None (default) this follows the current mode – a weighted distribution re-fits weights, a conditional one stays conditional.

Returns:

SelectEstimator object.

Return type:

SelectEstimator

dist_to_encoder()[source]

Create an encoder for routed observations.

Returns:: SelectDataEncoder configured with the child encoders.
Return type:: SelectDataEncoder

enumerator()[source]

Creates a SelectEnumerator iterating the union of child supports in descending select-density order. All children must support enumeration.

Return type:: SelectEnumerator

class SelectEstimator(estimators, choice_function, estimate_weights=False)[source]

Bases: ParameterEstimator

SelectEstimator estimates a SelectDistribution from child sufficient statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
choice_function (Callable[[T], int])
estimate_weights (bool)

property count: int: Number of child estimators, derived from the immutable estimator tuple.

accumulator_factory()[source]

Creates a SelectEstimatorAccumulatorFactory from the child estimators.

Returns:: SelectEstimatorAccumulatorFactory object.
Return type:: SelectEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a SelectDistribution from aggregated sufficient statistics.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency.
suff_stat (Sequence[Tuple[float, Any]]) – One (weight, child sufficient statistic) pair per child, as returned by SelectEstimatorAccumulator.value().

Returns:

SelectDistribution object.

Return type:

SelectDistribution

class TypeDispatch(specs)[source]

Bases: object

Serializable choice function that routes an observation to a child by its Python type.

specs[i] declares the type(s) that child i emits; an observation routes to the FIRST child it is an instance of. Specs are friendly names (‘str’, ‘int’, ‘float’, ‘number’, ‘bytes’, ‘bool’, ‘complex’) or the matching Python type objects, with numpy scalar types handled automatically. Because its state is just those names, it round-trips through JSON with no manual registration – unlike a hand-written lambda choice function. Order matters: put more specific types first (e.g. ‘bool’ before ‘int’, since a bool is also an integer).

Parameters:: specs (Sequence[Any])

class SelectStatistics(schema_version, branches)[source]

Bases: NamedTuple

Versioned routed sufficient statistics, one branch entry per child.

Parameters:

schema_version (int)
branches (tuple[tuple[float, Any], ...])

schema_version: int: Alias for field number 0

branches: tuple[tuple[float, Any], ...]: Alias for field number 1

exception NonGenerativeSelectError[source]

Bases: TypeError

Raised when a conditional select likelihood is used as a generative law.

certify_select_routing(choice_function, contract_id)[source]

Attach an explicit, stable pushforward-routing assertion to a callable.

The caller asserts that every value generated by child k routes back to k. Finite child supports are still checked exhaustively; infinite supports are checked on every generated draw.

Parameters:

choice_function (Callable[[T], int])
contract_id (str)

Return type:

Callable[[T], int]

class SelectEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates the union of the child supports in descending select-density order.

Parameters:: dist (SelectDistribution)

class SequenceDistribution(dist, len_dist=NullDistribution(), len_normalized=False, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Independent sequence distribution built from a component observation distribution.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
len_dist (SequenceEncodableProbabilityDistribution | None)
len_normalized (bool | None)
name (str | None)
prior (tuple[Any, Any] | None)

compute_capabilities()[source]: Return compute-backend metadata inherited from the element and length distributions.

get_prior()[source]

Return the joint prior as (entry_prior, length_prior) from the wrapped children.

Return type:: tuple[Any, Any]

set_prior(prior)[source]

Distribute (entry_prior, length_prior) to the base and length distributions.

prior=None is a no-op (children keep their existing priors, leaving the MLE path byte-identical); otherwise the two-element prior is pushed to the base and length children via their own set_prior.

Parameters:: prior (tuple[Any, Any] | None)
Return type:: None

expected_log_density(x)[source]

Prior-expected log-density of the sequence x (sum over entries + length term).

Parameters:: x (Sequence[T])
Return type:: float

seq_expected_log_density(x)[source]

Vectorized prior-expected log-density over sequence-encoded input x.

Parameters:: x (tuple[ndarray, ndarray, ndarray, E1, E2 | None])
Return type:: ndarray

compute_declaration()[source]: Return the symbolic declaration for sequence elements and optional length statistics.

density(x)[source]

Return exp(log_density(x)) under the sequence score contract.

In normalized mode only the element log-score is divided by the observed length; the modeled length log-probability remains a full term. That mode is a training objective, not a normalized generative law.

Parameters:: x (Sequence[T])
Return type:: float

density_semantics()[source]: Classify conditional and length-normalized modes as likelihood factors.

log_density(x)[source]

Evaluate the log-density of SequenceDistribution at observed sequence x.

See density() for details.

Parameters:: x (Sequence[T]) – Sequence of iid observations from base distribution of SequenceDistribution.
Returns:: Log-density evaluated at observation x.
Return type:: float

seq_ld_lambda()[source]: Return vectorized log-density callables for encoded data.

seq_log_density(x)[source]

Vectorized evaluation of SequenceDistribution.log-density evaluated on sequence encoded x.

Parameters:: x (E) – Sequence encoded data observation.
Returns:: Numpy array of log-density evaluated at each encoded observation value x.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded sequences.

Parameters:

x (tuple[ndarray, ndarray, ndarray, E1, E2 | None])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child routes for homogeneous sequence mixtures.

Parameters:

dists (Sequence[SequenceDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of sequence log densities.

Parameters:

x (tuple[ndarray, ndarray, ndarray, E1, E2 | None])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return per-component legacy sequence sufficient statistics.

Parameters:

x (tuple[ndarray, ndarray, ndarray, E1, E2 | None])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, …]

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (list[Any])
recurse (Any)
tensor_param (Any)

Return type:

to_fisher(**kwargs)[source]: Structural Fisher view for the sequence.

to_exponential_family(engine=None)[source]

Return the iid exponential-family view, or None.

An iid sequence of an exponential family is itself an exponential family with the shared element eta and T(x) = sum_t T_0(x_t). This holds only when the length is not separately modeled and not length-normalized (a length term or normalization breaks the single-exp-family form); otherwise returns None, as does a non-exp-family element.

Parameters:: engine (Any)

sampler(seed=None)[source]

Create a sampler for this sequence distribution.

Note: If member len_dist (SequenceEncodableDistribution) is NullDistribution() and or not compatible with data type int, an error is thrown.

Parameters:: seed (Optional[int]) – Used to set seed of random number generator used to sample.
Returns:: SequenceSampler object.
Return type:: SequenceSampler

estimator(pseudo_count=None)[source]

Return an estimator for iid sequence observations and their lengths.

Parameters:: pseudo_count (float | None)
Return type:: SequenceEstimator

decomposition()[source]: Sequences are iid: this names the data (sequence) axis, sufficient stats SUM-reduce. The planner sizes this axis from N (the data), not a fixed model count; the base dist may itself decompose.

dist_to_encoder()[source]

Return an encoder for iid sequence observations.

Base distribution DataSequenceEncoder and length distribution DataSequenceEncoder objects are passed.

Returns:: SequenceDataEncoder object.
Return type:: SequenceDataEncoder

enumerator()[source]

Returns SequenceEnumerator iterating sequences in descending probability order.

Return type:: SequenceEnumerator

structural_fine_bucket(value, quantizer)[source]

Sum of per-element buckets plus the length term – mirrors the count index’s per-length L-fold element convolution shifted by the length-term bucket.

Return type:: int

quantized_count_index(quantizer, max_fine_bucket)[source]

Structural count index: per-length L-fold self-convolution of the element histogram.

log p(x) = sum_i log p(x_i) + log p(len(x)). For each length L the count histogram of the L-element sum is the L-fold self-convolution of the element count histogram, shifted by the length term’s bucket; the total is the pooled sum over lengths. Lengths come from the length distribution’s enumerator in descending probability, so once the length term alone exceeds the depth bound every later length does too and we stop. Sequences are unranked by resolving the contributing length, then the per-position element buckets via the convolution unranker.

Parameters:: max_fine_bucket (int)

class SequenceStatistics(schema_version, element_nobs, length_nobs, elements, lengths)[source]

Bases: NamedTuple

Versioned sequence child statistics with their effective observation counts.

Parameters:

schema_version (int)
element_nobs (float)
length_nobs (float)
elements (Any)
lengths (Any | None)

schema_version: int: Alias for field number 0

element_nobs: float: Alias for field number 1

length_nobs: float: Alias for field number 2

elements: Any: Alias for field number 3

lengths: Any | None: Alias for field number 4

exception NonGenerativeSequenceError[source]

Bases: TypeError

Raised when a conditional or normalized sequence score is asked to generate.

class SequenceEstimator(estimator, len_estimator=NullEstimator(), len_dist=NullDistribution(), len_normalized=False, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimator for iid sequence distributions from element and optional length sufficient statistics.

Parameters:

estimator (ParameterEstimator)
len_estimator (ParameterEstimator | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
len_normalized (bool | None)
name (str | None)
keys (str | None)
prior (tuple[Any, Any] | None)

get_prior()[source]

Return the joint prior as (entry_prior, length_prior) from the child estimators.

Return type:: tuple[Any, Any]

set_prior(prior)[source]

Distribute (entry_prior, length_prior) to the entry and length estimators.

prior=None is a no-op. The prior is pushed to the entry/length estimators (not to a fixed len_dist), so each child performs its own conjugate update.

Parameters:: prior (tuple[Any, Any] | None)
Return type:: None

model_log_density(model)[source]

Sum the entry and length estimators’ model_log_density on the corresponding children.

Parameters:: model (SequenceDistribution)
Return type:: float

accumulator_factory()[source]

Return SequenceAccumulatorFactory from len_estimator and estimator member variables with keys passed.

Return type:: SequenceAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the element distribution and, when configured, the length distribution.

Parameters:

nobs (float | None)
suff_stat (SequenceStatistics)

Return type:

SequenceDistribution

class SequenceEnumerator(dist)[source]

Bases: DistributionEnumerator

Best-first enumerator for finite-length iid sequences with a modeled length law.

Parameters:: dist (SequenceDistribution)

class ScheduledHiddenMarkovModelDistribution(inits, transitions, emissions, schedule, len_dist=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Phase-indexed (length-/position-conditional) HMM. See the module docstring for the modeling story.

Parameters:

inits (np.ndarray)
transitions (np.ndarray)
emissions (list[list[Any]])
schedule (PhaseSchedule)
len_dist (Any)
name (str | None)

log_density(x)[source]

Return the log likelihood of one scheduled HMM sequence.

Parameters:: x (list[Any])
Return type:: float

seq_log_density(x)[source]

Score a batch of scheduled HMM sequences.

Parameters:: x (Any)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for scheduled HMM sequences.

Parameters:: seed (int | None)
Return type:: ScheduledHMMSampler

estimator(pseudo_count=None)[source]

Create the matching estimator from this distribution’s own components.

Every phase/state cell retains its own estimator, so heterogeneous emission families survive fitting. The length estimator mirrors len_dist when one is modeled.

Parameters:: pseudo_count (float | None)
Return type:: ScheduledHMMEstimator

dist_to_encoder()[source]

Return the pass-through scheduled HMM encoder.

Return type:: ScheduledHMMDataEncoder

class ScheduledHMMEstimator(n_states, schedule, emission_estimator, len_estimator=None, pseudo_count=1e-8, name=None, *, emission_estimators=None)[source]

Bases: ParameterEstimator

EM estimator for a ScheduledHiddenMarkovModelDistribution with a fixed schedule.

emission_estimator is the backward-compatible homogeneous estimator prototype. emission_estimators may instead provide an exact phase-by-state grid, preserving heterogeneous families.

Parameters:

n_states (int)
schedule (PhaseSchedule)
emission_estimator (Any)
len_estimator (Any)
pseudo_count (float)
name (str | None)
emission_estimators (Sequence[Sequence[Any]] | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: ScheduledHMMAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate phase-indexed initial, transition, emission, and length models.

Parameters:

nobs (float | None)
suff_stat (tuple)

Return type:

ScheduledHiddenMarkovModelDistribution

class Homogeneous[source]

Bases: PhaseSchedule

One phase for everything – the ordinary time-homogeneous HMM.

phase(t, length)[source]

Return the single homogeneous phase.

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

Serialize the homogeneous schedule.

Return type:: dict[str, Any]

class ByPosition(cap)[source]

Bases: PhaseSchedule

Absolute position: phi(t, L) = min(t, cap - 1) (positions past cap-1 share the last phase).

Parameters:: cap (int)

phase(t, length)[source]

Return the absolute-position phase capped at the final phase.

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

Serialize the absolute-position schedule.

Return type:: dict[str, Any]

class ByRelativePosition(bins)[source]

Bases: PhaseSchedule

Relative position: phi(t, L) = min(bins - 1, floor(bins * t / L)) – progress through the sequence.

Parameters:: bins (int)

phase(t, length)[source]

Return the relative-position phase for t / length.

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

Serialize the relative-position schedule.

Return type:: dict[str, Any]

class ByLength(boundaries)[source]

Bases: PhaseSchedule

Length-conditional: phase is the bucket of L against sorted boundaries (constant within a seq).

With boundaries = [5, 10] there are three phases: L <= 5, 5 < L <= 10, L > 10.

Parameters:: boundaries (Sequence[int])

phase(t, length)[source]

Return the length-bucket phase for the sequence length.

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

Serialize the length-bucket schedule.

Return type:: dict[str, Any]

class SegmentalHiddenMarkovModelDistribution(emissions, w=MISSING, transitions=MISSING, len_dist=NullDistribution(), name=None, weights=MISSING, terminal_states=None)[source]

Bases: SequenceEncodableProbabilityDistribution

HMM whose states emit arbitrary segment-valued distributions.

Observations are lists of segment objects. For example, with SequenceDistribution(GaussianDistribution(...), len_dist=...) as an emission, each state emits a variable-length list of real values.

Parameters:

emissions (Sequence[SequenceEncodableProbabilityDistribution])
w (Sequence[float] | ndarray)
transitions (Sequence[Sequence[float]] | ndarray)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
weights (Sequence[float] | ndarray)
terminal_states (set[int] | Sequence[int] | None)

compute_capabilities()[source]: Describe backend support shared by emissions and optional length model.

compute_declaration()[source]: Return a composite compute declaration for the segmental HMM.

property topics: list[SequenceEncodableProbabilityDistribution]: Compatibility alias with HiddenMarkovModelDistribution terminology.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (Sequence[Any])
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (Sequence[Any])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray, tuple[Any, ...], Any | None])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral segmental-HMM forward scoring for encoded segment sequences.

Parameters:

x (tuple[ndarray, ndarray, tuple[Any, ...], Any | None])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: SegmentalHiddenMarkovSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: SegmentalHiddenMarkovEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: SegmentalHiddenMarkovDataEncoder

enumerator()[source]

Enumerate segment sequences in descending marginal probability order.

The segmental HMM has the standard HMM forward semantics – each position emits one segment from its state’s distribution, scored independently – so it reuses HiddenMarkovModelEnumerator directly via its per-state emission (topics), log_w, log_transitions, and len_dist. Each segment is drawn from the union of the per-state emission supports, so every emission distribution must itself support enumeration (and a length distribution must be modeled).

Return type:: DistributionEnumerator

SegmentalHiddenMarkovDistribution: alias of SegmentalHiddenMarkovModelDistribution

class SegmentalHiddenMarkovEstimator(estimators, len_estimator=NullEstimator(), pseudo_count=(None, None), name=None, keys=(None, None, None), terminal_states=None)[source]

Bases: ParameterEstimator

Baum-Welch estimator for SegmentalHiddenMarkovModelDistribution.

Parameters:

estimators (Sequence[ParameterEstimator])
len_estimator (ParameterEstimator | None)
pseudo_count (float | tuple[float | None, float | None] | None)
name (str | None)
keys (tuple[str | None, str | None, str | None] | None)
terminal_states (set[int] | Sequence[int] | None)

accumulator_factory()[source]

Return an accumulator factory for Baum-Welch sufficient statistics.

Return type:: SegmentalHiddenMarkovAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate initial, transition, emission, and length distributions.

Parameters:

nobs (float | None)
suff_stat (tuple[int, ndarray, ndarray, ndarray, Sequence[Any], Any | None])

Return type:

SegmentalHiddenMarkovModelDistribution

SegmentalHiddenMarkovModelEstimator: alias of SegmentalHiddenMarkovEstimator

class BernoulliSetDistribution(pmap=MISSING, min_prob=1.0e-128, name=None, keys=None, prob_map=MISSING, prior=None, posteriors=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Bernoulli set distribution: each support element is included in an observed set independently.

Parameters:

pmap (dict[Any, float])
min_prob (float)
name (str | None)
keys (str | None)
prob_map (dict[Any, float])
prior (SequenceEncodableProbabilityDistribution | None)
posteriors (dict[Any, tuple[float, float]] | None)

classmethod compute_capabilities()[source]: Declare backend support for Bernoulli-set generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Bernoulli set.

set_prior(prior, posteriors=None)[source]

Attach a (per-element) Beta prior and precompute conjugate-prior expectations.

With a shared Beta(a, b) prior on each element’s inclusion probability p_k this caches the digamma expectations so that expected_log_density evaluates the variational Bayes term E_q[log p(x | p)] via E[log p_k] = digamma(a_k) - digamma(a_k + b_k) and E[log(1 - p_k)] = digamma(b_k) - digamma(a_k + b_k). When posteriors (element -> (a_k, b_k)) is supplied, those per-element posterior Beta parameters are used; otherwise the shared prior parameters are broadcast over the support in pmap. Any other prior (including None) leaves the distribution a plain point model.

Parameters:

prior (SequenceEncodableProbabilityDistribution | None) – A shared BetaDistribution prior, or None.
posteriors (dict[Any, tuple[float, float]] | None) – Optional per-element posterior Beta parameters carried forward from a conjugate update.

Return type:

None

get_prior()[source]

Return the shared Beta prior (or None).

Return type:: SequenceEncodableProbabilityDistribution | None

get_posteriors()[source]

Return the per-element posterior Beta parameters (or None).

Return type:: dict[Any, tuple[float, float]] | None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | p)] under the per-element Beta prior.

Sums E[log p_k] over elements present in x plus E[log(1 - p_k)] over the remaining support. Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (Sequence[Any])
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (tuple[int, ndarray, ndarray, ndarray])
Return type:: ndarray

density(x)[source]

Density of the Bernoulli set distribution at observed set x.

See log_density() for details.

Parameters:: x (Sequence[Any]) – Observed set of distinct elements from the support of pmap.
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of the Bernoulli set distribution at observed set x.

Sums log(p_k / (1-p_k)) over the elements present in x, plus the constant sum_k log(1-p_k). Returns -inf if x is missing a required element (an element with p_k = 1 when min_prob is 0).

Parameters:: x (Sequence[Any]) – Observed set of distinct elements from the support of pmap.
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (Tuple[int, np.ndarray, np.ndarray, np.ndarray]) – Sequence encoded set observations from BernoulliSetDataEncoder.seq_encode().
Returns:: Numpy array of log-density values, one per encoded observation.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded object-valued sets.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Bernoulli-set parameters for shared label support.

Parameters:

dists (Sequence[BernoulliSetDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Bernoulli-set log densities.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return per-component legacy (count_map, total_weight) statistics.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[tuple[dict[Any, float], float], …]

sampler(seed=None)[source]

Create a sampler for this Bernoulli set distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: Sampler bound to this distribution.
Return type:: BernoulliSetSampler

estimator(pseudo_count=None)[source]

Create a BernoulliSetEstimator, passing pmap as suff_stat if pseudo_count is given.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight the distribution’s pmap in estimation.
Returns:: Estimator configured with this distribution’s prior settings.
Return type:: BernoulliSetEstimator

dist_to_encoder()[source]

Return a data encoder for Bernoulli set observations.

Return type:: BernoulliSetDataEncoder

enumerator()[source]

Returns BernoulliSetEnumerator iterating subsets of the support in descending probability order.

Return type:: BernoulliSetEnumerator

exception BernoulliSetFitError[source]

Bases: RuntimeError

Raised when Bernoulli-set statistics do not define a fitted law.

class BernoulliSetEstimator(min_prob=1.0e-128, pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None, support=None)[source]

Bases: ParameterEstimator

Estimate Bernoulli set distributions from aggregated sufficient statistics.

Parameters:

min_prob (float)
pseudo_count (float | None)
suff_stat (dict[Any, float] | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)
support (Sequence[Any] | None)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: BernoulliSetAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s per-element probabilities under the shared Beta prior.

This is the global ELBO term: with a shared Beta(a, b) prior the contribution is the sum over support elements of log Beta(p_k; a, b). Returns 0.0 when no conjugate prior is attached.

Parameters:: model (BernoulliSetDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a BernoulliSetDistribution from aggregated sufficient statistics.

Parameters:

nobs (Optional[float]) – Unused (kept for protocol consistency).
suff_stat (Tuple[Dict[Any, float], float]) – Inclusion counts by element and total weight.

Returns:

BernoulliSetDistribution object.

Return type:

BernoulliSetDistribution

class BernoulliSetEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates subsets of the pmap support in descending probability order.

Parameters:: dist (BernoulliSetDistribution)

class SparseMarkovAssociationDistribution(init_prob_vec, cond_prob_mat, alpha=0.0, len_dist=NullDistribution(), low_memory=False)[source]

Bases: SequenceEncodableProbabilityDistribution

Distribution for a sparse count set S2 generated from a count set S1.

Parameters:

init_prob_vec (Sequence[float] | ndarray)
cond_prob_mat (csr_matrix)
alpha (float)
len_dist (SequenceEncodableProbabilityDistribution | None)
low_memory (bool)

density(x)[source]

Density of the sparse Markov association model at observation x.

See log_density() for details.

Parameters:: x (tuple[list[tuple[int, float]], list[tuple[int, float]]]) – Observation tuple (S1, S2), each a list of (value, count) pairs.
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of the sparse Markov association model at observation x.

Computes log(P(S2 | S1)) (see module docstring, eq. (1)) plus the log-density of the total counts [n1, n2] under len_dist.

Parameters:: x (tuple[list[tuple[int, float]], list[tuple[int, float]]]) – Observation tuple (S1, S2), each a list of (value, count) pairs.
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x – Encoded sequence (from SparseMarkovAssociationDataEncoder.seq_encode).
Returns:: Numpy array of log-densities, one per encoded observation.
Return type:: ndarray

compute_capabilities()[source]

Engine readiness for the dense scoring tail (numpy + torch).

The large word-by-word transition matrix is sliced/gathered host-side with SciPy sparse ops, but the per-pair smoothing, log, and segment reductions run on the active engine (see backend_seq_log_density), so the model composes on numpy and torch.

backend_seq_log_density(x, engine)[source]

Validate and score the sparse encoding once, then lift the result to engine.

Return type:: Any

density_semantics()[source]: Classify the neutral-length form as a conditional fixed-length factor.

sampler(seed=None)[source]

Create a sampler for this sparse Markov association distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: Sampler bound to this distribution.
Return type:: SparseMarkovAssociationSampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this sparse Markov association distribution.

Parameters:: pseudo_count (Optional[float]) – Prior mass for the initial and conditional simplexes.
Returns:: Estimator configured with matching size and sparsity settings.
Return type:: SparseMarkovAssociationEstimator

dist_to_encoder()[source]

Return a data encoder for sparse Markov association observations.

Return type:: SparseMarkovAssociationDataEncoder

class SparseMarkovAssociationEstimator(num_vals=MISSING, alpha=0.0, len_estimator=NullEstimator(), suff_stat=None, pseudo_count=None, low_memory=True, keys=(None, None), num_values=MISSING)[source]

Bases: ParameterEstimator

Estimate sparse Markov association distributions from sufficient statistics.

Parameters:

num_vals (int)
alpha (float)
len_estimator (ParameterEstimator | None)
suff_stat (Any | None)
pseudo_count (float | None)
low_memory (bool)
keys (tuple[str | None, str | None])
num_values (int)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: SparseMarkovAssociationAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a sparse Markov association distribution from aggregated sufficient statistics.

Arg suff_stat is a Tuple of length 3 containing:: suff_stat[0] (np.ndarray): Weighted counts for the initial states P(S1). suff_stat[1] (Optional[Union[lil_matrix, csr_matrix]]): Counts for transitions used to estimate P(S2|S1). suff_stat[2] (SS1): Sufficient statistics from the accumulator of the size/len distribution.

Parameters:

nobs (Optional[float]) – Weighted number of observations.
suff_stat (tuple[ndarray, lil_matrix | csr_matrix | None, SS1]) – See above for details.

Returns:

SparseMarkovAssociationDistribution.

Return type:

SparseMarkovAssociationDistribution

class SpearmanRankingDistribution(sigma, rho=1.0, name=None, keys=None, max_dim=_DEFAULT_MAX_DIM, fit_diagnostics=None, *, _sigma_already_centered=False, _sigma_raw_scale_hint=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Exact finite Spearman law over item orderings under a dimension budget.

Known limitation: direct construction from a raw location vector (this class’s sigma argument – see the module docstring’s “possibly fractional mean rank vector”) whose entries share an extremely large common offset – beyond _TRUSTED_SIGMA_RAW_SCALE_CEILING in spearman_rho.py, roughly the range of a 32-bit integer (~2.1e9) – succeeds here, but the one-time float64 cancellation __init__ performs while centering it can leave a residual that a later restore (__pysp_setstate__) cannot always distinguish from genuine state corruption, and may then reject with a ValueError even though it was built validly. The original, pre-centering magnitude is not recoverable from the restored, already-centered state, so this is an accepted, documented limit rather than a bug to silently work around – see the comment above _validate_location in this module for the full reasoning and exact boundary.

Parameters:

sigma (Sequence[float] | np.ndarray)
rho (float)
name (str | None)
keys (str | None)
max_dim (int)
fit_diagnostics (SpearmanRankingFitDiagnostics | None)
_sigma_already_centered (bool)
_sigma_raw_scale_hint (float | None)

classmethod compute_capabilities()[source]: Declare generated NumPy and Torch scoring support.

classmethod compute_declaration()[source]: Return the generated-compute declaration.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return row-wise count and item-indexed rank-vector statistics.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, sigma, rho, log_const, engine)[source]

Score item orderings after explicit conversion to rank vectors.

Callers arrive under two shape conventions. backend_seq_log_density passes the natural ones – ranks (n, d) against a single sigma (d,). The generated scorer in mixle.stats.compute.declarations pre-aligns both sides instead: data picks up a component axis ((n, 1, d)) and every parameter a leading row axis ((1, k, d)), so the two already broadcast. Inserting a component axis unconditionally, as this did, double-counts it on that path and returns an (n, 1, k) score where the contract is (n, k). Only add the axis when the ranks really are still two-dimensional.

Parameters:

x (Any)
sigma (Any)
rho (Any)
log_const (Any)
engine (Any)

Return type:

property sigma: ndarray: Return an ownership-safe copy of the canonical mean rank vector.

density(x)[source]

Return the probability of an item ordering.

Parameters:: x (Sequence[int] | ItemOrdering)
Return type:: float

log_density(x)[source]

Return the log-probability of one x[rank] = item ordering.

Parameters:: x (Sequence[int] | ItemOrdering)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for item orderings.

Parameters:: x (ndarray)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized scoring for encoded item orderings.

Parameters:

x (ndarray)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Stack equal-dimensional Spearman parameters.

Parameters:

dists (Sequence[SpearmanRankingDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an observation-by-component score matrix.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked item-indexed rank-vector statistics.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Return an exact conditional-permanent sampler.

Parameters:: seed (int | None)
Return type:: SpearmanRankingSampler

estimator(pseudo_count=None)[source]

Return an estimator preserving the dimension and resource budget.

Parameters:: pseudo_count (float | None)
Return type:: SpearmanRankingEstimator

dist_to_encoder()[source]

Return the item-ordering encoder.

Return type:: SpearmanRankingDataEncoder

enumerator()[source]

Return a lazy descending-probability enumerator.

Return type:: SpearmanRankingEnumerator

support_size()[source]

Return the number of full item orderings.

Return type:: int

class SpearmanRankingEstimator(dim, rho=None, pseudo_count=None, suff_stat=None, name=None, keys=None, max_rho=1.0e6, max_dim=_DEFAULT_MAX_DIM)[source]

Bases: ParameterEstimator

Estimate consensus mean ranks and nonnegative Spearman concentration.

Parameters:

dim (int)
rho (float | None)
pseudo_count (float | None)
suff_stat (tuple[float, np.ndarray] | None)
name (str | None)
keys (str | None)
max_rho (float)
max_dim (int)

accumulator_factory()[source]

Return a factory for item-ordering sufficient statistics.

Return type:: SpearmanRankingAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from validated item-indexed rank sums.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray])

Return type:

SpearmanRankingDistribution

class SpearmanRankingEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate item orderings by increasing rank-to-item assignment cost.

Parameters:: dist (SpearmanRankingDistribution)

class SpearmanRankingFitDiagnostics(concentration_algorithm, converged, iterations, boundary_solution, regularized, pseudo_count)[source]

Bases: object

Concentration-fit and regularization evidence attached to an estimate.

Parameters:

concentration_algorithm (str)
converged (bool)
iterations (int)
boundary_solution (bool)
regularized (bool)
pseudo_count (float)

class ItemOrdering(values)[source]

Bases: Sequence[int]

A permutation whose entry at each rank is the item occupying that rank.

Parameters:: values (tuple[int, ...])

to_rank_vector()[source]

Return the inverse permutation, indexed by item.

Return type:: RankVector

class RankVector(values)[source]

Bases: Sequence[int]

A permutation whose entry for each item is that item’s rank.

Parameters:: values (tuple[int, ...])

to_item_ordering()[source]

Return the inverse permutation, indexed by rank.

Return type:: ItemOrdering

item_ordering_to_rank_vector(value)[source]

Convert x[rank] = item to owned rank[item] = rank data.

Parameters:: value (Sequence[int] | ndarray | ItemOrdering)
Return type:: ndarray

rank_vector_to_item_ordering(value)[source]

Convert rank[item] = rank to owned x[rank] = item data.

Parameters:: value (Sequence[int] | ndarray | RankVector)
Return type:: ndarray

class KnowledgeGraphDistribution(entity_embeddings, relation_embeddings, name=None, keys=None, fit_receipt=None)[source]

Bases: SequenceEncodableProbabilityDistribution

DistMult knowledge-graph embedding distribution over triples (h, r, t).

entity_embeddings is (num_entities, dim) and relation_embeddings is (num_relations, dim). log_density((h, r, t)) is the conditional tail log-probability log p(t | h, r) under the entity softmax.

Parameters:

entity_embeddings (Any)
relation_embeddings (Any)
name (str | None)
keys (str | None)
fit_receipt (dict[str, Any] | None)

score(h, r, t)[source]

DistMult score of a single triple (higher is more plausible).

Parameters:

h (int)
r (int)
t (int)

Return type:

tail_log_posterior(h, r)[source]

Length-num_entities vector of log p(t | h, r) over all tail candidates.

Parameters:

h (int)
r (int)

Return type:

head_log_posterior(r, t)[source]

Length-num_entities vector of log p(h | r, t) over all head candidates.

Parameters:

r (int)
t (int)

Return type:

relation_log_posterior(h, t)[source]

Length-num_relations vector of log p(r | h, t) over all relation candidates.

Parameters:

h (int)
t (int)

Return type:

complete(h=None, r=None, t=None)[source]

Log-posterior over candidates for the single missing slot of a query.

Exactly one of h, r, t must be None; the returned vector is over entities (for a missing head or tail) or relations (for a missing relation).

Parameters:

h (int | None)
r (int | None)
t (int | None)

Return type:

rank(h=None, r=None, t=None, exclude=(), top_n=None)[source]

Rank candidates for the missing slot by log-probability, dropping exclude candidates.

Returns [(candidate, log_prob), ...] highest first (the most plausible completions).

Parameters:

h (int | None)
r (int | None)
t (int | None)
exclude (Any)
top_n (int | None)

Return type:

list[tuple[int, float]]

recommend(known, top_n=10)[source]

Recommend the most plausible missing tail facts for the (h, r) contexts in known.

known is a sequence of observed (h, r, t) triples; for each distinct (h, r) the already-present tails are excluded, the remaining tails are ranked by log p(t | h, r), and the global top top_n new facts are returned as [(h, r, t, log_prob), ...].

Parameters:

known (Any)
top_n (int)

Return type:

list[tuple[int, int, int, float]]

recommend_subgraph(node, known, top_n=5)[source]

Recommend plausible new edges incident to node (both (node, r, ?) and (?, r, node)).

Excludes edges already in known and returns the top top_n by log-probability as [(h, r, t, log_prob), ...], the suggested missing subgraph around the node.

Parameters:

node (int)
known (Any)
top_n (int)

Return type:

list[tuple[int, int, int, float]]

pattern(pattern, candidates=None, known=None, beam=64)[source]

A subgraph-pattern query over this model for flexible enumeration of missing parts.

pattern is a list of triples whose slots are either fixed integer ids or named variables (strings starting with '?'), variables shared across edges (e.g. [(alice, friend, '?x'), ('?x', lives_in, '?c')]). The returned KnowledgeGraphPattern enumerates the variable bindings (completed subgraphs) in descending joint plausibility, restricts variables to candidates if given, drops groundings that add nothing new when known is given, and plugs into ConformalStructure for a calibrated set of completed subgraphs.

Parameters:

pattern (Any)
candidates (Any)
known (Any)
beam (int)

Return type:

KnowledgeGraphPattern

log_density(x)[source]

Return normalized joint log p(h,r,t) for one triple.

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized tail log-probabilities for encoded triples.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for observed triples.

Parameters:: seed (int | None)
Return type:: KnowledgeGraphSampler

estimator(pseudo_count=None)[source]

Return a DistMult embedding estimator for this entity/relation shape.

Parameters:: pseudo_count (float | None)
Return type:: KnowledgeGraphEstimator

dist_to_encoder()[source]

Return the triple encoder used by vectorized methods.

Return type:: KnowledgeGraphDataEncoder

class KnowledgeGraphEstimator(num_entities, num_relations, dim=16, lr=0.5, epochs=100, batch_size=256, weight_decay=0.0, init_scale=0.3, max_norm=1.0, directions=('tail',), negatives=None, seed=1, pseudo_count=None, name=None, keys=None, objective=None, initial_model=None)[source]

Bases: ParameterEstimator

Train DistMult knowledge-graph embeddings by maximizing the tail-softmax log-likelihood.

estimate runs vectorized mini-batch gradient ascent (epochs passes, batch size batch_size, step lr with L2 weight_decay) from a deterministic seeded init, projecting each entity embedding back to the unit ball every epoch so the scale – hence the step size – stays well behaved. One optimize / fit iteration (max_its=1) trains the model; the data is supplied through the accumulator like any other estimator.

Parameters:

num_entities (int)
num_relations (int)
dim (int)
lr (float)
epochs (int)
batch_size (int)
weight_decay (float)
init_scale (float)
max_norm (float)
directions (tuple)
negatives (int | None)
seed (int)
pseudo_count (float | None)
name (str | None)
keys (str | None)
objective (str | None)
initial_model (KnowledgeGraphDistribution | None)

accumulator_factory()[source]

Return a factory for stored-triple accumulators.

Return type:: KnowledgeGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

Fit DistMult embeddings from stored triples and weights.

Parameters:

nobs (float | None)
suff_stat (tuple)

Return type:

KnowledgeGraphDistribution

class KnowledgeGraphEnsemble(members)[source]

Bases: object

An ensemble of independently fit KnowledgeGraphDistribution models, for epistemic (model) uncertainty over completions.

The members share the entity and relation index spaces but are fit from different random seeds, so where the data pins the answer down they agree and where it does not they disagree. The mean tail posterior averages p(t | h, r) across members; the epistemic uncertainty is the mutual information (BALD) H(mean) - mean_m H(member_m) – the part of the predictive entropy that comes from disagreement among members rather than from genuine ambiguity.

Parameters:: members (list[KnowledgeGraphDistribution])

mean_tail_posterior(h, r)[source]

The ensemble-averaged p(t | h, r) over all tail candidates.

Parameters:

h (int)
r (int)

Return type:

epistemic_tail_uncertainty(h, r)[source]

Mutual-information (BALD) epistemic uncertainty of the tail completion (nats); 0 if members agree.

Thin wrapper over the general mixle.inference.uncertainty.decompose_entropy() – the tail posteriors p(t | h, r) per member are exactly the categorical predictives it splits.

Parameters:

h (int)
r (int)

Return type:

fit_knowledge_graph_ensemble(triples, num_entities, num_relations, dim=16, members=5, bootstrap=False, rng=None, **estimator_kwargs)[source]

Fit members knowledge-graph models and wrap them in an ensemble.

Members differ by their random seed; with bootstrap=True each is also fit on a bootstrap resample of the triples (bagging), which spreads the members further apart where the data is thin and so sharpens the epistemic-uncertainty estimate.

Parameters:

triples (Sequence[Sequence[int]])
num_entities (int)
num_relations (int)
dim (int)
members (int)
bootstrap (bool)
rng (Any)
estimator_kwargs (Any)

Return type:

KnowledgeGraphEnsemble

class PlackettLuceDistribution(log_w, name=None, keys=None, allow_partial=False)[source]

Bases: SequenceEncodableProbabilityDistribution

Plackett-Luce distribution over orderings of K items with log-worths log_w.

Data type: List[int] (an ordering: a permutation of 0,…,K-1, best-ranked item first).

Parameters:

log_w (Sequence[float] | ndarray)
name (str | None)
keys (str | None)
allow_partial (bool)

classmethod compute_capabilities()[source]: Declare the NumPy execution path used by Plackett-Luce ranking kernels.

density(x)[source]

Return the probability of an ordering x.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the log-probability of an ordering x.

x may be a full ranking (a permutation of 0,...,K-1) or a partial / top-m ranking (an ordered list of m <= K distinct items, best first, leaving the other K-m items unranked). For a partial ranking the sequential-choice denominator at each stage still includes the unranked items: p(x) = prod_{s=0}^{m-1} w_{x[s]} / (sum_{t>=s} w_{x[t]} + sum_{u unranked} w_u), which reduces to the full-ranking density when m = K.

Raises:: ValueError – If x is not 1-D, has a non-integer-valued entry (e.g. 0.5, which would otherwise silently truncate to a plausible-looking index instead of being rejected), or its (integer) entries are not distinct item indices in 0,...,K-1.
Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded orderings.

A dense (N, K) integer array (the full-ranking encoding) is scored by the vectorized path; a ragged sequence of variable-length orderings (the partial / top-m encoding) is scored per-ranking via log_density(), which includes the unranked-item denominator term.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing orderings from this distribution.

Parameters:: seed (int | None)
Return type:: PlackettLuceSampler

enumerator()[source]

Return an exact finite enumerator over all orderings in decreasing probability order.

Return type:: PlackettLuceEnumerator

support_size()[source]

Return the number of full rankings.

Return type:: int

estimator(pseudo_count=None)[source]

Return an MM estimator that keeps the item count fixed at this distribution’s K.

Parameters:: pseudo_count (float | None)
Return type:: PlackettLuceEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

The returned encoder handles both full rankings and partial/top-m rankings (see PlackettLuceDataEncoder), so this works regardless of whether self was produced by PlackettLuceEstimator or PlackettLucePartialEstimator.

Return type:: PlackettLuceDataEncoder

class PlackettLuceEstimator(dim, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Minorization-Maximization estimator for the Plackett-Luce log-worths (item count K fixed).

Parameters:

dim (int)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for MM sufficient statistics at this estimator’s dimension.

Return type:: PlackettLuceAccumulatorFactory

estimate(nobs, suff_stat)[source]

Return one MM estimate from accumulated full-ranking sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray, ndarray])

Return type:

PlackettLuceDistribution

class PlackettLuceEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate Plackett–Luce orderings in descending probability order, lazily (A* best-first).

A ranking’s log-density is sum_k [theta_{x_k} - logsumexp(theta over the items not yet ranked at step k)]. The state is a chosen prefix with exact partial score g; the best possible completion ranks the remaining items by descending worth (which minimizes the remaining logsumexp denominators), giving an exact admissible bound h. A* on g + h streams the rankings in exact descending order without touching the n! support.

Parameters:: dist (PlackettLuceDistribution)

class PlackettLucePartialEstimator(dim, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

MM estimator of Plackett-Luce log-worths from partial / top-m rankings (item count K fixed).

Parameters:

dim (int)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for partial-ranking MM sufficient statistics.

Return type:: PlackettLucePartialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Return one MM estimate from accumulated partial-ranking sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray, ndarray])

Return type:

PlackettLuceDistribution

class MallowsDistribution(sigma0, theta=1.0, name=None, keys=None, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Mallows distribution over permutations of 0,…,n-1 with central permutation sigma0 and dispersion theta.

Data type: List[int] (an ordering: a permutation of 0,…,n-1, best-ranked item first).

Parameters:

sigma0 (Sequence[int] | ndarray)
theta (float)
name (str | None)
keys (str | None)
fit_diagnostics (MallowsFitDiagnostics | None)

classmethod compute_capabilities()[source]: Return compute-backend metadata for the Mallows distribution.

kendall_distance(x)[source]

Return the Kendall tau distance between ordering x and the central permutation.

Raises:: ValueError – If x is not a permutation of 0,…,n-1 (wrong length, a repeated element, a non-integer entry, or an element outside that range). A malformed x is not merely an unlikely ordering – it isn’t an ordering at all, so it is rejected here rather than silently scored (e.g. a repeated index would otherwise still produce a finite, meaningless distance, an out-of-range index can alias a valid rank via numpy’s negative-index wraparound instead of failing loudly, and a fractional entry like 0.5 would otherwise be silently truncated to 0 by the int cast before this check ever saw it).
Parameters:: x (Sequence[int])
Return type:: int

density(x)[source]

Return the probability of an ordering x.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the log-probability of an ordering x (a permutation of 0,…,n-1).

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for an (N, n) array of orderings.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing orderings from this distribution.

Parameters:: seed (int | None)
Return type:: MallowsSampler

enumerator()[source]

Return an exact finite enumerator over all orderings in decreasing probability order.

Return type:: MallowsEnumerator

support_size()[source]

Return the number of full rankings.

Return type:: int

estimator(pseudo_count=None)[source]

Return an estimator that keeps the item count fixed at this distribution’s n.

Parameters:: pseudo_count (float | None)
Return type:: MallowsEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: MallowsDataEncoder

class MallowsEstimator(dim, theta=None, pseudo_count=None, prior_precede=None, prior_center=None, center_exact_cap=9, allow_approximate_center=False, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for the Mallows central permutation (Copeland aggregation) and dispersion theta.

Parameters:

dim (int)
theta (float | None)
pseudo_count (float | None)
prior_precede (ndarray | None)
prior_center (Sequence[int] | ndarray | None)
center_exact_cap (int)
allow_approximate_center (bool)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Mallows sufficient-statistic accumulators.

Return type:: MallowsAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the central permutation and dispersion from precedence counts.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray])

Return type:

MallowsDistribution

class MallowsEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate Mallows orderings in descending probability order, lazily.

Kendall distance is separable in the Lehmer code: an ordering’s distance is the sum of digits L_i in {0,...,n-1-i} (inversions contributed at each rank), each weighted -theta*L_i. So the support is a product over the digits and ProductEnumerator streams it in increasing distance (descending probability) without materializing the n! permutations; each digit tuple decodes (factorial number system) to a permutation of the identity, relabeled through the central permutation sigma0.

Parameters:: dist (MallowsDistribution)

class MallowsFitDiagnostics(center_algorithm, center_exact, centers_evaluated, kendall_objective, regularized, pseudo_count)[source]

Bases: object

Center-search and regularization evidence attached to a fitted Mallows law.

Parameters:

center_algorithm (str)
center_exact (bool)
centers_evaluated (int)
kendall_objective (float)
regularized (bool)
pseudo_count (float)

class GeneralizedMallowsDistribution(sigma0, theta=1.0, metric='kendall', name=None, keys=None, n_mc=20000, seed=0, max_exact=16, max_enum=9, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Mallows distribution under a configurable distance metric (closed-form normalizer metrics).

Parameters:

sigma0 (Sequence[int] | np.ndarray)
theta (float)
metric (str)
name (str | None)
keys (str | None)
n_mc (int)
seed (int)
max_exact (int)
max_enum (int)
fit_diagnostics (GeneralizedMallowsFitDiagnostics | None)

classmethod compute_capabilities()[source]: Declare the NumPy and numba execution path used by Mallows kernels.

distance(x)[source]

Distance between ordering x and the central permutation under this metric.

Raises:: ValueError – If x is not a permutation of 0,…,n-1 (wrong length, a repeated element, a non-integer entry, or an element outside that range). A malformed x is not merely an unlikely ordering – it isn’t an ordering at all, so it is rejected here rather than silently scored (e.g. a repeated index would otherwise still produce a finite, meaningless distance, an out-of-range index can alias a valid rank via numpy’s negative-index wraparound instead of failing loudly, and a fractional entry like 0.5 would otherwise be silently truncated to 0 by the int cast before this check ever saw it).
Parameters:: x (Sequence[int])
Return type:: int

density(x)[source]

Return the probability of one ordering under the Mallows model.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the log-probability of one ordering.

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded orderings.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for this Mallows distribution.

Parameters:: seed (int | None)
Return type:: GeneralizedMallowsSampler

estimator(pseudo_count=None)[source]

Return a Mallows estimator with this metric and item count.

Parameters:: pseudo_count (float | None)
Return type:: GeneralizedMallowsEstimator

dist_to_encoder()[source]

Return the full-ranking encoder used by vectorized methods.

Return type:: GeneralizedMallowsDataEncoder

class GeneralizedMallowsEstimator(dim, metric='kendall', theta=None, reservoir=10000, name=None, keys=None, n_mc=20000, seed=0, max_exact=16, max_enum=9, pseudo_count=None, prior_center=None, center_exact_cap=7, allow_approximate_center=False)[source]

Bases: ParameterEstimator

Estimate the central permutation (Copeland/Borda) and dispersion theta (moment match).

Parameters:

dim (int)
metric (str)
theta (float | None)
reservoir (int)
name (str | None)
keys (str | None)
n_mc (int)
seed (int)
max_exact (int)
max_enum (int)
pseudo_count (float | None)
prior_center (Sequence[int] | np.ndarray | None)
center_exact_cap (int)
allow_approximate_center (bool)

accumulator_factory()[source]

Return a factory for Mallows sufficient-statistic accumulators.

Return type:: GeneralizedMallowsAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the central ordering and dispersion from accumulated rankings.

Parameters:: nobs (float | None)
Return type:: GeneralizedMallowsDistribution

class GeneralizedMallowsFitDiagnostics(center_algorithm, center_exact, centers_evaluated, distance_objective, regularized, pseudo_count)[source]

Bases: object

Center-search and regularization evidence attached to a fitted model.

Parameters:

center_algorithm (str)
center_exact (bool)
centers_evaluated (int)
distance_objective (float)
regularized (bool)
pseudo_count (float)

class GeneralizedMallowsComputationDiagnostics(normalizer_algorithm, normalizer_exact, sampler_algorithm, sampler_exact, legacy_n_mc_ignored, legacy_seed_ignored)[source]

Bases: object

Exactness and algorithm provenance for scoring and sampling.

Parameters:

normalizer_algorithm (str)
normalizer_exact (bool)
sampler_algorithm (str)
sampler_exact (bool)
legacy_n_mc_ignored (int)
legacy_seed_ignored (int)

class GeneralizedMallowsModelDistribution(sigma0, theta=None, name=None, keys=None, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Generalized Mallows Model: a Kendall Mallows model with a per-stage dispersion vector theta.

Parameters:

sigma0 (Sequence[int] | np.ndarray)
theta (Sequence[float] | np.ndarray | None)
name (str | None)
keys (str | None)
fit_diagnostics (GeneralizedMallowsModelFitDiagnostics | None)

classmethod compute_capabilities()[source]: Declare the NumPy execution path used by stage-wise Mallows kernels.

density(x)[source]

Return the probability of one ordering.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the log-probability of one ordering.

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded orderings.

Raises:: ValueError – If any row of x is not a permutation of 0,…,n-1 (wrong length, a repeated element, a non-integer entry, or an element outside that range). A malformed row is not merely an unlikely ordering – it isn’t an ordering at all, so it is rejected here rather than silently scored (e.g. a repeated index would otherwise still produce a finite, meaningless log-density, an out-of-range or negative index reaches the numba RIM kernel below, which has no bounds checking of its own and does not raise – it silently scores too, rather than failing loudly – and a fractional entry like 0.5 would otherwise be silently truncated to 0 by the int cast before this check ever saw it).
Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return an exact repeated-insertion sampler for this model.

Parameters:: seed (int | None)
Return type:: GeneralizedMallowsModelSampler

estimator(pseudo_count=None)[source]

Return a stage-wise Mallows estimator with this item count.

Parameters:: pseudo_count (float | None)
Return type:: GeneralizedMallowsModelEstimator

dist_to_encoder()[source]

Return the full-ranking encoder used by vectorized methods.

Return type:: GeneralizedMallowsModelDataEncoder

class GeneralizedMallowsModelEstimator(dim, reservoir=10000, pseudo_count=None, prior_center=None, center_exact_cap=7, allow_approximate_center=False, name=None, keys=None)[source]

Bases: ParameterEstimator

Fit a center and per-stage dispersions from exact weighted empirical support.

Parameters:

dim (int)
reservoir (int)
pseudo_count (float | None)
prior_center (Sequence[int] | np.ndarray | None)
center_exact_cap (int)
allow_approximate_center (bool)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for stage-wise Mallows sufficient-statistic accumulators.

Return type:: GeneralizedMallowsModelAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate central ordering and per-stage dispersions from accumulated rankings.

Parameters:: nobs (float | None)
Return type:: GeneralizedMallowsModelDistribution

class GeneralizedMallowsModelFitDiagnostics(center_algorithm, center_exact, centers_evaluated, objective, regularized, pseudo_count)[source]

Bases: object

Center-search and regularization evidence attached to a fitted stage-wise model.

Parameters:

center_algorithm (str)
center_exact (bool)
centers_evaluated (int)
objective (float)
regularized (bool)
pseudo_count (float)

class BradleyTerryDistribution(log_w, name=None, keys=None, fit_diagnostics=None, *, _log_w_already_centered=False)[source]

Bases: SequenceEncodableProbabilityDistribution

Bradley-Terry paired-comparison model with centered log-worths log_w.

Parameters:

log_w (Sequence[float] | np.ndarray)
name (str | None)
keys (str | None)
fit_diagnostics (BradleyTerryFitDiagnostics | None)
_log_w_already_centered (bool)

classmethod compute_capabilities()[source]: Declare the NumPy and numba execution path used by Bradley-Terry kernels.

density(x)[source]

Return the probability of one (winner, loser) comparison.

Parameters:: x (tuple[int, int])
Return type:: float

log_density(x)[source]

Return the JOINT log-probability of one (winner, loser) comparison.

The pair is drawn uniformly from all K(K-1)/2 unordered pairs and the winner follows Bradley-Terry, so exp(log_density(...)) sums to one over all ordered pairs and exp(log_density((i, j))) + exp(log_density((j, i))) is 1/C(K, 2) – NOT one. It is not P(i beats j); that conditional is win_probability().

Parameters:: x (tuple[int, int])
Return type:: float

win_probability(i, j)[source]

Return P(i beats j | i and j are compared): sigmoid(log_w[i] - log_w[j]).

The conditional a reader of log_density expects. log_density is the joint over (which pair, uniformly) x (who won), smaller by the factor C(K, 2); this quantity satisfies win_probability(i, j) + win_probability(j, i) == 1.

Parameters:

i (int)
j (int)

Return type:

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded pairwise comparisons.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for paired-comparison outcomes.

Parameters:: seed (int | None)
Return type:: BradleyTerrySampler

estimator(pseudo_count=None)[source]

Return an MM estimator with this distribution’s item count.

Parameters:: pseudo_count (float | None)
Return type:: BradleyTerryEstimator

dist_to_encoder()[source]

Return the pairwise-comparison encoder used by vectorized methods.

Return type:: BradleyTerryDataEncoder

class BradleyTerryEstimator(dim, pseudo_count=None, max_iter=500, tol=1e-10, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood log-worths via the Zermelo / MM fixed point (Hunter 2004).

pseudo_count adds that many fractional wins to EVERY ordered pair (symmetric smoothing). It is what lets an undefeated or winless competitor, or a disconnected comparison graph, fit at all: the unregularized maximum likelihood does not exist there (Ford 1957), and the estimator refuses rather than return a boundary worth. Choosing it: the top of the ranking is stable over a wide range, but near-tied competitors can swap order and the leader’s worth margin shrinks roughly with pseudo_count relative to the wins per pair, because the prior wins pull every worth toward equality (a 0.05 -> 2.0 sweep on one realistic dataset moved the leader’s margin by ~10x while leaving the top order alone). Start near 0.5, half a prior win per ordered pair, shrink it as the comparisons per pair grow, read fit_diagnostics.regularized and pseudo_count on the result, and compare two values before quoting a margin.

Parameters:

dim (int)
pseudo_count (float | None)
max_iter (int)
tol (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Bradley-Terry sufficient-statistic accumulators.

Return type:: BradleyTerryAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate centered log-worths from accumulated win counts.

Parameters:: nobs (float | None)
Return type:: BradleyTerryDistribution

class BradleyTerryFitDiagnostics(converged, iterations, l1_change, regularized, pseudo_count)[source]

Bases: object

Convergence and regularization evidence attached to an estimated model.

Parameters:

converged (bool)
iterations (int)
l1_change (float)
regularized (bool)
pseudo_count (float)

class LowRankPermutationDistribution(u, v, name=None, keys=None, max_exact=12, sinkhorn_iter=200, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Permutation Gibbs model with a low-rank item-by-rank score matrix S = U V^T.

Parameters:

u (np.ndarray)
v (np.ndarray)
name (str | None)
keys (str | None)
max_exact (int)
sinkhorn_iter (int)
fit_diagnostics (LowRankPermutationFitDiagnostics | None)

classmethod compute_capabilities()[source]: Declare the NumPy and numba execution path used by low-rank permutation kernels.

density(x)[source]

Return the probability of one ordering.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the log-probability of one ordering.

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded orderings.

Parameters:: x (ndarray)
Return type:: ndarray

marginals()[source]

Return exact model marginals P[item, rank].

Return type:: ndarray

sinkhorn_relaxation()[source]

Return an explicitly approximate doubly-stochastic transport relaxation.

Return type:: ndarray

sampler(seed=None)[source]

Return an exact conditional-permanent sampler.

Parameters:: seed (int | None)
Return type:: LowRankPermutationSampler

estimator(pseudo_count=None)[source]

Return an exact-marginal estimator with this dimension and rank.

Parameters:: pseudo_count (float | None)
Return type:: LowRankPermutationEstimator

dist_to_encoder()[source]

Return the full-ranking encoder used by vectorized methods.

Return type:: LowRankPermutationDataEncoder

class LowRankPermutationEstimator(dim, rank=2, max_exact=12, sinkhorn_iter=200, max_iter=300, lr=0.5, tol=1.0e-6, pseudo_count=None, prior_marginals=None, require_convergence=True, name=None, keys=None)[source]

Bases: ParameterEstimator

Fit U, V by Sinkhorn-marginal gradient ascent toward the empirical item-by-rank marginals.

Parameters:

dim (int)
rank (int)
max_exact (int)
sinkhorn_iter (int)
max_iter (int)
lr (float)
tol (float)
pseudo_count (float | None)
prior_marginals (np.ndarray | None)
require_convergence (bool)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for low-rank permutation sufficient-statistic accumulators.

Return type:: LowRankPermutationAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate low-rank score factors from item-by-rank marginal counts.

Parameters:: nobs (float | None)
Return type:: LowRankPermutationDistribution

class LowRankPermutationFitDiagnostics(converged, iterations, gradient_norm, regularized, pseudo_count, marginal_algorithm='exact_log_permanent')[source]

Bases: object

Optimization evidence attached to an estimated low-rank permutation law.

Parameters:

converged (bool)
iterations (int)
gradient_norm (float)
regularized (bool)
pseudo_count (float)
marginal_algorithm (str)

class LowRankPermutationComputationDiagnostics(normalizer_algorithm='exact_log_permanent', normalizer_exact=True, marginal_algorithm='exact_log_permanent_ratios', marginals_exact=True, sampler_algorithm='exact_conditional_permanent', sampler_exact=True, optional_relaxation='sinkhorn_bethe_transport')[source]

Bases: object

Exactness and algorithm provenance for the represented probability law.

Parameters:

normalizer_algorithm (str)
normalizer_exact (bool)
marginal_algorithm (str)
marginals_exact (bool)
sampler_algorithm (str)
sampler_exact (bool)
optional_relaxation (str)

class ThurstoneDistribution(mu, name=None, keys=None, n_mc=4000, seed=0, smoothing=0.5, fit_diagnostics=None, *, _mu_already_centered=False)[source]

Bases: SequenceEncodableProbabilityDistribution

Normalized finite-sample approximation to a Case V Thurstone law.

Parameters:

mu (Sequence[float] | np.ndarray)
name (str | None)
keys (str | None)
n_mc (int)
seed (int)
smoothing (float)
fit_diagnostics (ThurstoneFitDiagnostics | None)
_mu_already_centered (bool)

classmethod compute_capabilities()[source]: Declare the NumPy execution path used to build the approximation.

density(x)[source]

Return the normalized approximating probability of a full ordering.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the normalized approximating log-probability of one ordering.

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return batch-invariant log-probabilities for encoded full orderings.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for this exact approximating categorical law.

Parameters:: seed (int | None)
Return type:: ThurstoneSampler

support_size()[source]

Return the number of full rankings in the smoothed support.

Return type:: int

estimator(pseudo_count=None)[source]

Return a labelled Thurstone-Mosteller pairwise-moment estimator.

Parameters:: pseudo_count (float | None)
Return type:: ThurstoneEstimator

dist_to_encoder()[source]

Return the dense full-ranking encoder used by vectorized methods.

Return type:: ThurstoneDataEncoder

class ThurstoneEstimator(dim, n_mc=4000, seed=0, smoothing=0.5, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Labelled pairwise-moment estimator for Case V Thurstone utilities.

Parameters:

dim (int)
n_mc (int)
seed (int)
smoothing (float)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Thurstone sufficient-statistic accumulators.

Return type:: ThurstoneAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate centered utilities from validated pairwise-precedence statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray])

Return type:

ThurstoneDistribution

class ThurstoneApproximationDiagnostics(method, draws, seed, smoothing, distinct_rankings, support_size, maximum_binomial_standard_error)[source]

Bases: object

Provenance and uncertainty scale for the approximating categorical law.

Parameters:

method (str)
draws (int)
seed (int)
smoothing (float)
distinct_rankings (int)
support_size (int)
maximum_binomial_standard_error (float)

class ThurstoneFitDiagnostics(method, exact_mle, regularized, pseudo_count)[source]

Bases: object

Provenance for an estimated Thurstone utility vector.

Parameters:

method (str)
exact_mle (bool)
regularized (bool)
pseudo_count (float)

class ThurstoneMostellerDistribution(mu, name=None, keys=None, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gaussian/probit paired-comparison model P(i beats j) = Phi((mu_i - mu_j) / sqrt(2)).

Parameters:

mu (Sequence[float] | np.ndarray)
name (str | None)
keys (str | None)
fit_diagnostics (ThurstoneMostellerFitDiagnostics | None)

classmethod compute_capabilities()[source]: Return backend capabilities for the probit pairwise likelihood.

density(x)[source]

Return the probability mass of one winner-loser pair.

Parameters:: x (tuple[int, int])
Return type:: float

log_density(x)[source]

Return the JOINT log probability of one winner-loser pair.

The pair is drawn uniformly from all K(K-1)/2 unordered pairs and the winner follows the probit rule, so exp(log_density((i, j))) + exp(log_density((j, i))) is 1/C(K, 2), not one. P(i beats j | compared) is win_probability().

Parameters:: x (tuple[int, int])
Return type:: float

win_probability(i, j)[source]

Return P(i beats j | i and j are compared) = Phi((mu[i] - mu[j]) / sqrt(2)).

Parameters:

i (int)
j (int)

Return type:

seq_log_density(x)[source]

Score encoded winner-loser pairs.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for winner-loser comparisons.

Parameters:: seed (int | None)
Return type:: ThurstoneMostellerSampler

estimator(pseudo_count=None)[source]

Return the least-squares probit paired-comparison estimator.

Parameters:: pseudo_count (float | None)
Return type:: ThurstoneMostellerEstimator

dist_to_encoder()[source]

Return the encoder for winner-loser pair data.

Return type:: PairDataEncoder

class ThurstoneMostellerEstimator(dim, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

mu_i - mu_j = sqrt(2) Phi^{-1}(P(i beats j)) from the win-count matrix (least squares).

pseudo_count adds that many fractional wins to every ordered pair before the moment step; see BradleyTerryEstimator for how to choose it and what it does to margins. Here it also keeps a never-lost pair away from the Phi^{-1} clip (clipped_pair_probabilities counts the pairs that hit it).

Parameters:

dim (int)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: PairWinAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Thurstone-Mosteller utilities from win-count statistics.

Parameters:: nobs (float | None)
Return type:: ThurstoneMostellerDistribution

class ThurstoneMostellerFitDiagnostics(method, exact_mle, graph_connected, clipped_pair_probabilities, regularized, pseudo_count, strongly_connected)[source]

Bases: object

Provenance and identifiability evidence for the pairwise-moment fit.

Parameters:

method (str)
exact_mle (bool)
graph_connected (bool)
clipped_pair_probabilities (int)
regularized (bool)
pseudo_count (float)
strongly_connected (bool)

class TieModelFitDiagnostics(model, converged, status, message, iterations, objective, gradient_norm, worth_boundary_hit, tie_parameter_boundary_hit, graph_connected, regularized, pseudo_count, strongly_connected)[source]

Bases: object

Optimizer, identifiability, and boundary evidence for a tie-model fit.

Parameters:

model (str)
converged (bool)
status (int)
message (str)
iterations (int)
objective (float)
gradient_norm (float)
worth_boundary_hit (bool)
tie_parameter_boundary_hit (bool)
graph_connected (bool)
regularized (bool)
pseudo_count (float)
strongly_connected (bool)

class DavidsonDistribution(log_w, nu=1.0, name=None, keys=None, fit_diagnostics=None)[source]

Bases: _BaseTieDistribution

Bradley-Terry with ties (Davidson 1970); tie mass nu sqrt(w_i w_j).

Parameters:

nu (float)
name (str | None)
keys (str | None)
fit_diagnostics (TieModelFitDiagnostics | None)

estimator(pseudo_count=None)[source]

Return the maximum-likelihood Davidson estimator.

Parameters:: pseudo_count (float | None)

class DavidsonEstimator(dim, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood Davidson worths and tie parameter (L-BFGS on the count matrices).

pseudo_count adds that many fractional wins to every ordered pair and that many ties to every unordered pair; see BradleyTerryEstimator for how to choose it. Without it, data in which some competitor never lost (or never won) has no finite fit and the estimator raises ValueError rather than return a boundary worth.

Parameters:

dim (int)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: _TieAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Davidson worths and tie parameter from sufficient statistics.

Parameters:: nobs (float | None)
Return type:: DavidsonDistribution

class RaoKupperDistribution(log_w, nu=1.5, name=None, keys=None, fit_diagnostics=None)[source]

Bases: _BaseTieDistribution

Bradley-Terry with ties via a threshold nu >= 1 (Rao-Kupper 1967).

Parameters:

nu (float)
name (str | None)
keys (str | None)
fit_diagnostics (TieModelFitDiagnostics | None)

estimator(pseudo_count=None)[source]

Return the maximum-likelihood Rao-Kupper estimator.

Parameters:: pseudo_count (float | None)

class RaoKupperEstimator(dim, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood Rao-Kupper worths and threshold (L-BFGS on the count matrices).

Parameters:

dim (int)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: _TieAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Rao-Kupper worths and threshold from sufficient statistics.

Parameters:: nobs (float | None)
Return type:: RaoKupperDistribution

class EwensDistribution(dim, theta=1.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Ewens distribution over permutations of 0..n-1 with cycle-weight parameter theta > 0.

Parameters:

dim (int)
theta (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare the NumPy and numba execution path used by Ewens kernels.

density(x)[source]

Return the probability of one permutation.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the log-probability of one permutation.

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded permutations.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return an exact Ewens permutation sampler.

Parameters:: seed (int | None)
Return type:: EwensSampler

estimator(pseudo_count=None)[source]

Return a cycle-count moment estimator for this dimension.

Parameters:: pseudo_count (float | None)
Return type:: EwensEstimator

dist_to_encoder()[source]

Return the permutation encoder used by vectorized methods.

Return type:: EwensDataEncoder

class EwensEstimator(dim, theta=None, pseudo_count=None, prior_mean_cycles=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Fit theta by matching the mean cycle count E[cycles] = sum_i theta/(theta+i).

Parameters:

dim (int)
theta (float | None)
pseudo_count (float | None)
prior_mean_cycles (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Ewens sufficient-statistic accumulators.

Return type:: EwensAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate theta by matching the accumulated mean cycle count.

Parameters:: nobs (float | None)
Return type:: EwensDistribution

class SpanningTreeDistribution(weights, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Weighted spanning-tree distribution over n labeled nodes with symmetric positive edge weights.

Data type: a sequence of n-1 undirected edges (i, j) forming a spanning tree of 0,…,n-1.

Parameters:

weights (Sequence[Sequence[float]] | ndarray)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for weighted spanning-tree operations.

density(x)[source]

Return the probability of a spanning tree x (a sequence of edges).

Parameters:: x (Sequence[Sequence[int]])
Return type:: float

log_density(x)[source]

Return the log-probability of a spanning tree x (a sequence of n-1 edges).

Parameters:: x (Sequence[Sequence[int]])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for a validated sequence of edge arrays.

Parameters:: x (Sequence[ndarray])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing spanning trees from this distribution.

Parameters:: seed (int | None)
Return type:: SpanningTreeSampler

enumerator(max_edge_subsets=_DEFAULT_MAX_ENUMERATION_SUBSETS)[source]

Return a probability-ordered enumerator capped at max_edge_subsets returned trees.

Parameters:: max_edge_subsets (int | None)
Return type:: SpanningTreeEnumerator

estimator(pseudo_count=None)[source]

Return an estimator that keeps the node count fixed at this distribution’s n.

Parameters:: pseudo_count (float | None)
Return type:: SpanningTreeEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: SpanningTreeDataEncoder

exception SpanningTreeFitError[source]

Bases: RuntimeError

Raised when spanning-tree statistics do not identify a valid fit.

class SpanningTreeEstimator(dim, pseudo_count=None, max_steps=500, learning_rate=1.0, tol=1.0e-7, candidate_support=None, prior_weights=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate edge weights by matching empirical or smoothed tree edge marginals.

Parameters:

dim (int)
pseudo_count (float | None)
max_steps (int)
learning_rate (float)
tol (float)
candidate_support (ndarray | None)
prior_weights (ndarray | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for spanning-tree edge counts.

Return type:: SpanningTreeAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate edge weights by matching target edge marginals.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray])

Return type:

SpanningTreeDistribution

class SpanningTreeEnumerator(dist, max_edge_subsets=_DEFAULT_MAX_ENUMERATION_SUBSETS)[source]

Bases: DistributionEnumerator

Enumerate supported spanning trees in descending probability order, lazily.

A tree’s probability is the product of its edge weights, so descending probability is increasing total edge cost under cost = -log(weights) (zero-weight edges become +inf, i.e. absent). Gabow’s k-best spanning-tree algorithm streams the trees in that order from one constrained-MST oracle per node, without scanning the exponential set of edge subsets.

Parameters:

dist (SpanningTreeDistribution)
max_edge_subsets (int | None)

property receipt: dict[str, object]: Return enumeration progress and termination metadata.

class MatchingDistribution(weights, max_nodes=_DEFAULT_MAX_NODES, name=None, keys=None, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Weighted bipartite perfect-matching distribution over n left/right nodes (permanent-normalized).

Data type: a permutation x of 0,…,n-1 (left node i matched to right node x[i]).

Parameters:

weights (Sequence[Sequence[float]] | ndarray)
max_nodes (int)
name (str | None)
keys (str | None)
fit_diagnostics (MatchingFitDiagnostics | None)

classmethod compute_capabilities()[source]: Return compute-backend metadata for the matching distribution.

density(x)[source]

Return the probability of a matching x (a permutation).

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

Return the log-probability of a matching x (left i matched to right x[i]).

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for an (N, n) array of matchings.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing matchings from this distribution.

Parameters:: seed (int | None)
Return type:: MatchingSampler

enumerator()[source]

Return an exact finite enumerator over all matchings in decreasing probability order.

Return type:: MatchingEnumerator

support_size()[source]

Return the number of perfect matchings.

Return type:: int

estimator(pseudo_count=1.0)[source]

Return an estimator that keeps the node count fixed at this distribution’s n.

Parameters:: pseudo_count (float | None)
Return type:: MatchingEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: MatchingDataEncoder

class MatchingEstimator(dim, max_nodes=_DEFAULT_MAX_NODES, pseudo_count=1.0, max_steps=5000, learning_rate=1.0, tol=1.0e-7, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the edge weights (matches empirical and model edge marginals).

Parameters:

dim (int)
max_nodes (int)
pseudo_count (float | None)
max_steps (int)
learning_rate (float)
tol (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for matching sufficient-statistic accumulators.

Return type:: MatchingAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a permanent-normalized matching distribution from assignment counts.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray])

Return type:

MatchingDistribution

class MatchingEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate finite-probability perfect matchings in descending probability order.

Lazily, via Murty’s k-best assignment on the edge-cost matrix -log(weights): decreasing probability is increasing assignment cost, and zero-weight edges become +inf costs (forbidden), so only positive-probability matchings are yielded. This streams the top matchings without materializing the n! permutation support.

Parameters:: dist (MatchingDistribution)

class MatchingFitDiagnostics(converged, iterations, max_marginal_error, regularized, pseudo_count)[source]

Bases: object

Convergence evidence attached to an estimated matching model.

Parameters:

converged (bool)
iterations (int)
max_marginal_error (float)
regularized (bool)
pseudo_count (float)

class RandomDotProductGraphDistribution(positions, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Random Dot Product Graph over n nodes with d-dimensional latent positions X (edge prob X X^T).

Parameters:

positions (Sequence[Sequence[float]] | np.ndarray)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Return compute-backend metadata for RDPG log-density evaluation.

edge_marginals()[source]

Return the n-by-n matrix of edge probabilities P(A_ij = 1).

Return type:: ndarray

density(x)[source]

Return the probability of a graph x.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-probability of a binary undirected graph x.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-probabilities for a sequence of graph observations.

Parameters:: x (Sequence[GraphObservation])
Return type:: np.ndarray

backend_seq_log_density(x, engine)[source]

Engine-routed RDPG edge log-likelihood (reduction runs on the active engine).

Parameters:

x (Sequence[GraphObservation])
engine (Any)

Return type:

Any

sampler(seed=None)[source]

Return a sampler for drawing graphs from this distribution.

Parameters:: seed (int | None)
Return type:: RandomDotProductGraphSampler

estimator(pseudo_count=None)[source]

Return an ASE estimator that keeps the latent dimension fixed at this distribution’s d.

Parameters:: pseudo_count (float | None)
Return type:: RandomDotProductGraphEstimator

dist_to_encoder()[source]

Return the shared graph data encoder.

Return type:: GraphDataEncoder

class RandomDotProductGraphEstimator(dim, num_nodes=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Adjacency Spectral Embedding estimator for the RDPG latent positions.

Parameters:

dim (int)
num_nodes (int | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for RDPG sufficient-statistic accumulators.

Return type:: RandomDotProductGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate latent positions from the mean adjacency matrix using ASE.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray | None])

Return type:

RandomDotProductGraphDistribution

class SemiSupervisedMixtureDistribution(components, w=MISSING, name=None, weights=MISSING)[source]

Bases: SequenceEncodableProbabilityDistribution

SemiSupervisedMixtureDistribution models observations (value, prior) where the optional prior labels re-weight the mixture weights over the listed components.

Parameters:

components (Sequence[SequenceEncodableProbabilityDistribution])
w (list[float] | ndarray)
name (str | None)
weights (list[float] | ndarray)

compute_capabilities()[source]: Declare generated-compute support inherited from mixture components.

compute_declaration()[source]: Return the generated-compute declaration for the semi-supervised mixture.

density(x)[source]

Density of the semi-supervised mixture at observation x.

See log_density() for details.

Parameters:: x (Tuple[T0, Optional[Sequence[Tuple[int, T1]]]]) – Observation (value, prior).
Returns:: Density at x.
Return type:: float

log_density(x)[source]

Log-density of the semi-supervised mixture at observation x = (value, prior).

If prior is None this is the standard mixture log-density. Otherwise the mixture weights are restricted to the components listed in the prior, re-weighted by the prior probabilities, and re-normalized before mixing the component log-densities.

Parameters:: x (Tuple[T0, Optional[Sequence[Tuple[int, T1]]]]) – Observation (value, prior), where prior is an optional sequence of (component index, probability) pairs.
Returns:: Log-density at x.
Return type:: float

posterior(x)[source]

Posterior probability of each component for observation x = (value, prior).

Components not listed in the prior (when a prior is present) receive posterior 0.

Parameters:: x (Tuple[T0, Optional[Sequence[Tuple[int, T1]]]]) – Observation (value, prior).
Returns:: Numpy array of length num_components containing the component posteriors.
Return type:: ndarray

seq_log_density(x)[source]

Vectorized evaluation of the log-density on sequence encoded data x.

Parameters:: x (E) – Sequence encoded data produced by SemiSupervisedMixtureDataEncoder.seq_encode().
Returns:: Numpy array of log-densities, one entry per encoded observation.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral semi-supervised mixture log-density for encoded observations.

Parameters:

x (tuple[int, E0, tuple[tuple[ndarray, ndarray, ndarray, ndarray], ndarray, ndarray], Sequence[tuple[T0, Sequence[tuple[int, T1]] | None]]])
engine (Any)

Return type:

seq_posterior(x)[source]

Vectorized component posteriors on sequence encoded data x.

Parameters:: x (E) – Sequence encoded data produced by SemiSupervisedMixtureDataEncoder.seq_encode().
Returns:: Numpy array of shape (number of observations, num_components) of posteriors.
Return type:: ndarray

density_semantics()[source]: Return exact-or-approximate density semantics joined from component models.

sampler(seed=None)[source]

Creates a SemiSupervisedMixtureSampler for sampling component values.

Parameters:: seed (Optional[int]) – Seed for the random number generator used in sampling.
Returns:: SemiSupervisedMixtureSampler object.
Return type:: SemiSupervisedMixtureSampler

estimator(pseudo_count=None)[source]

Creates a SemiSupervisedMixtureEstimator with one child estimator per component.

Parameters:: pseudo_count (Optional[float]) – Used to inflate the sufficient statistics of the mixture weights.
Returns:: SemiSupervisedMixtureEstimator object.
Return type:: SemiSupervisedMixtureEstimator

dist_to_encoder()[source]

Creates a SemiSupervisedMixtureDataEncoder for encoding sequences of (value, prior) observations.

Returns:: SemiSupervisedMixtureDataEncoder object.
Return type:: SemiSupervisedMixtureDataEncoder

enumerator()[source]

Enumeration is not well-defined for semi-supervised mixtures.

Observations pair a component value with exogenous prior labels: the model defines no distribution over the prior part, so the support over (value, prior) pairs cannot be enumerated with consistent probabilities.

Raises:: EnumerationError always. –
Return type:: DistributionEnumerator

class SemiSupervisedMixtureEstimator(estimators, suff_stat=None, pseudo_count=None, keys=(None, None), name=None)[source]

Bases: ParameterEstimator

SemiSupervisedMixtureEstimator estimates a SemiSupervisedMixtureDistribution from aggregated sufficient statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
suff_stat (ndarray | None)
pseudo_count (float | None)
keys (tuple[str | None, str | None] | None)
name (str | None)

accumulator_factory()[source]

Create an accumulator factory from the child estimators.

Returns:: Factory configured for this estimator.
Return type:: SemiSupervisedMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a SemiSupervisedMixtureDistribution from aggregated sufficient statistics.

The mixture weights are the normalized component counts, optionally regularized by pseudo_count and the stored suff_stat weights.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency.
suff_stat (Tuple[np.ndarray, Tuple[SS0, ...]]) – Component counts and component sufficient statistics, as returned by SemiSupervisedMixtureEstimatorAccumulator.value().

Returns:

Estimated distribution.

Return type:

SemiSupervisedMixtureDistribution

class TreeHiddenMarkovModelDistribution(topics, w=MISSING, transitions=MISSING, len_dist=NullDistribution(), terminal_level=10, name=None, use_numba=None, weights=MISSING)[source]

Bases: SequenceEncodableProbabilityDistribution

Hidden Markov model on a rooted tree with emission distributions of type T.

Data type: Sequence[Tuple[Tuple[int, int], T]] (((node_id, parent_id), emission) per node, root parent -1).

Parameters:

topics (Sequence[SequenceEncodableProbabilityDistribution])
w (Sequence[float] | ndarray)
transitions (list[list[float]] | ndarray)
len_dist (SequenceEncodableProbabilityDistribution | None)
terminal_level (int)
name (str | None)
use_numba (bool | None)
weights (Sequence[float] | ndarray)

compute_capabilities()[source]: Declare generated-compute support from emission and length children.

compute_declaration()[source]: Return the generated-compute declaration for the tree HMM.

density(x)[source]

Density of tree HMM at a single observed tree x.

See log_density() for details.

Parameters:: x (Sequence[Tuple[D, T]]) – Tree as ((node_id, parent_id), emission) tuples (root parent -1).
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of tree HMM at a single observed tree x.

The hidden states are marginalized out with an upward (beta) message passing recursion over the tree. When a non-null length distribution (len_dist) is set, its contribution to the likelihood (the sum over nodes of len_dist.log_density(num_children)) is included; a NullDistribution length contributes nothing.

Parameters:: x (Sequence[Tuple[D, T]]) – Tree as ((node_id, parent_id), emission) tuples (root parent -1).
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Dispatches to numba kernels or to the pure-numpy level-by-level recursion depending on which encoding (use_numba) the input was created with.

Parameters:: x (E) – Sequence encoded trees from TreeHiddenMarkovDataEncoder.seq_encode().
Returns:: Numpy array of log-density (float), one entry per encoded tree.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral tree-HMM scoring for the pure non-numba encoded layout.

Parameters:

x (tuple[tuple[ndarray, tuple[int, ndarray, ndarray, ndarray], tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray], E3, tuple[ndarray, E4] | None] | None, tuple[int, ndarray, tuple[ndarray, ndarray, ndarray], tuple[ndarray, ndarray, ndarray, ndarray, list[ndarray], list[ndarray], list[ndarray], list[ndarray], ndarray], E3, tuple[ndarray, E4] | None] | None])
engine (Any)

Return type:

seq_posterior(x)[source]

Posterior state membership probabilities for each node of each encoded tree.

Parameters:: x (E) – Sequence encoded trees from TreeHiddenMarkovDataEncoder.seq_encode().
Returns:: List with one numpy array per tree, each of shape (num_nodes, num_states), containing the posterior probability of each hidden state at each node.
Return type:: list[ndarray] | None

viterbi(x)[source]

Most likely hidden state assignment for each node of a single observed tree.

Parameters:: x (Sequence[Tuple[D, T]]) – Tree as ((node_id, parent_id), emission) tuples (root parent -1).
Returns:: Numpy array of int states, one per node of the tree.
Return type:: ndarray

seq_viterbi(x)[source]

Vectorized Viterbi state assignments for sequence encoded trees.

Parameters:: x (E) – Sequence encoded trees from TreeHiddenMarkovDataEncoder.seq_encode().
Returns:: List with one numpy array of int states per tree (one state per node).
Return type:: list[ndarray]

density_semantics()[source]: Return exact-or-approximate density semantics joined from child models.

sampler(seed=None)[source]

Create a sampler for this tree hidden Markov distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: Sampler bound to this distribution.
Return type:: TreeHiddenMarkovSampler
Raises:: ValueError – If len_dist is a NullDistribution (a length distribution with support on the non-negative integers is required for sampling).

enumerator()[source]

Not supported: observations are rooted trees, not chains.

The chain best-first enumerator (HiddenMarkovModelEnumerator) does not apply – the marginal sums over hidden states on a branching tree whose shape is itself governed by the per-node child-count len_dist, so the support is a set of trees rather than sequences. Use sampler() or the exact log_density instead.

Return type:: DistributionEnumerator

estimator(pseudo_count=None)[source]

Create a TreeHiddenMarkovEstimator with estimators for the topics and length distribution.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics of the initial state weights, transition matrix, topics, and length distribution.
Returns:: TreeHiddenMarkovEstimator object.
Return type:: TreeHiddenMarkovEstimator

dist_to_encoder()[source]

Return a data encoder for iid tree HMM observations.

Return type:: TreeHiddenMarkovDataEncoder

class TreeHiddenMarkovEstimator(estimators, len_estimator=NullEstimator(), pseudo_count=(None, None), name=None, keys=(None, None, None), use_numba=None)[source]

Bases: ParameterEstimator

Estimator for the TreeHiddenMarkovModelDistribution from aggregated sufficient statistics.

Parameters:

estimators (list[ParameterEstimator])
len_estimator (ParameterEstimator | None)
pseudo_count (float | tuple[float | None, float | None] | None)
name (str | None)
keys (tuple[str | None, str | None, str | None] | None)
use_numba (bool | None)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: TreeHiddenMarkovAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a TreeHiddenMarkovModelDistribution from sufficient statistics (M-step).

Initial state weights and transition rows are normalized counts, optionally smoothed with the pseudo_count pair. A transition row with no observed outgoing transitions – e.g. every training tree is shallow enough that this state is never seen with a child – is filled uniform rather than left at zero when no pseudo-count is given, so that p_level (the per-level marginal state-occupancy vector derived from w and this matrix, used throughout scoring) stays strictly positive at every level instead of going hard-zero and later poisoning log_density() on a deeper out-of-sample tree with a silent NaN (T4-01). Every such row is disclosed through numerical_repairs() on the returned distribution. Topics and the length distribution are estimated from their respective sufficient statistics.

Parameters:

nobs (Optional[float]) – Number of observations.
suff_stat (Tuple) – Tuple of number of states, initial-state counts, state counts, transition counts, emission sufficient statistics per state, and length sufficient statistics.

Returns:

Estimated distribution.

Return type:

TreeHiddenMarkovModelDistribution

TreeHiddenMarkovModelEstimator: alias of TreeHiddenMarkovEstimator

class TransformDistribution(dist, transform=None, density_correction=None, name=None, keys=None, fit_receipt=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Push a child distribution through a fixed invertible transform.

Observations live in transformed space. For fixed continuous transforms, log-density uses the inverse transform and adds the inverse-Jacobian term. The transform is not learned; estimation inverse-transforms observations and delegates sufficient statistics to the child estimator.

Parameters:

dist (SequenceEncodableProbabilityDistribution)
transform (Any | None)
density_correction (bool | None)
name (str | None)
keys (str | None)
fit_receipt (TransformFitReceipt | None)

compute_capabilities()[source]: Return capabilities delegated from the child distribution where safe.

compute_declaration()[source]: Return a declaration describing this distribution as a transformed child.

density(x)[source]

Return the probability density or mass at a single observation.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (tuple[Any, ndarray, ndarray])
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for inverse-encoded observations.

Parameters:

x (tuple[Any, ndarray, ndarray])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child parameters for homogeneous fixed-transform mixtures.

Parameters:

dists (Sequence[TransformDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of transformed child log densities.

Parameters:

x (tuple[Any, ndarray, ndarray])
params (dict[str, Any])
engine (Any)

Return type:

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:

engine (Any)
torch (Any)
leaves (Any)
recurse (Any)
tensor_param (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: TransformSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: TransformEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: TransformDataEncoder

enumerator()[source]

Return an enumerator over the distribution support when available.

Return type:: TransformEnumerator

exception TransformCompatibilityError[source]

Bases: TypeError

Raised when a transform contract is incompatible with its child distribution.

class TransformContract(input_domain, output_domain, measure='adaptive', bijective=True)[source]

Bases: object

Machine-checkable declaration for a deterministic bijective transform.

input_domain and output_domain use the same coarse vocabulary as compute-declaration support tags. measure is "adaptive" when the transform supports both counting measure and continuous change-of-variables, or "discrete" for a counting-measure-only mapping.

Parameters:

input_domain (str)
output_domain (str)
measure (str)
bijective (bool)

exception TransformDomainError[source]

Bases: ValueError

Raised when an observation lies outside a transform’s declared domain.

class TransformFitReceipt(accepted_weight, rejected_weight, rejected_fraction)[source]

Bases: NamedTuple

Accepted/rejected evidence accounting attached to a fitted transform wrapper.

Parameters:

accepted_weight (float)
rejected_weight (float)
rejected_fraction (float)

accepted_weight: float: Alias for field number 0

rejected_weight: float: Alias for field number 1

rejected_fraction: float: Alias for field number 2

class TransformStatistics(schema_version, child, accepted_weight, rejected_weight)[source]

Bases: NamedTuple

Versioned child statistics plus transform-domain evidence accounting.

Parameters:

schema_version (int)
child (Any)
accepted_weight (float)
rejected_weight (float)

schema_version: int: Alias for field number 0

child: Any: Alias for field number 1

accepted_weight: float: Alias for field number 2

rejected_weight: float: Alias for field number 3

class TransformEstimator(estimator, transform=None, density_correction=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for fixed-transform distributions.

Parameters:

estimator (ParameterEstimator)
transform (Any | None)
density_correction (bool | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory for inverse-transformed observations.

Return type:: TransformAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate from accepted evidence and attach the rejected-weight receipt.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

TransformDistribution

class TransformEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate transformed child support for discrete child distributions.

Parameters:: dist (TransformDistribution)

class FiniteStochasticTransformDistribution(dist, kernel, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Finite discrete source pushed through a fixed finite stochastic kernel (noisy channel).

Parameters:

dist (SequenceEncodableProbabilityDistribution)
kernel (Any)
name (str | None)
keys (str | None)

density(x)[source]

Return P(Y = x).

Parameters:: x (int)
Return type:: float

log_density(x)[source]

Return log P(Y = x) for an integer output x in {0, ..., n-1}.

Parameters:: x (int)
Return type:: float

seq_log_density(x)[source]

Return per-observation log P(Y = y) for an encoded batch of outputs.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

support_size()[source]

Number of finite outputs {0, ..., n-1}.

Return type:: int

sampler(seed=None)[source]

Return a sampler drawing X ~ dist then Y ~ Categorical(kernel[X]).

Parameters:: seed (int | None)
Return type:: FiniteStochasticTransformSampler

estimator(pseudo_count=None)[source]

Return an estimator that recovers the source via the channel-inversion-free E-step.

Parameters:: pseudo_count (float | None)
Return type:: FiniteStochasticTransformEstimator

dist_to_encoder()[source]

Return the data encoder for integer outputs.

Return type:: FiniteStochasticTransformDataEncoder

enumerator()[source]

Enumerate the finite outputs y in descending P(Y = y) order.

Return type:: FiniteStochasticTransformEnumerator

class FiniteStochasticTransformEstimator(source_estimator, kernel, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for a fixed-kernel finite stochastic transform (recovers the source).

Parameters:

source_estimator (ParameterEstimator)
kernel (Any)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for finite-transform sufficient-statistic accumulators.

Return type:: FiniteStochasticTransformAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the source distribution and re-wrap it with the fixed kernel.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

FiniteStochasticTransformDistribution

class FiniteStochasticTransformEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate the finite output support in descending marginal probability.

Parameters:: dist (FiniteStochasticTransformDistribution)

class ZeroInflatedDistribution(base, pi, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A base count distribution with an extra point mass of probability pi at zero.

Parameters:

base (SequenceEncodableProbabilityDistribution)
pi (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the zero-inflated probability at x.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return log[(1-pi) p_base(x)] for x > 0, mixed with pi at x == 0.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Vectorized zero-inflated log-density for an encoded batch.

Parameters:: x (tuple[Any, ndarray])
Return type:: ndarray

sampler(seed=None)[source]

Return a ZeroInflatedSampler for this distribution.

Parameters:: seed (int | None)
Return type:: ZeroInflatedSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits pi and the base by EM over the latent zero source.

Parameters:: pseudo_count (float | None)
Return type:: ZeroInflatedEstimator

dist_to_encoder()[source]

Return the data encoder (base encoding + a boolean is-zero mask).

Return type:: ZeroInflatedDataEncoder

class ZeroInflatedEstimator(base_estimator, pseudo_count=None, name=None, keys=None, initial_inflation_probability=0.5)[source]

Bases: ParameterEstimator

EM estimator: pi = (expected structural zeros) / N, base re-fit on the down-weighted data.

Parameters:

base_estimator (ParameterEstimator)
pseudo_count (float | None)
name (str | None)
keys (str | None)
initial_inflation_probability (float)

accumulator_factory()[source]

Return a factory for zero-inflated sufficient-statistic accumulators.

Return type:: ZeroInflatedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the base distribution and structural-zero probability.

Parameters:

nobs (float | None)
suff_stat (tuple[Any, float, float])

Return type:

ZeroInflatedDistribution

class BackoffDistribution(base, fallback, escape_weight=DEFAULT_ESCAPE_WEIGHT, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A sharp base mixed with a broad fallback under a pinned escape weight.

Parameters:

base (SequenceEncodableProbabilityDistribution)
fallback (SequenceEncodableProbabilityDistribution)
escape_weight (float)
name (str | None)
keys (str | None)

compute_declaration()[source]

Declare the backoff’s support as the support its two children agree on.

A backoff mixes a sharp base with a broad fallback over the SAME sample space, so when both children declare the same support the mixture has it too. Declaring nothing made the composite unusable wherever a caller has to prove what a distribution ranges over: SequenceDistribution refuses a length model that cannot “prove support on non-negative integers”, and mixle.utils.automatic builds exactly this shape – a backoff length model over sequence records – so the automatic path produced a model the library then rejected.

Children that disagree (or do not declare) leave the support unstated, which is the honest answer rather than a guess.

density_semantics()[source]

Join both children’s semantics – a backoff is only exact when everything it mixes is.

The base-class default returns EXACT, which is a claim about the whole mixture. A backoff over a child explicitly marked LIKELIHOOD_FACTOR (a categorical used as an unnormalized factor, say) inherits that child’s missing normalizer: the escape-weighted sum of an exact law and an unnormalized factor is itself unnormalized. Reporting EXACT there tells a caller a density integrates to one when it does not.

density(x)[source]

Return the mixture density at x.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the mixture log-density at x.

Finite whenever either component can score x, which is the reason this class exists: the base may return -inf for an unobserved outcome and the total stays finite.

Parameters:: x (Any)
Return type:: float

component_log_densities(x)[source]

Return the two weighted component log-density vectors for encoded data x.

Parameters:: x (tuple[Any, Any])
Return type:: tuple[ndarray, ndarray]

seq_log_density(x)[source]

Vectorized mixture log-density over sequence-encoded observations.

Parameters:: x (tuple[Any, Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler that draws the component first, then the value.

Parameters:: seed (int | None)
Return type:: BackoffSampler

estimator(pseudo_count=None)[source]

Return an estimator for this backoff structure, reusing the children’s own estimators.

Parameters:: pseudo_count (float | None)
Return type:: BackoffEstimator

dist_to_encoder()[source]

Return an encoder that encodes each observation for both components.

Return type:: BackoffDataEncoder

class BackoffEstimator(base_estimator, fallback_estimator, escape_weight=DEFAULT_ESCAPE_WEIGHT, max_escape_weight=DEFAULT_MAX_ESCAPE_WEIGHT, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for BackoffDistribution with a bounded escape weight.

Parameters:

base_estimator (ParameterEstimator)
fallback_estimator (ParameterEstimator)
escape_weight (float)
max_escape_weight (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the matching accumulator factory.

Return type:: BackoffAccumulatorFactory

estimate(nobs, suff_stat)[source]

Fit both components and the (bounded) escape weight.

Parameters:

nobs (float | None)
suff_stat (tuple[Any, Any, float, float])

Return type:

BackoffDistribution

class HurdleDistribution(base, pi, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A zero hurdle (probability pi) followed by a zero-truncated base for the positive counts.

Parameters:

base (SequenceEncodableProbabilityDistribution)
pi (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the hurdle probability at x.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return log pi at x == 0, else log[(1-pi) p_base(x) / (1 - p_base(0))].

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Vectorized hurdle log-density for an encoded batch.

Parameters:: x (tuple[Any, ndarray])
Return type:: ndarray

sampler(seed=None)[source]

Return a HurdleSampler for this distribution.

Parameters:: seed (int | None)
Return type:: HurdleSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits pi (the zero rate) and the base on the positives – closed form.

Parameters:: pseudo_count (float | None)
Return type:: HurdleEstimator

dist_to_encoder()[source]

Return the data encoder (base encoding + a boolean is-zero mask).

Return type:: HurdleDataEncoder

class HurdleEstimator(base_estimator, pseudo_count=None, name=None, keys=None, trunc_max_iter=100, trunc_threshold=1.0e-10)[source]

Bases: ParameterEstimator

Closed-form pi (the zero rate) plus the zero-truncated MLE of the base over the positives.

The two parts are independent. pi is the observed zero rate. The count part is the base fit by maximum likelihood under the zero truncation – NOT the base fit naively to the positives, which is biased (it recovers the truncated mean, so the fitted model would not match the data). The truncated MLE is obtained by a short EM that treats the removed zeros as missing data: given the current base, the positives imply N_missing = N_pos * P0/(1-P0) hypothetical base zeros; refit the base to the positives plus those pseudo-zeros and iterate. (If the base has no mass at 0 there is no truncation and the positives are fit directly.)

Parameters:

base_estimator (ParameterEstimator)
pseudo_count (float | None)
name (str | None)
keys (str | None)
trunc_max_iter (int)
trunc_threshold (float)

accumulator_factory()[source]

Return a factory for hurdle sufficient-statistic accumulators.

Return type:: HurdleAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the hurdle probability and zero-truncated base distribution.

Parameters:

nobs (float | None)
suff_stat (tuple[Any, float, float])

Return type:

HurdleDistribution

class SurvivalDistribution(base, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Right-censored survival likelihood over a base event-time distribution.

Parameters:

base (SequenceEncodableProbabilityDistribution)
name (str | None)
keys (str | None)

density(x)[source]

Return the likelihood contribution of (t, event).

Parameters:: x (tuple[float, int])
Return type:: float

log_density(x)[source]

Return log f(t) for an observed event, else log S(t) for a right-censored time.

Parameters:: x (tuple[float, int])
Return type:: float

seq_log_density(x)[source]

Vectorized likelihood: base density for events, log survival for censored rows.

Parameters:: x (tuple[Any, ndarray, ndarray])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler (draws uncensored event times; censoring is exogenous).

Parameters:: seed (int | None)
Return type:: SurvivalSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits the base under right-censoring by conditional-quantile EM.

Parameters:: pseudo_count (float | None)
Return type:: SurvivalEstimator

dist_to_encoder()[source]

Return the data encoder (base encoding of the times + the event mask).

Return type:: SurvivalDataEncoder

class SurvivalEstimator(base_estimator, n_impute=16, name=None, keys=None)[source]

Bases: ParameterEstimator

Fit the base event-time distribution under right-censoring (conditional-quantile imputation EM).

Parameters:

base_estimator (ParameterEstimator)
n_impute (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for right-censored survival sufficient-statistic accumulators.

Return type:: SurvivalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the base event-time distribution from imputed survival statistics.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

SurvivalDistribution

class TruncatedDistribution(base, allowed=None, forbidden=None, name=None, keys=None, fit_receipt=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A base distribution restricted to an allowed support and renormalized.

Parameters:

base (SequenceEncodableProbabilityDistribution)
allowed (Sequence[Any] | None)
forbidden (Sequence[Any] | None)
name (str | None)
keys (str | None)
fit_receipt (TruncatedProjectionFitReceipt | None)

density(x)[source]

Return the renormalized probability/density at x.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return log p_base(x) - log Z for allowed x, else -inf.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return per-row truncated log-densities for an encoded batch.

Parameters:: x (tuple[Any, ndarray])
Return type:: ndarray

sampler(seed=None)[source]

Return a rejection sampler over the allowed support.

Parameters:: seed (int | None)
Return type:: TruncatedSampler

estimator(pseudo_count=None)[source]

Return the explicit projection estimator, not a truncated-likelihood MLE.

The projection fits the child to retained observations and then reapplies the support restriction. It deliberately omits the parameter-dependent -n log Z(theta) term, so the returned model carries a receipt with likelihood_aware=False.

Parameters:: pseudo_count (float | None)
Return type:: TruncatedProjectionEstimator

dist_to_encoder()[source]

Return the data encoder (base encoding + an allowed-membership mask).

Return type:: TruncatedDataEncoder

support_size()[source]

Cardinality of the retained support (None if infinite).

Return type:: int | None

enumerator()[source]

Enumerate the allowed support in descending (renormalized) probability order.

Return type:: TruncatedEnumerator

TruncatedEstimator: alias of TruncatedProjectionEstimator

class TruncatedProjectionEstimator(base_estimator, allowed=None, forbidden=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Approximate projection that fits the base only to retained observations.

This is intentionally not called a truncated MLE: it omits the parameter-dependent normalizer from the objective and marks every fitted model with likelihood_aware=False.

Parameters:

base_estimator (ParameterEstimator)
allowed (Sequence[Any] | None)
forbidden (Sequence[Any] | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for truncated-data sufficient-statistic accumulators.

Return type:: TruncatedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Project retained evidence onto the base and report excluded evidence.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

TruncatedDistribution

class TruncatedProjectionFitReceipt(accepted_weight, rejected_weight, rejected_fraction, likelihood_aware)[source]

Bases: NamedTuple

Evidence accounting for the explicit untruncated-base projection fit.

Parameters:

accepted_weight (float)
rejected_weight (float)
rejected_fraction (float)
likelihood_aware (bool)

accepted_weight: float: Alias for field number 0

rejected_weight: float: Alias for field number 1

rejected_fraction: float: Alias for field number 2

likelihood_aware: bool: Alias for field number 3

class TruncatedStatistics(schema_version, child, accepted_weight, rejected_weight)[source]

Bases: NamedTuple

Versioned sufficient statistics for support-filtered projection fitting.

Parameters:

schema_version (int)
child (Any)
accepted_weight (float)
rejected_weight (float)

schema_version: int: Alias for field number 0

child: Any: Alias for field number 1

accepted_weight: float: Alias for field number 2

rejected_weight: float: Alias for field number 3

class TruncatedEnumerator(dist)[source]

Bases: DistributionEnumerator

Filter the base enumeration to the allowed support, renormalized by -log Z.

Parameters:: dist (TruncatedDistribution)

class CensoredDistribution(base, name=None, keys=None, *, fit_receipt=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A base distribution whose observations may be interval/left/right censored.

Parameters:

base (SequenceEncodableProbabilityDistribution)
name (str | None)
keys (str | None)
fit_receipt (CensoredExactOnlyFitReceipt | None)

density(x)[source]

Return the contribution of x (density for exact, interval mass for censored).

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Log-likelihood contribution of x.

Exact observation x -> log p_base(x); interval (a, b) -> log P(a <= X <= b) (see _interval_log_mass()).

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Per-row censored log-densities for an encoded batch.

Parameters:: x (tuple[Any, ndarray, ndarray, ndarray, ndarray])
Return type:: ndarray

sampler(seed=None)[source]

Return exact evidence from the base; censoring requires a separate observation process.

Parameters:: seed (int | None)
Return type:: CensoredSampler

estimator(pseudo_count=None)[source]

Return the explicit exact-only projection estimator with an effective-count receipt.

This is not a censored MLE. Use likelihood_estimator() with a base-family-specific fitting callback when interval evidence must influence the fitted parameters.

Parameters:: pseudo_count (float | None)
Return type:: ExactOnlyCensoredEstimator

likelihood_estimator(fit)[source]

Return a likelihood-aware estimator backed by a declared base-family fitting callback.

fit(observations, weights, initial_base) receives validated exact/interval evidence and must optimize the full censored objective, returning a fitted base distribution.

Parameters:: fit (Callable[[tuple[Any, ...], ndarray, Any], SequenceEncodableProbabilityDistribution])
Return type:: CensoredLikelihoodEstimator

dist_to_encoder()[source]

Return the data encoder (exact observations + censoring intervals split out).

Return type:: CensoredDataEncoder

class CensoredInterval(lower, upper)[source]

Bases: object

Closed interval likelihood evidence with validated ordered bounds.

Parameters:

lower (float)
upper (float)

class ExactObservation(value)[source]

Bases: object

Explicit exact evidence; useful when the child value could otherwise look like metadata.

Parameters:: value (Any)

CensoredEstimator: alias of ExactOnlyCensoredEstimator

class ExactOnlyCensoredEstimator(base_estimator, name=None, keys=None)[source]

Bases: ParameterEstimator

Projection estimator that deliberately excludes interval evidence and reports its weight.

Parameters:

base_estimator (ParameterEstimator)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for censored-data sufficient-statistic accumulators.

Return type:: CensoredAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

CensoredDistribution

class CensoredLikelihoodEstimator(initial_base, fit, name=None, keys=None)[source]

Bases: ParameterEstimator

Delegate full censored-objective optimization to a declared base-family callback.

Parameters:

initial_base (Any)
fit (Callable[[tuple[Any, ...], np.ndarray, Any], SequenceEncodableProbabilityDistribution])
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: CensoredLikelihoodAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (CensoredLikelihoodStatistics)

Return type:

CensoredDistribution

class CensoredExactOnlyFitReceipt(exact_weight, censored_weight, censored_fraction, likelihood_aware)[source]

Bases: NamedTuple

Parameters:

exact_weight (float)
censored_weight (float)
censored_fraction (float)
likelihood_aware (bool)

exact_weight: float: Alias for field number 0

censored_weight: float: Alias for field number 1

censored_fraction: float: Alias for field number 2

likelihood_aware: bool: Alias for field number 3

class CopulaDistribution(marginals, copula, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Joint over d scalar fields = d marginals coupled by a copula core (Sklar’s theorem).

marginals is a length-d sequence of CONTINUOUS mixle leaves, each exposing log_density, deterministic cdf/quantile methods, and the estimator/encoder contract – a marginal with enumerable (discrete/atomic) support is rejected at construction (see module docstring: the continuous Sklar density formula this class implements is not a valid probability model for discrete marginals). copula is a distribution on (0,1)^d (e.g. GaussianCopulaDistribution) whose dim must equal len(marginals). An observation is a length-d tuple/array of scalars (x_1, ..., x_d).

Parameters:

marginals (Sequence[SequenceEncodableProbabilityDistribution])
copula (SequenceEncodableProbabilityDistribution)
name (str | None)
keys (str | None)

density(x)[source]

Return the joint density at one raw observation.

Parameters:: x (Sequence[float])
Return type:: float

log_density(x)[source]

Sklar’s decomposition: sum of marginal log-densities + the copula log-density at the PIT scores.

Parameters:: x (Sequence[float])
Return type:: float

seq_log_density(enc)[source]

Vectorized: per-column marginal log-densities (summed) plus the copula log-density at the PIT scores.

Parameters:: enc (Any)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler that draws copula scores and inverts the marginals.

Parameters:: seed (int | None)
Return type:: CopulaSampler

estimator(pseudo_count=None)[source]

Return an IFM estimator for marginals followed by the copula core.

Parameters:: pseudo_count (float | None)
Return type:: CopulaEstimator

dist_to_encoder()[source]

Return an encoder that preserves marginal encodings and raw columns.

Return type:: CopulaDataEncoder

class CopulaEstimator(marginal_estimators, copula_estimator, dim, copula_prototype, name=None, keys=None)[source]

Bases: ParameterEstimator

IFM estimator: fit each marginal from its sub-stats, PIT the buffered data, fit the copula on the scores.

Parameters:

marginal_estimators (Sequence[ParameterEstimator])
copula_estimator (ParameterEstimator)
dim (int)
copula_prototype (SequenceEncodableProbabilityDistribution)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for IFM copula sufficient-statistic accumulators.

Return type:: CopulaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate marginals, transform buffered data by PIT, and estimate the copula core.

Parameters:

nobs (float | None)
suff_stat (CopulaIFMStatistics)

Return type:

CopulaDistribution

class CopulaIFMStatistics(schema_version, marginal_statistics, columns, weights, marginal_effective_count, copula_effective_count)[source]

Bases: NamedTuple

Versioned IFM state with explicit stage-specific effective counts.

Parameters:

schema_version (int)
marginal_statistics (tuple[Any, ...])
columns (ndarray)
weights (ndarray)
marginal_effective_count (float)
copula_effective_count (float)

schema_version: int: Alias for field number 0

marginal_statistics: tuple[Any, ...]: Alias for field number 1

columns: ndarray: Alias for field number 2

weights: ndarray: Alias for field number 3

marginal_effective_count: float: Alias for field number 4

copula_effective_count: float: Alias for field number 5

exception CopulaQuantileError[source]

Bases: RuntimeError

Raised when a marginal quantile violates its declared CDF inverse contract.

class ExponentiallyModifiedGaussianDistribution(mu, sigma2, lam, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Exponentially-modified Gaussian: X = N(mu, sigma2) + Exp(rate=lam).

Parameters:

mu (float)
sigma2 (float)
lam (float)
name (str | None)
keys (str | None)

density(x)[source]

Density of the EMG at observation x (see log_density).

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Stable log-density of the EMG at x.

log f(x) = log(lam/2) - 0.5*u^2 + log_erfcx(z) with u = (x - mu)/sigma and z = (lam*sigma - u)/sqrt(2).

Parameters:: x (float)
Return type:: float

seq_ld_lambda()[source]

Return vectorized log-density callables for encoded data.

Return type:: list[Callable]

seq_log_density(x)[source]

Vectorized EMG log-density at sequence-encoded input x.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Declare NumPy/Torch scoring capabilities for EMG log-density kernels.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized EMG log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact, via scipy’s exponnorm).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

sampler(seed=None)[source]

Return an ExponentiallyModifiedGaussianSampler for this distribution.

Parameters:: seed (int | None)
Return type:: ExponentiallyModifiedGaussianSampler

estimator(pseudo_count=None)[source]

Return an ExponentiallyModifiedGaussianEstimator (method-of-moments).

Parameters:: pseudo_count (float | None)
Return type:: ExponentiallyModifiedGaussianEstimator

dist_to_encoder()[source]

Return the encoder for exponentially modified Gaussian observations.

Return type:: ExponentiallyModifiedGaussianDataEncoder

class ExponentiallyModifiedGaussianEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate EMG parameters from weighted central moments.

The fit is SHIFT-EQUIVARIANT: estimating on x + c returns mu + c with sigma2 and lam unchanged, for any constant c the data can carry – epoch seconds (~1.7e9), 2**31 and 1e12 included. The moments come from ExponentiallyModifiedGaussianAccumulator, which centers each batch twice for exactly this reason; a single centering pass moved the fit by 1.3e-4 at 1e12, silently.

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for EMG central-moment accumulators.

Return type:: ExponentiallyModifiedGaussianAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an EMG from the accumulated (count, mean, M2, M3) via method of moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float, float])

Return type:

ExponentiallyModifiedGaussianDistribution

class SkellamDistribution(mu1, mu2, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Skellam distribution: K = N1 - N2 for independent N1 ~ Poisson(mu1), N2 ~ Poisson(mu2).

Parameters:

mu1 (float)
mu2 (float)
name (str | None)
keys (str | None)

density(x)[source]

Probability mass at integer x (see log_density).

Parameters:: x (int)
Return type:: float

log_density(x)[source]

Stable Skellam log-mass at integer x (-inf for non-integer input).

Parameters:: x (int)
Return type:: float

seq_log_density(x)[source]

Vectorized Skellam log-mass at sequence-encoded integer counts x.

Parameters:: x (ndarray)
Return type:: ndarray

mean()[source]

Mean E[X] = mu1 - mu2.

Return type:: float

variance()[source]

Variance Var[X] = mu1 + mu2.

Return type:: float

entropy()[source]

Shannon entropy in nats, by exact two-sided summation of the standard series.

The Skellam entropy -sum_k p_k log p_k has no closed form. The sum runs over the support between this distribution’s own quantiles at 1e-16 and 1 - 1e-16 (plus a safety margin on each side), beyond which the remaining tail mass on both sides is far below double rounding. Terms where the scaled Bessel term underflows to exactly zero (mass indistinguishable from 0 at double precision) are dropped, matching the p log p -> 0 limit.

Return type:: float

classmethod compute_capabilities()[source]: Describe backend support for generated Skellam scoring kernels.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized Skellam log-mass for encoded data (see class backend note).

The series yields the UNSCALED log I_k (not log ive = log I_k - z), so the constant here is -(mu1 + mu2) — the legacy path’s -sqrt_diff_sq plus its implicit -z.

Parameters:

x (Any)
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (via scipy skellam).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) (via scipy skellam).

Parameters:: q (float)
Return type:: float

sampler(seed=None)[source]

Return a SkellamSampler for this distribution.

Parameters:: seed (int | None)
Return type:: SkellamSampler

estimator(pseudo_count=None)[source]

Return a SkellamEstimator (method of moments).

Parameters:: pseudo_count (float | None)
Return type:: SkellamEstimator

dist_to_encoder()[source]

Return the encoder for Skellam observations.

Return type:: SkellamDataEncoder

enumerator()[source]

Return an enumerator over all integers in descending probability order.

Return type:: SkellamEnumerator

class SkellamEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate (mu1, mu2) by the (exact, closed-form) method of moments.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Skellam moment statistics.

Return type:: SkellamAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a Skellam from the accumulated (count, sum, sum2) via method of moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

SkellamDistribution

class SkewNormalDistribution(loc, scale, shape, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Skew-normal distribution with location loc, scale > 0 and shape alpha.

Parameters:

loc (float)
scale (float)
shape (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated skew-normal scoring kernels.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized skew-normal log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean E[X] = loc + scale * delta * sqrt(2/pi), delta = shape / sqrt(1 + shape^2).

Return type:: float

variance()[source]

Variance Var[X] = scale^2 (1 - 2 delta^2 / pi), delta = shape / sqrt(1 + shape^2).

Return type:: float

entropy()[source]

Differential entropy log(scale) + 0.5 log(2 pi e) - log(2) - E[log Phi(alpha Y)].

Y is the standard skew-normal(alpha); E[Y^2] = 1 for every alpha (a property of the two-Gaussian stochastic representation) collapses the Gaussian part of the log-density to a closed form, leaving E[log Phi(alpha Y)]. That term has no closed form for general alpha (Arellano-Valle, Contreras-Reyes & Genton, ‘Shannon entropy and mutual information for multivariate skew-elliptical distributions’, Scand. J. Statist. 40 (2013)), so it is evaluated by adaptive quadrature against the standard skew-normal density itself.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: SkewNormalSampler

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for loc, scale and shape.

Parameters:: pseudo_count (float | None)
Return type:: SkewNormalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: SkewNormalDataEncoder

class SkewNormalEstimator(pseudo_count=None, suff_stat=None, min_scale=1.0e-12, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for skew-normal location, scale and shape.

The fit is SHIFT-EQUIVARIANT: estimating on x + c returns loc + c with scale and shape unchanged, for any constant c the data can carry – epoch seconds (~1.7e9), 2**31 and 1e12 included. The moments come from SkewNormalAccumulator, which centers each batch twice for exactly this reason; a single centering pass left the fitted shape 1.1e-3 off at 1e12, silently.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float, float] | None)
min_scale (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for skew-normal moment statistics.

Return type:: SkewNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location, scale, and shape from weighted central moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float, float])

Return type:

SkewNormalDistribution

class TweedieDistribution(mu, phi, p=1.5, name=None, keys=None, *, max_series_terms=_DEFAULT_MAX_SERIES_TERMS, max_series_work=_DEFAULT_MAX_SERIES_WORK, series_tolerance=_DEFAULT_SERIES_TOLERANCE)[source]

Bases: SequenceEncodableProbabilityDistribution

Tweedie (compound Poisson-Gamma) distribution on [0, inf) with fixed power p in (1, 2).

Parameters:

mu (float)
phi (float)
p (float)
name (str | None)
keys (str | None)
max_series_terms (int)
max_series_work (int)
series_tolerance (float)

density(x)[source]

Probability density (or the point mass at 0) at x (see log_density).

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Tweedie log-density: log P(Y=0) = -lam at 0, the series for x > 0, -inf for x < 0.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Vectorized Tweedie log-density at sequence-encoded non-negative observations x.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Return compute-backend metadata for Tweedie scoring.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized Tweedie log-density for encoded data (see class backend note).

Parameters:

x (Any)
engine (Any)

Return type:

sampler(seed=None)[source]

Return a TweedieSampler for this distribution.

Parameters:: seed (int | None)
Return type:: TweedieSampler

estimator(pseudo_count=None)[source]

Return a TweedieEstimator (method of moments at the fixed power p).

Parameters:: pseudo_count (float | None)
Return type:: TweedieEstimator

dist_to_encoder()[source]

Return the encoder for Tweedie observations.

Return type:: TweedieDataEncoder

exception TweedieSeriesResourceError(*, required_terms, rows, max_terms, max_work)[source]

Bases: RuntimeError

A Tweedie density series exceeded its declared term or work budget.

Parameters:

required_terms (int)
rows (int)
max_terms (int)
max_work (int)

Return type:

None

class TweedieEstimator(p=1.5, pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate (mu, phi) at fixed power p by the (exact) method of moments.

Parameters:

p (float)
pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Tweedie moment accumulators.

Return type:: TweedieAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a Tweedie from the accumulated (count, sum, sum2) via method of moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

TweedieDistribution

class BirthDeathSamplingDistribution(birth_rate, death_rate, sampling_rate=0.0, initial_population=1, horizon=10.0, name=None, keys=None, prior_shape=1.0, prior_rate=0.0)[source]

Bases: SequenceEncodableProbabilityDistribution

General linear birth-death-sampling process (fossilized birth-death is the sampling_rate>0 case).

Parameters:

birth_rate (float)
death_rate (float)
sampling_rate (float)
initial_population (int)
horizon (float)
name (str | None)
keys (str | None)
prior_shape (Any)
prior_rate (Any)

density(x)[source]

Probability density of one trajectory (see log_density).

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Log-likelihood of one fully-observed trajectory (n0, T, events).

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Vectorized log-likelihood for validated (N, 6) encoded rows.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a BirthDeathSamplingSampler for this distribution.

Parameters:: seed (int | None)
Return type:: BirthDeathSamplingSampler

estimator(pseudo_count=None)[source]

Return a fixed-configuration closed-form MLE or Gamma MAP estimator.

Parameters:: pseudo_count (float | None)
Return type:: BirthDeathSamplingEstimator

dist_to_encoder()[source]

Return the encoder for birth-death samples.

Return type:: BirthDeathSamplingDataEncoder

class BirthDeathSamplingStatistics(births, deaths, samplings, population_exposure, trajectory_weight, horizon_weight)[source]

Bases: NamedTuple

Versioned, tuple-compatible aggregate birth-death statistics.

Parameters:

births (float)
deaths (float)
samplings (float)
population_exposure (float)
trajectory_weight (float)
horizon_weight (float)

births: float: Alias for field number 0

deaths: float: Alias for field number 1

samplings: float: Alias for field number 2

population_exposure: float: Alias for field number 3

trajectory_weight: float: Alias for field number 4

horizon_weight: float: Alias for field number 5

property schema_version: int: Return the serialized statistic schema version.

class BirthDeathSamplingEstimator(name=None, keys=None, pseudo_count=None, initial_population=1, horizon=10.0, prior_shape=None, prior_rate=None)[source]

Bases: ParameterEstimator

Closed-form per-channel MLE or Gamma-prior MAP estimator.

Parameters:

name (str | None)
keys (str | None)
pseudo_count (float | None)
initial_population (int)
horizon (float)
prior_shape (Any | None)
prior_rate (Any | None)

accumulator_factory()[source]

Return a factory for birth-death-sampling sufficient-statistic accumulators.

Return type:: BirthDeathSamplingAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate per-capita rates while preserving fixed sampling configuration.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float, float, float, float])

Return type:

BirthDeathSamplingDistribution

class ContinuousTimeMarkovChainDistribution(rates, initial_state=0, horizon=10.0, name=None, keys=None, prior_shape=1.0, prior_rate=0.0)[source]

Bases: SequenceEncodableProbabilityDistribution

CTMC on K states with generator Q (off-diagonal rates); MLE is closed form (GLOBAL_UNIQUE).

Parameters:

rates (np.ndarray)
initial_state (int)
horizon (float)
name (str | None)
keys (str | None)
prior_shape (Any)
prior_rate (Any)

property generator: ndarray: The generator matrix Q (off-diagonal rates, diagonal = -exit rate).

density(x)[source]

Return the probability density of one fully observed trajectory.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-likelihood of one fully observed CTMC trajectory.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-likelihoods for encoded trajectory statistics.

Parameters:: x (Any)
Return type:: ndarray

sampler(seed=None)[source]

Return a Gillespie sampler for trajectories from this CTMC.

Parameters:: seed (int | None)
Return type:: ContinuousTimeMarkovChainSampler

estimator(pseudo_count=None)[source]

Return the closed-form rate estimator for this state space.

pseudo_count=c is the compatibility shorthand for independent off-diagonal Gamma(shape=1+c, rate=c) priors. With no override, the distribution’s explicit edgewise priors are preserved.

Parameters:: pseudo_count (float | None)
Return type:: ContinuousTimeMarkovChainEstimator

dist_to_encoder()[source]

Return the trajectory-statistics encoder used by vectorized methods.

Return type:: ContinuousTimeMarkovChainDataEncoder

class ContinuousTimeMarkovChainStatistics(transition_counts, dwell_times)[source]

Bases: NamedTuple

Versioned, tuple-compatible aggregate CTMC statistics.

Parameters:

transition_counts (ndarray)
dwell_times (ndarray)

transition_counts: ndarray: Alias for field number 0

dwell_times: ndarray: Alias for field number 1

property schema_version: int: Return the serialized statistic schema version.

class ContinuousTimeMarkovChainEstimator(num_states, pseudo_count=None, initial_state=0, horizon=10.0, name=None, keys=None, prior_shape=None, prior_rate=None)[source]

Bases: ParameterEstimator

Closed-form independent-edge CTMC MLE or Gamma-prior MAP estimator.

For edge i -> j, an explicit Gamma(shape_ij, rate_ij) prior gives q_ij = (n_ij + shape_ij - 1) / (T_i + rate_ij). Shapes must be at least one so the finite non-negative MAP is well defined. The default shape=1, rate=0 recovers the MLE. The legacy pseudo_count=c spelling maps coherently to shape=1+c, rate=c on every off-diagonal edge; it cannot be mixed with explicit priors.

Parameters:

num_states (int)
pseudo_count (float | None)
initial_state (int)
horizon (float)
name (str | None)
keys (str | None)
prior_shape (Any | None)
prior_rate (Any | None)

accumulator_factory()[source]

Return a factory for CTMC sufficient-statistic accumulators.

Return type:: ContinuousTimeMarkovChainAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate off-diagonal rates with the documented Gamma-prior MAP.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

ContinuousTimeMarkovChainDistribution

class InhomogeneousPoissonProcessDistribution(rates, t_max=None, edges=None, name=None, keys=None, prior_shape=1.0, prior_rate=0.0)[source]

Bases: SequenceEncodableProbabilityDistribution

Inhomogeneous Poisson process with piecewise-constant intensity on a fixed window.

Parameters:

rates (Sequence[float] | ndarray)
t_max (float | None)
edges (Sequence[float] | ndarray | None)
name (str | None)
keys (str | None)
prior_shape (Any)
prior_rate (Any)

intensity(t, times=None, marks=None)[source]

Conditional rate lambda(t) = rates[bin containing t].

The inhomogeneous Poisson process is not self-exciting, so the rate depends only on t. times/marks are accepted for TemporalPointProcess signature parity and ignored. Raises ValueError for t outside the support [edges[0], edges[-1]].

Parameters:

t (float)
times (Any)
marks (Any)

Return type:

expected_count(t_start, t_end, times=None, marks=None)[source]

Compensator integral_{t_start}^{t_end} lambda(s) ds – the piecewise-rate integral.

Computed as sum_b rate_b * width(overlap([t_start, t_end], bin_b)). times/marks are accepted for signature parity and ignored. With t_start=edges[0], t_end=edges[-1] this returns the full integral sum_b rate_b width_b used by log_density.

Parameters:

t_start (float)
t_end (float)
times (Any)
marks (Any)

Return type:

density(x)[source]

Probability density of one realization x (a sequence of event times).

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Log-likelihood of one realization: sum_b n_b log rate_b - sum_b rate_b width_b.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Vectorized log-likelihood for a (num_realizations, num_bins) matrix of per-bin counts.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return an InhomogeneousPoissonProcessSampler for this distribution.

Parameters:: seed (int | None)
Return type:: InhomogeneousPoissonProcessSampler

estimator(pseudo_count=None)[source]

Return an InhomogeneousPoissonProcessEstimator over the same bin edges.

Parameters:: pseudo_count (float | None)
Return type:: InhomogeneousPoissonProcessEstimator

dist_to_encoder()[source]

Returns an InhomogeneousPoissonProcessDataEncoder bound to these bin edges.

Return type:: InhomogeneousPoissonProcessDataEncoder

class InhomogeneousPoissonProcessStatistics(bin_counts, realization_weight)[source]

Bases: NamedTuple

Versioned, tuple-compatible process statistics.

Parameters:

bin_counts (ndarray)
realization_weight (float)

bin_counts: ndarray: Alias for field number 0

realization_weight: float: Alias for field number 1

property schema_version: int: Return the serialized statistic schema version.

class InhomogeneousPoissonProcessEstimator(num_bins=None, t_max=None, edges=None, name=None, keys=None, pseudo_count=None, prior_shape=None, prior_rate=None)[source]

Bases: ParameterEstimator

Closed-form MLE: rate_b = (weighted events in bin b) / (width_b * weighted realizations).

Parameters:

num_bins (int | None)
t_max (float | None)
edges (Sequence[float] | ndarray | None)
name (str | None)
keys (str | None)
pseudo_count (float | None)
prior_shape (Any | None)
prior_rate (Any | None)

accumulator_factory()[source]

Return a factory for inhomogeneous Poisson sufficient-statistic accumulators.

Return type:: InhomogeneousPoissonProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate per-bin rates from accumulated (bin_counts, n_realizations).

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, float])

Return type:

InhomogeneousPoissonProcessDistribution

class RenewalProcessDistribution(interarrival, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: SequenceEncodableProbabilityDistribution

Renewal process with i.i.d. inter-arrivals interarrival observed on [0, window].

Parameters:

interarrival (Any)
window (float)
name (str | None)
keys (str | None)
max_events (int)

log_density(x)[source]

Exact log-likelihood of one realization (observed gaps + censored survival).

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Vectorized log-likelihood for encoded realizations (flattened gaps + per-realization survival).

Parameters:: x (Any)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler that draws gaps until the cumulative time exceeds window.

Parameters:: seed (int | None)
Return type:: RenewalProcessSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits the inter-arrival distribution to the observed gaps.

Parameters:: pseudo_count (float | None)
Return type:: RenewalProcessEstimator

dist_to_encoder()[source]

Return the data encoder (delegates gap encoding to the inter-arrival encoder).

Return type:: RenewalProcessDataEncoder

class RenewalProcessStatistics(gap_statistics, completed_gaps, completed_weights, censored_times, censored_weights)[source]

Bases: NamedTuple

Versioned renewal evidence including right-censoring.

Parameters:

gap_statistics (Any)
completed_gaps (ndarray)
completed_weights (ndarray)
censored_times (ndarray)
censored_weights (ndarray)

gap_statistics: Any: Alias for field number 0

completed_gaps: ndarray: Alias for field number 1

completed_weights: ndarray: Alias for field number 2

censored_times: ndarray: Alias for field number 3

censored_weights: ndarray: Alias for field number 4

property schema_version: int: Return the serialized statistic schema version.

class RenewalProcessEstimator(interarrival_estimator, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: ParameterEstimator

Fit supported inter-arrival families to the full censored likelihood.

Parameters:

interarrival_estimator (ParameterEstimator)
window (float)
name (str | None)
keys (str | None)
max_events (int)

accumulator_factory()[source]

Return an accumulator factory for observed inter-arrival gaps.

Return type:: RenewalProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the inter-arrival distribution and keep the fixed window.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

RenewalProcessDistribution

class HawkesProcessDistribution(mu, alpha, beta, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: SequenceEncodableProbabilityDistribution

Univariate Hawkes process with an exponential excitation kernel on a fixed window.

Parameters:

mu (float)
alpha (float)
beta (float)
window (float)
name (str | None)
keys (str | None)
max_events (int)

intensity(t, times, marks=None)[source]

Conditional rate lambda(t) = mu + alpha sum_{t_i < t} exp(-beta (t - t_i)) given the history.

times is the event history; marks is accepted for TemporalPointProcess signature parity (the univariate Hawkes process is unmarked) and is ignored.

Parameters:

t (float)
times (Any)
marks (Any)

Return type:

expected_count(t_start, t_end, times, marks=None)[source]

Compensator integral_{t_start}^{t_end} lambda(s) ds of the intensity given the history.

marks is accepted for signature parity and ignored (the univariate process is unmarked).

Parameters:

t_start (float)
t_end (float)
times (Any)
marks (Any)

Return type:

density(x)[source]

Probability density of one realization x (a sequence of event times).

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Exact log-likelihood of one realization (a strictly increasing event-time sequence in [0, window]).

The conditional intensity is defined over the strict history t_j < t (see the class docstring), so a realization with a tied timestamp pair (t_j == t_i for j != i) is not a valid t_1 < ... < t_n history – like any other malformed ordering, it scores -inf rather than silently letting one of the tied events excite the other.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Vectorized exact log-likelihood over a padded (num_realizations, max_len) time matrix.

Parameters:: x (tuple[ndarray, ndarray, float])
Return type:: ndarray

sampler(seed=None)[source]

Return a HawkesProcessSampler (Ogata thinning) for this distribution.

Parameters:: seed (int | None)
Return type:: HawkesProcessSampler

estimator(pseudo_count=None)[source]

Return a HawkesProcessEstimator over the same observation window.

Parameters:: pseudo_count (float | None)
Return type:: HawkesProcessEstimator

dist_to_encoder()[source]

Returns a HawkesProcessDataEncoder bound to this window.

Return type:: HawkesProcessDataEncoder

class MultivariateHawkesProcessDistribution(mu, alpha, beta, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: SequenceEncodableProbabilityDistribution

Multivariate Hawkes process: baselines mu (D), excitation alpha (D, D), decay beta.

Parameters:

mu (ndarray)
alpha (ndarray)
beta (float)
window (float)
name (str | None)
keys (str | None)
max_events (int)

intensity(t, times, marks)[source]

Per-mark conditional rate vector (the vector-valued variant of intensity).

Returns lambda(t) of shape (D,) with lambda_k(t) = mu_k + sum_{(t_i, m_i) < t} alpha[k, m_i] exp(-beta (t - t_i)).

Parameters:

t (float)
times (Any)
marks (Any)

Return type:

expected_count(t_start, t_end, times, marks)[source]

Per-mark compensator vector (the vector-valued variant of expected_count).

Returns (D,) with the integral of lambda_k over [t_start, t_end] given the history.

Parameters:

t_start (float)
t_end (float)
times (Any)
marks (Any)

Return type:

density(x)[source]

Probability density of one realization (a sequence of (time, mark) events).

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Exact log-likelihood of one realization of marked events sorted by time.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Log-likelihood for a list of realizations.

Parameters:: x (list[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler (multivariate Ogata thinning).

Parameters:: seed (int | None)
Return type:: MultivariateHawkesProcessSampler

estimator(pseudo_count=None)[source]

Return an exact finite-window estimator.

Parameters:: pseudo_count (float | None)
Return type:: MultivariateHawkesProcessEstimator

dist_to_encoder()[source]

Return the data encoder (passes realizations through; the likelihood is per-realization).

Return type:: MultivariateHawkesProcessDataEncoder

class MultivariateHawkesProcessEstimator(dim, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: ParameterEstimator

Exact weighted finite-window maximum-likelihood estimator.

Parameters:

dim (int)
window (float)
name (str | None)
keys (str | None)
max_events (int)

accumulator_factory()[source]

Return an accumulator factory for branching EM statistics.

Return type:: MultivariateHawkesProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Maximize the exact compensator-aware weighted log-likelihood.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

MultivariateHawkesProcessDistribution

class HawkesProcessEstimator(window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: ParameterEstimator

Exact weighted finite-window maximum-likelihood estimator.

Parameters:

window (float)
name (str | None)
keys (str | None)
max_events (int)

accumulator_factory()[source]

Return a factory for Hawkes EM sufficient-statistic accumulators.

Return type:: HawkesProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Maximize the exact compensator-aware weighted log-likelihood.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

HawkesProcessDistribution

class ExponentialTiltedDistribution(base, theta, statistic=None, log_normalizer=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A base distribution reweighted by exp(theta . T(x)) and renormalized by Z(theta).

Parameters:

base (SequenceEncodableProbabilityDistribution)
theta (Any)
statistic (str | Callable[[Any], Any] | None)
log_normalizer (Callable[[Any], float] | float | None)
name (str | None)
keys (str | None)

density(x)[source]

Return the tilted probability/density at x.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return log p_base(x) + theta . T(x) - log Z.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return per-row tilted log-densities for an encoded batch.

Parameters:: x (tuple[Any, ndarray])
Return type:: ndarray

closed_form()[source]

Return the in-family tilted distribution when the tilt closes in the base family, else None.

Return type:: SequenceEncodableProbabilityDistribution | None

sampler(seed=None)[source]

Return a sampler (exact for registered/enumerable bases; SIR otherwise).

Parameters:: seed (int | None)
Return type:: ExponentialTiltedSampler

estimator(pseudo_count=None, fit='theta')[source]

Return an estimator. fit='theta' fits the tilt by the exponential-family score equation E_theta[T] = mean(T(data)) (base + statistic fixed); fit='base' holds theta fixed and refits the base on the data, re-tilting (the fixed-tilt analogue of the truncation estimator).

Parameters:

pseudo_count (float | None)
fit (str)

Return type:

ExponentialTiltedEstimator

dist_to_encoder()[source]

Return the data encoder (base encoding plus the precomputed statistic per row).

Return type:: ExponentialTiltedDataEncoder

support_size()[source]

Tilting preserves the support, so the cardinality is the base’s.

Return type:: int | None

enumerator()[source]

Enumerate the support in descending tilted-probability order.

Return type:: ExponentialTiltedEnumerator

class ExponentialTiltedEstimator(prototype, pseudo_count=None, fit='theta', max_iter=60, tol=1e-8)[source]

Bases: ParameterEstimator

Fit the tilt by the exp-family score equation (fit='theta') or refit the base (fit='base').

Parameters:

prototype (ExponentialTiltedDistribution)
pseudo_count (float | None)
fit (str)
max_iter (int)
tol (float)

accumulator_factory()[source]

Return a factory for exponential-tilt sufficient-statistic accumulators.

Return type:: ExponentialTiltedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate either the tilt parameter or the tilted base distribution.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

ExponentialTiltedDistribution

class ExponentialTiltedEnumerator(dist)[source]

Bases: DistributionEnumerator

Reweight the base enumeration by theta . T(a) - log Z and re-sort descending.

Parameters:: dist (ExponentialTiltedDistribution)

register_exponential_tilt(dist_type, fn)[source]

Parameters:

dist_type (type)
fn (Callable[[Any, float], TiltResult])

Return type:

None

registered_tilt_families()[source]

Return the names of base families with a registered analytic tilt.

Return type:: list[str]

class IdentityTransform[source]

Bases: object

Identity transform y = x.

forward(x)[source]

Return x unchanged.

Parameters:: x (Any)
Return type:: Any

inverse(y)[source]

Return y unchanged.

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

Return the log absolute inverse-Jacobian determinant.

Parameters:: y (Any)
Return type:: float

invalid_inverse_value()[source]

Return a safe child-space fill value for invalid inverses.

Return type:: float

class AffineTransform(loc=0.0, scale=1.0)[source]

Bases: object

Affine transform y = loc + scale * x.

Parameters:

loc (float)
scale (float)

forward(x)[source]

Apply the affine map to a child-space value.

Parameters:: x (Any)
Return type:: Any

inverse(y)[source]

Map a transformed-space value back to child space.

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

Return the constant affine inverse-Jacobian correction.

Parameters:: y (Any)
Return type:: float

invalid_inverse_value()[source]

Return a safe child-space fill value for invalid inverses.

Return type:: float

class ExpTransform[source]

Bases: object

Exponential transform y = exp(x), mapping real x to positive y.

forward(x)[source]

Map a real value to the positive scale.

Parameters:: x (Any)
Return type:: Any

inverse(y)[source]

Map a positive transformed value back to the real line.

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

Return the log inverse-Jacobian correction for log(y).

Parameters:: y (Any)
Return type:: float

invalid_inverse_value()[source]

Return a safe child-space fill value for invalid inverses.

Return type:: float

class LogTransform[source]

Bases: object

Log transform y = log(x), mapping positive x to real y.

forward(x)[source]

Map a positive child value to the real line.

Parameters:: x (Any)
Return type:: Any

inverse(y)[source]

Map a real transformed value back to the positive scale.

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

Return the log inverse-Jacobian correction for exp(y).

Parameters:: y (Any)
Return type:: float

invalid_inverse_value()[source]

Return a safe positive child-space fill value for invalid inverses.

Return type:: float

class LogitTransform[source]

Bases: object

Logistic transform y = 1 / (1 + exp(-x)), mapping real x to (0, 1).

forward(x)[source]

Map a real value into the open unit interval.

Parameters:: x (Any)
Return type:: Any

inverse(y)[source]

Map a unit-interval value back to the real line.

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

Return the log inverse-Jacobian correction for the logit map.

Parameters:: y (Any)
Return type:: float

invalid_inverse_value()[source]

Return a safe child-space fill value for invalid inverses.

Return type:: float

class LDADistribution(topics, alpha, len_dist=NullDistribution(), gamma_threshold=1.0e-8, max_gamma_iter=100, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Latent Dirichlet allocation model for documents given as bags of weighted values.

Data type: Sequence[Tuple[T, float]], where T is the data type of the topic distributions and each (value, count) pair gives the count of a value in the document.

Parameters:

topics (Sequence[SequenceEncodableProbabilityDistribution])
alpha (Sequence[float] | ndarray)
len_dist (SequenceEncodableProbabilityDistribution | None)
gamma_threshold (float)
max_gamma_iter (int)
fit_diagnostics (LDAOptimizationDiagnostics | None)

compute_capabilities()[source]: Return backend capability metadata for this concrete LDA instance.

compute_declaration()[source]: Return the generated-compute declaration for latent Dirichlet allocation.

density(x)[source]

Evaluate the density of a single LDA document.

See log_density() for details.

Parameters:: x (Sequence[Tuple[int, float]]) – A document given as (value, count) pairs.
Returns:: Density evaluated at x.
Return type:: float

density_semantics()[source]: Return density semantics for the variational LDA document bound.

log_density(x)[source]

Evaluate the log-density of a single LDA document.

Note: The returned value is the variational lower bound (ELBO) on the marginal document log-likelihood obtained from the standard LDA mean-field approximation, not the exact (intractable) marginal log-likelihood.

Parameters:: x (Sequence[Tuple[int, float]]) – A document given as (value, count) pairs.
Returns:: Variational lower bound on the log-density evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of the document log-densities for an encoded corpus x.

Encoded sequence ‘x’ is a Tuple of length 5 containing:: x[0] (int): Number of documents in corpus. x[1] (np.ndarray): Document id for flattened array of values. x[2] (np.ndarray): Flattened array of counts for each value in each document. x[3] (Optional[np.ndarray]): Optional warm-start gammas (defaults to None). x[4] (E0): Sequence encoded flattened values.

Note: Returns the per-document variational lower bound (ELBO); see log_density(). If a document-length distribution ‘len_dist’ is set, its log-density of the total token count of each document is added to the returned values.

Parameters:: x (tuple[int, ndarray, ndarray, ndarray | None, E0]) – Encoded corpus of LDA documents (see LDADataEncoder.seq_encode()).
Returns:: Numpy array of log-density (ELBO) values, one entry per document.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Backend-neutral LDA variational lower-bound scoring.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray | None, E0])
engine (Any)

Return type:

seq_component_log_density(x)[source]

Vectorized evaluation of the per-topic log-density of each document in encoded corpus x.

Parameters:: x (tuple[int, ndarray, ndarray, ndarray | None, E0]) – Encoded corpus of LDA documents (see LDADataEncoder.seq_encode()).
Returns:: 2-d numpy array with shape (number of documents, n_topics), where entry (i, l) is the log-density of document i evaluated entirely under topic l.
Return type:: ndarray

backend_seq_component_log_density(x, engine)[source]

Backend-neutral per-topic document scores.

Parameters:

x (tuple[int, ndarray, ndarray, ndarray | None, E0])
engine (Any)

Return type:

seq_posterior(x)[source]

Vectorized evaluation of the posterior topic proportions for each document in encoded corpus x.

The variational gammas are computed for each document and normalized to sum to one.

Parameters:: x (tuple[int, ndarray, ndarray, ndarray | None, E0]) – Encoded corpus of LDA documents (see LDADataEncoder.seq_encode()).
Returns:: 2-d numpy array with shape (number of documents, n_topics) containing posterior topic proportions for each document.
Return type:: ndarray

latent_posterior(doc)[source]

Return the mean-field variational posterior q(theta, z) for a single document.

Runs the per-document Blei-Ng-Jordan variational fixed point and returns a MeanFieldLDAPosterior: .topic_proportions() (the document-topic mix E[theta]), .marginals() (per-word topic responsibilities phi), .sample(rng) (theta, z), .mode() (MAP topic per word), or .entropy().

Parameters:: doc (Sequence[tuple[int, float]])
Return type:: MeanFieldLDAPosterior

posterior_predictive(doc, n_words, seed=None)[source]

Draw n_words new words conditioned on the document doc.

Sample the document-topic mix theta ~ q(theta) = Dir(gamma) from the variational posterior, then generate each new word by drawing a topic ~ theta and a word from that topic – “given this document, generate more words from its inferred topic mixture”.

Parameters:

doc (Sequence[tuple[int, float]])
n_words (int)
seed (int | None)

Return type:

list[Any]

sampler(seed=None)[source]

Create a sampler for documents from this distribution.

Parameters:: seed (Optional[int]) – Seed for the random number generator used in sampling.
Returns:: Sampler bound to this distribution.
Return type:: LDASampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this distribution’s topics.

Parameters:: pseudo_count (Optional[float]) – If passed, used to re-weight sufficient statistics during estimation.
Returns:: Estimator configured with matching topic and length estimators.
Return type:: LDAEstimator

dist_to_encoder()[source]

Return a data encoder for iid LDA documents.

Return type:: LDADataEncoder

enumerator()[source]

LDA does not support enumeration.

The document log-density is a variational lower bound (ELBO) over latent topic assignments rather than an exact density, so an enumeration satisfying log_prob == log_density over a well-defined support cannot be constructed.

Raises:: EnumerationError – Always.
Return type:: DistributionEnumerator

class LDAEstimator(estimators, len_estimator=NullEstimator(), suff_stat=None, pseudo_count=None, keys=(None, None), fixed_alpha=None, gamma_threshold=1.0e-8, alpha_threshold=1.0e-8, max_gamma_iter=100, max_alpha_iter=1000)[source]

Bases: ParameterEstimator

Estimate LDA distributions from aggregated variational sufficient statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
len_estimator (ParameterEstimator | None)
suff_stat (Any | None)
pseudo_count (float | tuple[float, float] | None)
keys (tuple[str | None, str | None] | None)
fixed_alpha (ndarray | None)
gamma_threshold (float)
alpha_threshold (float)
max_gamma_iter (int)
max_alpha_iter (int)

accumulator_factory()[source]

Return an accumulator factory configured from this estimator.

Return type:: LDAEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an LDA distribution from aggregated sufficient statistics.

suff_stat is a six-item tuple containing:: suff_stat[0] (Optional[np.ndarray]): Previous Dirichlet parameter estimate. suff_stat[1] (np.ndarray): Aggregated expected log topic proportions. suff_stat[2] (float): Aggregated weighted document count. suff_stat[3] (np.ndarray): Aggregated weighted per-topic value counts. suff_stat[4] (Sequence[SS0]): Sufficient statistics for each topic. suff_stat[5] (Optional[Any]): Sufficient statistics for the document-length distribution.

Parameters:

nobs (Optional[float]) – Weighted number of observations used in aggregation of suff_stat.
suff_stat – See above for details.

Returns:

Estimated distribution.

Return type:

LDADistribution

class VonMisesFisherDistribution(mu, kappa, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Von Mises-Fisher distribution on the (p-1)-sphere with mean direction mu and concentration kappa.

Data type: Union[Sequence[float], np.ndarray] (a unit-norm vector in R^p).

Parameters:

mu (Sequence[float] | ndarray)
kappa (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Declare backend support for von Mises-Fisher generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the von Mises-Fisher distribution.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Return row-wise legacy sufficient statistics for resident reductions.

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, mu, kappa, log_const, engine)[source]

Engine-neutral von Mises-Fisher log-density from fitted parameters.

Parameters:

x (Any)
mu (Any)
kappa (Any)
log_const (Any)
engine (Any)

Return type:

density(x)[source]

Density of von Mises-Fisher distribution at observation x.

See log_density() for details.

Parameters:: x (Union[Sequence[float], np.ndarray]) – Unit-norm vector in R^p.
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of von Mises-Fisher distribution at observation x.

The log-density is given by

log(f(x; mu, kappa)) = log(c_p(kappa)) + kappa * dot(mu, x),

for x on the (p-1)-sphere. When kappa = 0 this reduces to the uniform density on the sphere.

Parameters:: x (Union[Sequence[float], np.ndarray]) – Unit-norm vector in R^p.
Returns:: Log-density at observation x.
Return type:: float

density_cumulative(x)[source]

Exact probability-ordered cumulative G(x) = P(p(Y) >= p(x)) (the HDR mass at x).

A coordinate-wise CDF is undefined on the sphere (no total order), but since the density is monotone in the cosine t = mu . x (p(y) >= p(x) iff mu.y >= mu.x for kappa >= 0), the highest-density-region mass is the upper tail of the cosine marginal, whose density is f(s) proportional to exp(kappa s) (1 - s^2)^((p-3)/2) on [-1, 1]. G is that tail integral (computed by quadrature; the exp(kappa(s-1)) shift keeps it stable for large kappa and cancels in the ratio). Returned to density_rank as method exact-analytic.

Parameters:: x (Sequence[float] | ndarray)
Return type:: float

density_quantile(q)[source]

Inverse of density_cumulative(): a representative unit vector at cumulative-density q.

q is the highest-density-region mass; since the density is monotone in the cosine t = mu . y, the boundary is the cosine t_q with tail mass q, found by bisection on the cosine marginal. The returned representative is a unit vector at that cosine from mu (t_q * mu + sqrt(1 - t_q^2) * perp for a fixed perp orthogonal to mu). Sweeping q enumerates the sphere in descending density (concentric caps about mu).

Parameters:: q (float)
Return type:: ndarray

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (np.ndarray) – 2-d numpy array of N unit-norm vectors with p columns.
Returns:: Numpy array of log-density (float) of length N.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded unit-vector observations.

Parameters:

x (ndarray)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for equal-dimensional von Mises-Fisher mixtures.

Parameters:

dists (Sequence[VonMisesFisherDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of von Mises-Fisher component log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return component-stacked legacy (count, weighted_vector_sum) statistics.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Create a sampler from this von Mises-Fisher distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: VonMisesFisherSampler configured from this distribution.
Return type:: VonMisesFisherSampler

estimator(pseudo_count=None)[source]

Create an estimator for a von Mises-Fisher distribution.

Parameters:: pseudo_count (Optional[float]) – Kept for interface consistency (has no effect on estimation).
Returns:: VonMisesFisherEstimator configured with this distribution’s name and keys.
Return type:: VonMisesFisherEstimator

dist_to_encoder()[source]

Return the encoder for von Mises-Fisher observations.

Return type:: VonMisesFisherDataEncoder

class GaussianCopulaDistribution(corr, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gaussian copula on (0,1)^d with dependence given by a correlation matrix.

Parameters:

corr (ndarray)
name (str | None)
keys (str | None)

property corr: ndarray: Return an owned copy so cached scoring state cannot be desynchronized.

density(x)[source]

Return the copula density at a single point u in (0,1)^d.

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

Return the log copula density at a single point u in (0,1)^d.

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Vectorized log copula density for sequence-encoded observations (z = Phi^{-1}(u) rows).

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this copula.

Parameters:: seed (int | None)
Return type:: GaussianCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits the correlation matrix by the inversion estimator.

Parameters:: pseudo_count (float | None)
Return type:: GaussianCopulaEstimator

dist_to_encoder()[source]

Return the data encoder (stores the normal-score transform z = Phi^{-1}(u)).

Return type:: GaussianCopulaDataEncoder

class GaussianCopulaEstimator(dim, min_eig=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Inversion estimator: the correlation of the normal scores z = Phi^{-1}(u).

Parameters:

dim (int)
min_eig (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Gaussian copula sufficient-statistic accumulators.

Return type:: GaussianCopulaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the copula correlation matrix from normal-score moments.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray, float])

Return type:

GaussianCopulaDistribution

class ClaytonCopulaDistribution(dim, theta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Clayton copula on (0,1)^d with theta >= 0; zero is independence.

Parameters:

dim (int)
theta (float)
name (str | None)
keys (str | None)

log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:: u (ndarray)
Return type:: float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: u (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: ClaytonCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: ClaytonCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UScoreEncoder

class ClaytonCopulaEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

Kendall’s-tau inversion: theta = 2*tau / (1 - tau) (pair-averaged for d > 2).

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

ClaytonCopulaDistribution

class FrankCopulaDistribution(dim, theta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Frank copula on (0,1)^2 with dependence parameter theta (any sign; 0 = independence).

Parameters:

dim (int)
theta (float)
name (str | None)
keys (str | None)

log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:: u (ndarray)
Return type:: float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: u (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: FrankCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: FrankCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UScoreEncoder

class FrankCopulaEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

1-D maximum likelihood on theta over [-40, 40] (golden section on the copula log-likelihood).

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

FrankCopulaDistribution

class StudentTCopulaDistribution(corr, df, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Student-t copula on (0,1)^d with correlation corr and degrees of freedom df.

Parameters:

corr (np.ndarray)
df (float)
name (str | None)
keys (str | None)

property corr: ndarray: Return an owned copy so cached scoring state cannot be desynchronized.

log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:: u (ndarray)
Return type:: float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: u (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: StudentTCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: StudentTCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UScoreEncoder

class StudentTCopulaEstimator(dim, min_eig=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Inversion for R (correlation of the t-scores) + profile likelihood over nu on a grid.

Parameters:

dim (int)
min_eig (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

StudentTCopulaDistribution

class GumbelCopulaDistribution(dim, theta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gumbel copula on (0,1)^2 with upper-tail dependence parameter theta >= 1.

Parameters:

dim (int)
theta (float)
name (str | None)
keys (str | None)

log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:: u (ndarray)
Return type:: float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: u (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: GumbelCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: GumbelCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UScoreEncoder

class GumbelCopulaEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Kendall’s-tau inversion: theta = 1 / (1 - tau) (clamped to theta >= 1).

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

GumbelCopulaDistribution

class CVineCopulaDistribution(dim, pairs, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A canonical-vine (C-vine) copula on (0,1)^d: d(d-1)/2 bivariate pair copulas in a tree cascade.

pairs maps (tree, position) -> a fitted pair copula, tree in 1..d-1 and position in 1..d-tree (tree 1 links the root variable to each other; deeper trees link conditionally). Build one by hand, or fit with CVineCopulaEstimator (which selects a family per edge).

Parameters:

dim (int)
pairs (dict[tuple[int, int], Any])
candidates (tuple[str, ...])
name (str | None)
keys (str | None)

log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:: u (ndarray)
Return type:: float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: u (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: CVineCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: CVineCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UScoreEncoder

class CVineCopulaEstimator(dim, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: ParameterEstimator

Sequential (stepwise) MLE: fit tree by tree on conditional pseudo-observations, best family per edge.

Parameters:

dim (int)
candidates (tuple[str, ...])
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

CVineCopulaDistribution

class DVineCopulaDistribution(dim, pairs, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A drawable-vine (D-vine) copula on (0,1)^d: the second canonical vine, a PATH of pair copulas.

Where a C-vine has a star at each tree (one root linked to all), a D-vine has a path: tree 1 couples consecutive variables (1,2),(2,3),...,(d-1,d); deeper trees couple (i, i+j) given the variables between them. Same d(d-1)/2 pair copulas indexed (tree, position); different (path vs star) tree topology. Like the C-vine it is a drop-in dependence core for CopulaDistribution.

Parameters:

dim (int)
pairs (dict[tuple[int, int], Any])
candidates (tuple[str, ...])
name (str | None)
keys (str | None)

log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:: u (ndarray)
Return type:: float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: u (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: DVineCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: DVineCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UScoreEncoder

class DVineCopulaEstimator(dim, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: ParameterEstimator

Sequential (stepwise) MLE for a D-vine: fit tree by tree on conditional pseudo-obs, best family per edge.

Parameters:

dim (int)
candidates (tuple[str, ...])
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

DVineCopulaDistribution

class RVineCopulaDistribution(dim, trees, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A regular-vine copula on (0,1)^d: an arbitrary tree sequence of bivariate pair copulas.

Construct with RVineCopulaEstimator (Dißmann selection), which picks the tree structure AND a pair-copula family per edge from data. trees is the fitted structure (a list of trees, each a list of _Edge); dim the number of variables.

Parameters:

dim (int)
trees (list[list[_Edge]])
candidates (tuple[str, ...])
name (str | None)
keys (str | None)

classmethod independence(dim, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Construct an explicit, structurally complete independence R-vine.

Parameters:

dim (int)
candidates (tuple[str, ...])
name (str | None)
keys (str | None)

Return type:

RVineCopulaDistribution

log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:: u (ndarray)
Return type:: float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: u (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: RVineCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: RVineCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: UScoreEncoder

class RVineCopulaEstimator(dim, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: ParameterEstimator

Dißmann selection + sequential MLE: choose the tree structure and per-edge family from data.

Parameters:

dim (int)
candidates (tuple[str, ...])
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray])

Return type:

RVineCopulaDistribution

class MatrixNormalDistribution(mean, row_covar, col_covar, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Matrix normal distribution over (n, p) matrices with row covariance U and column covariance V.

Parameters:

mean (ndarray)
row_covar (ndarray)
col_covar (ndarray)
name (str | None)
keys (str | None)

density(x)[source]

Return the matrix-normal density at a single (n, p) matrix.

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

Return the log-density at a single (n, p) matrix.

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Vectorized log-density for a stack of matrices, shape (N, n, p).

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing matrices from this distribution.

Parameters:: seed (int | None)
Return type:: MatrixNormalSampler

estimator(pseudo_count=None)[source]

Return a flip-flop MLE estimator for the mean and the two covariance factors.

Parameters:: pseudo_count (float | None)
Return type:: MatrixNormalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: MatrixNormalDataEncoder

class MatrixNormalEstimator(n, p, max_iter=100, tol=1.0e-9, name=None, keys=None)[source]

Bases: ParameterEstimator

Flip-flop maximum-likelihood estimator for the matrix-normal parameters.

Parameters:

n (int)
p (int)
max_iter (int)
tol (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for matrix-normal sufficient-statistic accumulators.

Return type:: MatrixNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the mean and covariance factors using flip-flop updates.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, ndarray, float])

Return type:

MatrixNormalDistribution

exception MatrixNormalFitError[source]

Bases: RuntimeError

Raised when a matrix-normal MLE is invalid or non-identifiable.

class WatsonDistribution(mu, kappa, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Watson distribution on the unit sphere S^{p-1} with axis mu and concentration kappa.

Parameters:

mu (ndarray)
kappa (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the density at a single unit vector x.

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

Return the log-density at a single unit vector x.

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Vectorized log-density for a stack of unit vectors, shape (N, p).

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated Watson scoring kernels.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for (N, p) unit vectors.

Parameters:

x (Any)
engine (Any)

Return type:

sampler(seed=None)[source]

Return an exact rejection sampler for this Watson distribution.

Parameters:: seed (int | None)
Return type:: WatsonSampler

estimator(pseudo_count=None)[source]

Return a maximum-likelihood estimator (scatter eigenvector + Kummer-ratio kappa solve).

Parameters:: pseudo_count (float | None)
Return type:: WatsonEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: WatsonDataEncoder

class WatsonEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator: scatter eigenvector for the axis, Kummer-ratio solve for kappa.

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Watson scatter statistics.

Return type:: WatsonAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the Watson axis and concentration from weighted scatter.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, float])

Return type:

WatsonDistribution

exception WatsonFitError[source]

Bases: RuntimeError

Raised when Watson moments have no certified finite fit.

exception WatsonSamplingError(accepted, proposed, kappa, dim)[source]

Bases: RuntimeError

Raised when exact Watson rejection sampling exhausts its proposal budget.

Parameters:

accepted (int)
proposed (int)
kappa (float)
dim (int)

Return type:

None

class WishartDistribution(df, scale, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Wishart distribution with df degrees of freedom and scale matrix scale (p, p).

Parameters:

df (float)
scale (ndarray)
name (str | None)
keys (str | None)

density(x)[source]

Return the density at a single (p, p) SPD matrix.

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

Return the log-density at a single (p, p) SPD matrix (-inf if not symmetric or not positive definite).

Mirrors seq_log_density()’s routines exactly rather than merely approximately: uses batched_pd_logdet() (the same eigenvalue-based check) instead of cholesky_logdet() for positive-definiteness/log-determinant, and the same einsum trace contraction instead of trace(A @ B). Near the positive-definiteness boundary a Cholesky factorization and an eigendecomposition can round differently and even disagree on whether a matrix is PD at all, and a full matrix product summed via trace accumulates in a different order than the direct einsum contraction – both previously made this scalar path and the vectorized path diverge (in value, and occasionally in support) on the same input.

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Vectorized log-density for a stack of SPD matrices, shape (N, p, p) (-inf per row that is not symmetric or not positive definite).

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing SPD matrices from this distribution.

Parameters:: seed (int | None)
Return type:: WishartSampler

estimator(pseudo_count=None)[source]

Return a closed-form estimator for the scale at the fixed degrees of freedom df.

Parameters:: pseudo_count (float | None)
Return type:: WishartEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: WishartDataEncoder

class WishartEstimator(dim, df=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form scale estimator (V = mean(X)/df); df=None also fits the degrees of freedom by MLE.

With a fixed df the estimator returns only the closed-form scale (E[X] = df V). With df=None it additionally estimates the degrees of freedom from sum_i w_i log det(X_i) with a bracketed, certified root of the profile score (_solve_wishart_df()).

Parameters:

dim (int)
df (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Wishart sufficient-statistic accumulators.

Return type:: WishartAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the Wishart scale and optionally degrees of freedom.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, float, float])

Return type:

WishartDistribution

exception WishartFitError[source]

Bases: RuntimeError

Raised when a Wishart fit has no valid, certified optimum.

class LKJDistribution(dim, eta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

LKJ distribution over dim x dim correlation matrices with concentration eta > 0.

Parameters:

dim (int)
eta (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at a correlation matrix x.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-density at a dim x dim correlation matrix (-inf if x is the wrong size, not symmetric, does not have a unit diagonal, or is not positive definite).

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log density for dimension-bound encoded LKJ data.

Invalid rows remain -inf regardless of eta, including at eta=1 where direct multiplication by their -inf sentinel would be NaN.

Parameters:: x (Any)
Return type:: ndarray

sampler(seed=None)[source]

Return an onion-method sampler for correlation matrices.

Parameters:: seed (int | None)
Return type:: LKJSampler

estimator(pseudo_count=None)[source]

Return a maximum-likelihood estimator for the concentration eta (dim fixed).

Parameters:: pseudo_count (float | None)
Return type:: LKJEstimator

dist_to_encoder()[source]

Return the data encoder (a correlation matrix is encoded as its log-determinant).

Return type:: LKJDataEncoder

class LKJEstimator(dim, eta_bounds=(0.05, 1.0e4), name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the concentration eta at fixed dimension dim.

Parameters:

dim (int)
eta_bounds (tuple[float, float])
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for LKJ sufficient-statistic accumulators.

Return type:: LKJAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the LKJ concentration from the mean log determinant.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

LKJDistribution

exception LKJFitError[source]

Bases: RuntimeError

Raised when an LKJ concentration fit has no certified solution.

class KentDistribution(gamma, kappa, beta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Kent (FB5) distribution on S^2 with orientation gamma (3x3), concentration and ovalness.

Parameters:

gamma (ndarray)
kappa (float)
beta (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the Kent density at one unit 3-vector.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-density at a unit 3-vector x.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded (n, 3) array of unit vectors.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Declare NumPy/Torch scoring capabilities for Kent log-density kernels.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for (N, 3) unit vectors.

Parameters:

x (Any)
engine (Any)

Return type:

sampler(seed=None)[source]

Return an exact rejection sampler for this Kent distribution.

Parameters:: seed (int | None)
Return type:: KentSampler

estimator(pseudo_count=None)[source]

Return Kent’s moment/ML estimator for orientation, concentration, and ovalness.

Parameters:: pseudo_count (float | None)
Return type:: KentEstimator

dist_to_encoder()[source]

Return the unit-vector encoder used by vectorized methods.

Return type:: KentDataEncoder

class KentEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Kent’s moment estimator for the orientation, with an ML refinement of (kappa, beta).

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Kent sufficient-statistic accumulators.

Return type:: KentAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate orientation, concentration, and ovalness from moment statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray, ndarray])

Return type:

KentDistribution

exception KentFitError[source]

Bases: RuntimeError

Raised when Kent moments have no certified finite fit.

exception KentSamplingError(accepted, proposed, kappa, beta)[source]

Bases: RuntimeError

Raised when Kent rejection sampling exhausts its proposal budget.

Parameters:

accepted (int)
proposed (int)
kappa (float)
beta (float)

class BinghamDistribution(m, z, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Bingham distribution on S^2 with orientation m (3x3) and concentrations z (length 3).

Parameters:

m (ndarray)
z (Sequence[float])
name (str | None)
keys (str | None)

density(x)[source]

Return the Bingham density at one unit 3-vector.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-density at a unit 3-vector x (the same value at x and -x).

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded (n, 3) array of unit vectors.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Declare NumPy/Torch scoring capabilities for Bingham log-density kernels.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for (N, 3) unit vectors.

Parameters:

x (Any)
engine (Any)

Return type:

sampler(seed=None)[source]

Return an exact rejection sampler for this Bingham distribution.

Parameters:: seed (int | None)
Return type:: BinghamSampler

estimator(pseudo_count=None)[source]

Return a maximum-likelihood estimator for Bingham orientation and concentration.

Parameters:: pseudo_count (float | None)
Return type:: BinghamEstimator

dist_to_encoder()[source]

Return the unit-vector encoder used by vectorized methods.

Return type:: BinghamDataEncoder

class BinghamEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood Bingham fit: scatter eigenbasis + concave concentration moment-matching.

Parameters:

name (str | None)
keys (str | None)

estimate(nobs, suff_stat)[source]

Estimate orientation and concentrations from scatter statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray])

Return type:

BinghamDistribution

accumulator_factory()[source]

Return a factory for Bingham sufficient-statistic accumulators.

Return type:: BinghamAccumulatorFactory

exception BinghamFitError[source]

Bases: RuntimeError

Raised when Bingham moments have no certified finite fit.

exception BinghamSamplingError(accepted, proposed, concentrations)[source]

Bases: RuntimeError

Raised when Bingham rejection sampling exhausts its proposal budget.

Parameters:

accepted (int)
proposed (int)
concentrations (ndarray)

class InverseWishartDistribution(df, scale, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Inverse-Wishart distribution with df degrees of freedom and scale matrix scale (p, p).

Parameters:

df (float)
scale (ndarray)
name (str | None)
keys (str | None)

density(x)[source]

Return the density at a single (p, p) SPD matrix.

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

Return the log-density at a single (p, p) SPD matrix (-inf if not symmetric or not positive definite).

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Vectorized log-density for a stack of SPD matrices, shape (N, p, p) (-inf per row that is not symmetric or not positive definite).

np.linalg.inv, like np.linalg.cholesky (see batched_pd_logdet()’s docstring), raises LinAlgError for the WHOLE batch if even one matrix is singular – singular is just the not-positive-definite boundary case, already scored -inf below via is_valid, so its inverse is never actually used. Substitute the identity for invalid rows before inverting so the call always succeeds, mirroring how the scalar log_density() path never calls inv on a matrix it is about to reject.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing SPD matrices from this distribution.

Parameters:: seed (int | None)
Return type:: InverseWishartSampler

estimator(pseudo_count=None)[source]

Return the fixed-df mean-moment estimator when that moment exists.

Parameters:: pseudo_count (float | None)
Return type:: InverseWishartMeanMomentEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: InverseWishartDataEncoder

InverseWishartEstimator: alias of InverseWishartMeanMomentEstimator

class InverseWishartMeanMomentEstimator(dim, df, name=None, keys=None)[source]

Bases: ParameterEstimator

Fixed-df method-of-moments estimator based on the inverse-Wishart mean.

This is not a likelihood MLE. It is defined only for df > p + 1, where E[X] = Psi / (df-p-1) exists.

Parameters:

dim (int)
df (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for estimating the fixed-df scale matrix.

Return type:: InverseWishartAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate scale by the inverse-Wishart mean moment, not likelihood.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, float])

Return type:

InverseWishartDistribution

exception InverseWishartMomentFitError[source]

Bases: RuntimeError

Raised when the inverse-Wishart mean-moment fit is undefined.

class VonMisesFisherEstimator(dim=None, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for the VonMisesFisherDistribution using the Banerjee et al. approximation for kappa.

Parameters:

dim (int | None)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]: Return a factory for von Mises-Fisher accumulators.

estimate(nobs, suff_stat)[source]

Estimate a VonMisesFisherDistribution from sufficient statistics.

The mean direction is the normalized weighted vector sum. The concentration solves A_p(kappa) = rhat using a finite bracket and Brent root certificate. Boundary resultants with rhat=1 have only an infinite-concentration MLE and raise a typed fit error.

Parameters:

nobs (Optional[float]) – Number of observations (unused).
suff_stat (Tuple[float, np.ndarray]) – Tuple of count and weighted vector sum.

Returns:

A fitted distribution carrying convergence and identifiability metadata.

Return type:

VonMisesFisherDistribution

exception VonMisesFisherFitError[source]

Bases: RuntimeError

Raised when vMF sufficient statistics have no finite identifiable fit.

class MultivariateStudentTDistribution(dof, loc, shape, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Multivariate Student’s t distribution with degrees of freedom dof, location mu, and scale Sigma.

Parameters:

dof (float)
loc (Sequence[float] | ndarray)
shape (Sequence[Sequence[float]] | ndarray)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated multivariate Student-t kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for multivariate Student-t distributions.

static backend_log_density_from_params(x, mu, inv_shape, log_const, dof, dim, engine)[source]

Engine-neutral multivariate Student’s t log-density from fitted parameters.

Parameters:

x (Any)
mu (Any)
inv_shape (Any)
log_const (Any)
dof (Any)
dim (Any)
engine (Any)

Return type:

condition(observed)[source]

Return the conditional distribution over the unobserved dimensions given observed.

The conditional of a multivariate Student-t is again a multivariate Student-t. With observed dimensions o (Mahalanobis d_o) and unobserved u:

dof'   = dof + |o|,
mu'    = mu_u + S_uo S_oo^{-1} (x_o - mu_o),
shape' = (dof + d_o)/(dof + |o|) * (S_uu - S_uo S_oo^{-1} S_ou),

i.e. the location shifts like the Gaussian conditional but the scale is inflated by how far the observed coordinates fall in the tails (given=-style conditional sampling). Raises if no dimension is left unobserved.

Parameters:: observed (dict[int, float])
Return type:: MultivariateStudentTDistribution

marginal(keep)[source]

Return the marginal over the dimensions keep: MVT(dof, mu[keep], shape[keep, keep]).

A multivariate Student-t marginal keeps the same degrees of freedom and simply restricts the location and shape to the kept coordinates (order preserved).

Parameters:: keep (Sequence[int])
Return type:: MultivariateStudentTDistribution

density(x)[source]

Return the probability density at a single observation.

Parameters:: x (Sequence[float] | ndarray)
Return type:: float

log_density(x)[source]

Return the log-density at a single observation.

Parameters:: x (Sequence[float] | ndarray)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (ndarray)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for equal-dimensional multivariate Student’s t mixtures.

Parameters:

dists (Sequence[MultivariateStudentTDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of multivariate Student’s t component log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: MultivariateStudentTSampler

estimator(pseudo_count=None)[source]

Return an EM estimator that keeps dof fixed at this distribution’s value.

Parameters:: pseudo_count (float | None)
Return type:: MultivariateStudentTEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: MultivariateStudentTDataEncoder

class MultivariateStudentTEstimator(dof=5.0, dim=None, pseudo_count=None, min_ridge=_MIN_RIDGE, name=None, keys=None)[source]

Bases: ParameterEstimator

Fixed-dof EM estimator for the multivariate Student’s t location and scale matrix.

The scale matrix is formed from shift-anchored statistics whenever the accumulated sufficient statistics carry that payload (see MultivariateStudentTAccumulator), which makes the fit SHIFT-EQUIVARIANT: estimating on x + c returns loc + c with the scale matrix unchanged, for any constant c the data can carry – epoch seconds (~1.7e9) and 2**31 included. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones that arrived already reduced from an engine kernel or an older serialization – the historical raw path is used bit-identically, and estimate warns rather than returning a scale matrix it cannot stand behind.

Residual limit, and it is representational rather than algorithmic. One M-step is shift-equivariant to ~1e-15, but a full EM run is not exactly so: the latent reweighting u_i = (nu + p)/(nu + delta_i) is a function of x_i - mu, and mu is a float64 at the data’s own magnitude, so it can only be placed on that grid – 1.2e-4 apart at offset 1e12. Snapping the un-shifted fit’s mu onto exactly that grid reproduces the shifted fit to 3e-14, which is what identifies the mechanism. The effect on the fitted scale matrix is bounded by roughly ulp(abs(mu)) / spread per iteration: 4e-8 at epoch seconds, 1e-7 at 2**31, 7e-5 at 1e12. Every consumer of a fitted location faces the same granularity, so there is no more precise answer to return; subtract a constant origin before fitting if a tighter one is needed.

Parameters:

dof (float)
dim (int | None)
pseudo_count (float | None)
min_ridge (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for fixed-dof Student-t EM statistics.

Return type:: MultivariateStudentTAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location and scale from EM reweighted statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, ndarray | None, ndarray | None])

Return type:

MultivariateStudentTDistribution

class WeightedDistribution(dist, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Distribution wrapper that attaches observation weights to a base distribution.

Parameters:

dist (SequenceEncodableProbabilityDistribution) – Base distribution for the observed values.
name (Optional[str]) – Optional distribution name.
keys (str | None)

dist

Base distribution for the observed values.

Type:: SequenceEncodableProbabilityDistribution

name

Optional distribution name.

Type:: Optional[str]

compute_capabilities()[source]: Delegate generated-compute support to the wrapped value distribution.

compute_declaration()[source]: Return the generated-compute declaration for the weighted wrapper.

density(x)[source]

Density of the base distribution at a weighted observation’s value.

Parameters:: x (D) – Observation value (weight excluded).
Returns:: Density of the base distribution at x.
Return type:: float

log_density(x)[source]

Log-density of the base distribution at a weighted observation’s value.

The observation weight does not enter the likelihood, so this is simply the base distribution’s log-density evaluated on the value.

Parameters:: x (D) – Observation value (weight excluded).
Returns:: Log-density of the base distribution at x.
Return type:: float

seq_log_density(x)[source]

Vectorized log-density of the base distribution on encoded values.

Parameters:: x (Tuple[E, np.ndarray]) – Sequence encoded values and weights from WeightedDataEncoder.
Returns:: Numpy array of base-distribution log-densities.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density delegated to the value distribution.

Parameters:

x (tuple[E, ndarray])
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child parameters for homogeneous weighted-wrapper mixtures.

Parameters:

dists (Sequence[WeightedDistribution])
engine (Any)

Return type:

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of child log densities, ignoring attached weights.

Parameters:

x (tuple[E, ndarray])
params (dict[str, Any])
engine (Any)

Return type:

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Decline resident accumulation until its nested effective-count layout is representable.

Parameters:

x (tuple[E, ndarray])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

dist_to_encoder()[source]

Returns a WeightedDataEncoder for encoding sequences of (value, weight) observations.

Return type:: WeightedDataEncoder

to_fisher(**kwargs)[source]: Fisher view for the weighted wrapper.

estimator(pseudo_count=None)[source]

Create a WeightedEstimator wrapping the base distribution’s estimator.

Parameters:: pseudo_count (Optional[float]) – Passed through to the base distribution’s estimator.
Returns:: WeightedEstimator object.
Return type:: WeightedEstimator

sampler(seed=None)[source]

Create a WeightedSampler producing (value, weight) pairs.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: WeightedSampler object.
Return type:: WeightedSampler

enumerator()[source]

Enumerate canonical (value, 1.0) observations in child-probability order.

Return type:: DistributionEnumerator

support_size()[source]

Return the child support size; attached weight is metadata, not a support coordinate.

Return type:: int | None

class WeightedEstimator(estimator, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for a weighted distribution from weighted observations.

Parameters:

estimator (ParameterEstimator) – Estimator for the base distribution.
name (Optional[str]) – Optional name assigned to the estimated distribution.
keys (str | None)

estimator

Estimator for the base distribution.

Type:: ParameterEstimator

name

Optional name assigned to the estimated distribution.

Type:: Optional[str]

accumulator_factory()[source]

Returns a WeightedAccumulatorFactory wrapping the base estimator’s factory.

Return type:: WeightedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a WeightedDistribution from the base distribution’s sufficient statistics.

Parameters:

nobs (Optional[float]) – Weighted number of observations.
suff_stat (SS) – Sufficient statistics of the base accumulator.

Returns:

WeightedDistribution wrapping the estimated base distribution.

Return type:

WeightedDistribution

resident_accumulation_supported()[source]

Use the host wrapper accumulator so effective-weight metadata cannot be dropped.

Return type:: bool

class WeightedObservation(value, weight)[source]

Bases: NamedTuple

A child value plus non-random, non-negative estimation-weight metadata.

Parameters:

value (Any)
weight (float)

value: Any: Alias for field number 0

weight: float: Alias for field number 1

class WeightedStatistics(child, effective_weight)[source]

Bases: NamedTuple

Child sufficient statistics plus their effective attached-times-external weight.

Parameters:

child (Any)
effective_weight (float)

child: Any: Alias for field number 0

effective_weight: float: Alias for field number 1

class WeightedEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate one canonical metadata representation for every child support value.

Parameters:: dist (WeightedDistribution)

class ErdosRenyiGraphDistribution(p, directed=False, self_loops=False, num_nodes=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Independent Bernoulli distribution over binary graph edges.

Parameters:

p (float)
directed (bool)
self_loops (bool)
num_nodes (int | None)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Return backend capabilities for Bernoulli graph scoring.

classmethod compute_declaration()[source]: Return the structured declaration for the Erdos-Renyi graph family.

classmethod from_model(model)[source]

Create a distribution wrapper from an Erdos-Renyi model.

Parameters:: model (Any)
Return type:: ErdosRenyiGraphDistribution

to_model()[source]

Convert this distribution to the corresponding random-graph model.

Return type:: Any

density(x)[source]

Return the probability mass of one graph observation.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the Bernoulli edge log probability of one graph.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Score a batch of graph observations.

Parameters:: x (Sequence[GraphObservation])
Return type:: np.ndarray

backend_seq_log_density(x, engine)[source]

Engine-routed Bernoulli edge log-likelihood.

Per-graph edge opportunities/successes are extracted host-side (the graphs are ragged object data), but the Bernoulli reduction runs on the active engine, so the model’s scoring math is engine-native (and differentiable in p on torch).

Parameters:

x (Sequence[GraphObservation])
engine (Any)

Return type:

Any

edge_probability(i=None, j=None, context=None)[source]

Return the common edge probability p.

Parameters:

i (int | None)
j (int | None)
context (Any | None)

Return type:

edge_marginals(num_nodes=None)[source]

Return the matrix of marginal edge probabilities for num_nodes.

Parameters:: num_nodes (int | None)
Return type:: ndarray

posterior(x)[source]

Return edge opportunities, observed edge count, and fitted probability for x.

Parameters:: x (Any)
Return type:: dict[str, float]

sampler(seed=None)[source]

Return a sampler for Erdos-Renyi graph observations.

Parameters:: seed (int | None)
Return type:: ErdosRenyiGraphSampler

enumerator()[source]

Enumerate binary graphs in descending probability order (requires num_nodes).

The edges are independent Bernoulli(p) over the free positions _edge_indices(n, directed, self_loops), so the graph distribution is a product of edge factors and enumerates by best-first over the per-edge supports – exactly like a composite of Bernoullis, with the combined value assembled into an adjacency matrix (mirrored for the undirected case). Each graph carries its exact log_density. num_nodes must be set so the edge set is finite.

Return type:: DistributionEnumerator

estimator(pseudo_count=None)[source]

Return the edge-count estimator for this graph family.

Parameters:: pseudo_count (float | None)
Return type:: ErdosRenyiGraphEstimator

dist_to_encoder()[source]

Return the graph encoder used by vectorized scoring and fitting.

Return type:: GraphDataEncoder

class ErdosRenyiGraphEstimator(directed=False, self_loops=False, pseudo_count=None, prior_p=0.5, num_nodes=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate an Erdos-Renyi graph distribution from edge counts.

Parameters:

directed (bool)
self_loops (bool)
pseudo_count (float | None)
prior_p (float)
num_nodes (int | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: ErdosRenyiGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the Bernoulli edge probability from edge-count statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float])

Return type:

ErdosRenyiGraphDistribution

class TemporalGraphGrammarDistribution(motif_weights, edge_rate=1.0, node_rate=0.0, remove_weights=None, edge_remove_rate=0.0, motif=None, directed=False, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Distribution over dynamic graphs (sequences of adjacency snapshots) under a motif-edit grammar.

Parameters:

motif_weights (Sequence[float])
edge_rate (float)
node_rate (float)
remove_weights (Sequence[float] | None)
edge_remove_rate (float)
motif (CommonNeighbourMotif | None)
directed (bool)
name (str | None)

transition_components(prev, cur)[source]

The PARAMETER-INDEPENDENT decomposition of a transition: (new_nodes, add_bins, add_cand, rem_bins, rem_cand, valid). Depends only on the graph pair and the motif, NOT on the grammar’s weights/rates – so K regimes sharing a motif can compute the (expensive A@A) decomposition ONCE and score it K times via score_components(). valid is False for an impossible node removal.

Parameters:

prev (Any)
cur (Any)

Return type:

tuple

score_components(components)[source]

Score a precomputed transition_components() decomposition under THIS grammar’s parameters.

Parameters:: components (tuple)
Return type:: float

log_density(x)[source]

Log-density of one dynamic graph: the sum of transition log-densities over the snapshot chain.

x is a sequence of binary adjacency matrices – dense ndarray or scipy.sparse (large graphs). The initial graph is taken as given (its marginal is not modelled, matching how the static grammars treat their start symbol).

Parameters:: x (Sequence[ndarray])
Return type:: float

seq_encode(x)[source]

Return dynamic graph sequences unchanged for sequence scoring.

Parameters:: x (Sequence[Sequence[ndarray]])
Return type:: Sequence[Sequence[ndarray]]

seq_log_density(x)[source]

Score a batch of dynamic graph sequences.

Parameters:: x (Sequence[Sequence[ndarray]])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for dynamic graph sequences.

Parameters:: seed (int | None)
Return type:: TemporalGraphGrammarSampler

estimator(pseudo_count=None)[source]

Return the closed-form estimator for this motif grammar.

Parameters:: pseudo_count (float | None)
Return type:: TemporalGraphGrammarEstimator

dist_to_encoder()[source]

Return the pass-through data encoder for graph sequences.

Return type:: TemporalGraphGrammarDataEncoder

class TemporalGraphGrammarEstimator(motif=None, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

Learn the motif distribution (rule weights) + edge/node rates from observed dynamic graphs.

Parameters:

motif (CommonNeighbourMotif | None)
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return the accumulator factory used by the estimator.

Return type:: TemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate grammar weights and rates from sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (TemporalGraphGrammarStatistics)

Return type:

TemporalGraphGrammarDistribution

class CommonNeighbourMotif(bins=(0, 1, 2, 3), directed=False)[source]

Bases: object

A motif rule keyed by how many common neighbours a candidate edge has (triangles it would close).

bins is an increasing list of thresholds; bin b covers common-neighbour counts in [bins[b], bins[b+1]) with the last bin open-ended. The default [0, 1, 2, 3] gives the interpretable {bridge, closes-1, closes-2, closes-3+} partition. A non-edge falls in exactly one bin, so the motifs partition every candidate edge.

Parameters:

bins (Sequence[int])
directed (bool)

property num_motifs: int: Number of mutually exclusive motif bins.

assign(adj, on_edges=False)[source]

Motif bin of every candidate pair (and -1 on non-candidates / diagonal).

The common-neighbour count of a pair (i, j) is (A @ A)[i, j] – for a non-edge, how many triangles adding it would CLOSE; for an existing edge, how many triangles it is PART of. Binning by self.bins gives its motif. With on_edges=False the candidates are the non-edges (addition); with on_edges=True they are the existing edges (removal). Non-candidates and the diagonal -> -1.

Parameters:

adj (ndarray)
on_edges (bool)

Return type:

counts_and_binner(adj, on_edges)[source]

Return (candidate_counts[M], lookup(i, j) -> motif index) WITHOUT forming the n*n bin matrix.

Sparse-scalable: only the existing edges (O(m)) and the non-edges that close a triangle (O(wedges) = A @ A’s nonzeros) are ever enumerated; the bridge count (cn=0 non-edges) is the analytic remainder pairs - edges - wedge_non_edges. The lookup reads (A @ A)[i, j] for the handful of observed edges. (For graphs with mega-hubs the wedge set itself is large – the documented limit.)

Parameters:

adj (Any)
on_edges (bool)

Return type:

tuple

class LabeledTemporalGraphGrammarDistribution(structure, node_dist=None, edge_dist=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A dynamic graph whose nodes and edges carry attributes.

Composes a structural TemporalGraphGrammarDistribution (the topology over time) with two ordinary mixle distributions: node_dist over per-node attribute records (location, name, age, … – typically a CompositeDistribution of leaves or a mixture) and edge_dist over per-edge attribute records (communication counts, channel, weight, …). An observation is (snapshots, node_features, edge_features): the adjacency chain, one attribute record per final node index, and one edge-record group per transition containing one record per added edge in canonical _edge_diff order. The likelihood factorises – structure x node attributes x edge attributes – so the attribute models are fit (and scored) with the full mixle distribution machinery (mixtures, fusion, all leaf families).

Parameters:

structure (TemporalGraphGrammarDistribution)
node_dist (SequenceEncodableProbabilityDistribution | None)
edge_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)

log_density(x)[source]

Score one attributed dynamic graph observation.

Parameters:: x (tuple)
Return type:: float

seq_encode(x)[source]

Validate and encode a batch of event-aligned attributed observations.

Parameters:: x (Sequence[tuple])
Return type:: Sequence[tuple]

seq_log_density(x)[source]

Score a batch of attributed dynamic graph observations.

Parameters:: x (Sequence[tuple])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for attributed dynamic graph observations.

Parameters:: seed (int | None)
Return type:: LabeledTemporalGraphGrammarSampler

estimator(**kw)[source]

Return the estimator for structure, node attributes, and edge attributes.

Parameters:: kw (Any)
Return type:: LabeledTemporalGraphGrammarEstimator

dist_to_encoder()[source]

Return the event-aligned attributed graph encoder.

Return type:: LabeledTemporalGraphGrammarDataEncoder

class LabeledTemporalGraphGrammarEstimator(structure_estimator, node_estimator=None, edge_estimator=None, *, structure, node_encoder=None, edge_encoder=None, name=None)[source]

Bases: ParameterEstimator

Estimator for attributed temporal graph grammars.

Parameters:

structure_estimator (Any)
node_estimator (Any)
edge_estimator (Any)
structure (TemporalGraphGrammarDistribution)
node_encoder (Any)
edge_encoder (Any)
name (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: LabeledTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate structure and attribute distributions from sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (LabeledTemporalGraphGrammarStatistics)

Return type:

LabeledTemporalGraphGrammarDistribution

class HomophilyTemporalGraphGrammarDistribution(rate, type_weights, node_rate=0.0, motif=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A growth grammar whose edge formation depends on node ATTRIBUTES, not just structure (homophily).

Each node carries a categorical type (community / location-bucket / …). The per-step number of new edges of motif m between an (unordered) type pair (a, b) is Poisson(rate[m, a, b]), placed uniformly among the candidate non-edges of that motif and type pair. Making rate[m, a, a] larger than rate[m, a, b] is homophily (“similar nodes connect more”); the rate tensor is the learnable coupling between attributes and topology. New nodes draw their type from type_weights.

Observation: (snapshots, node_types) – the adjacency chain plus an int type per node. Exact and closed-form: the rate tensor is just edge counts per (motif, type-pair) over steps, and the type distribution is node-type counts. (Phase: growth-only, dense; add+remove and sparse compose with the machinery above and are the natural extensions.)

Parameters:

rate (np.ndarray)
type_weights (Sequence[float])
node_rate (float)
motif (CommonNeighbourMotif | None)
name (str | None)

log_density(x)[source]

Score one homophily dynamic graph observation.

Parameters:: x (tuple)
Return type:: float

seq_encode(x)[source]

Validate and encode homophily observations.

Parameters:: x (Sequence[tuple])
Return type:: Sequence[tuple]

seq_log_density(x)[source]

Score a batch of homophily dynamic graph observations.

Parameters:: x (Sequence[tuple])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for homophily dynamic graph observations.

Parameters:: seed (int | None)
Return type:: HomophilyTemporalGraphGrammarSampler

estimator(pseudo_count=None)[source]

Return the estimator for homophily rates and node-type weights.

Parameters:: pseudo_count (float | None)
Return type:: HomophilyTemporalGraphGrammarEstimator

dist_to_encoder()[source]

Return the validated homophily encoder.

Return type:: HomophilyTemporalGraphGrammarDataEncoder

class HomophilyTemporalGraphGrammarEstimator(M, K, motif=None, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

Estimator for homophily temporal graph grammars.

Parameters:

M (int)
K (int)
motif (CommonNeighbourMotif | None)
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: HomophilyTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate homophily rates, type weights, and node rate from sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (HomophilyTemporalGraphGrammarStatistics)

Return type:

HomophilyTemporalGraphGrammarDistribution

class ChurningTemporalGraphGrammarDistribution(edit_grammar, node_remove_rate=0.0, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Dynamic graph where nodes both JOIN and LEAVE, tracked by stable identity.

Each snapshot is (adjacency, node_ids) – node_ids[i] is the persistent identity of row i. A transition first removes nodes (those whose id disappears; count ~ Poisson(node_remove_rate), chosen uniformly, their edges vanishing with them), then runs the wrapped edit grammar on the surviving subgraph (which also appends new nodes + adds/removes edges). So churn is a thin wrapper: identity alignment + a node-removal Poisson term on top of all the existing motif/edge machinery. Scoring and fitting accept dense or scipy.sparse adjacencies (the id alignment slices either); the sampler is dense.

Parameters:

edit_grammar (TemporalGraphGrammarDistribution)
node_remove_rate (float)
name (str | None)

log_density(x)[source]

Score one identity-tracked churning graph sequence.

Parameters:: x (Sequence[tuple])
Return type:: float

seq_encode(x)[source]

Validate and encode identity-tracked graph observations.

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

Score a batch of churning graph observations.

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for churning graph observations.

Parameters:: seed (int | None)
Return type:: ChurningTemporalGraphGrammarSampler

estimator(pseudo_count=None)[source]

Return the estimator for the wrapped edit grammar and node churn rate.

Parameters:: pseudo_count (float | None)
Return type:: ChurningTemporalGraphGrammarEstimator

dist_to_encoder()[source]

Return the validated identity-tracked graph encoder.

Return type:: ChurningTemporalGraphGrammarDataEncoder

class ChurningTemporalGraphGrammarEstimator(edit_estimator, edit_grammar=None, name=None)[source]

Bases: ParameterEstimator

Estimator for identity-tracked churning temporal graph grammars.

Parameters:

edit_estimator (Any)
edit_grammar (TemporalGraphGrammarDistribution | None)
name (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: ChurningTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the wrapped edit grammar and node-removal rate.

Parameters:

nobs (float | None)
suff_stat (ChurningTemporalGraphGrammarStatistics)

Return type:

ChurningTemporalGraphGrammarDistribution

class LatentTemporalGraphGrammarDistribution(states, initial_probs=None, transition_matrix=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A dynamic graph whose edit grammar is governed by a hidden, time-evolving REGIME.

A latent state z_t (a Markov chain: initial_probs pi, transition_matrix A) selects which of K edit grammars governs transition t. So the graph can switch regimes over time – e.g. a bursty growth / densification phase, then a fragmentation / decay phase – dynamics a single grammar cannot express. The sequence likelihood marginalises the regime path by the forward algorithm; emissions are the per- transition edit log-densities of each regime’s grammar, so this is an HMM whose emission models are the graph-edit grammars and EM reuses each grammar’s weighted accumulator for the M-step.

Observation = a plain list of adjacency snapshots (same as the base grammar) – the regime is latent. decode returns the most likely regime active at each transition (Viterbi).

Parameters:

states (Sequence[TemporalGraphGrammarDistribution])
initial_probs (Sequence[float] | None)
transition_matrix (Sequence[Sequence[float]] | None)
name (str | None)

log_density(x)[source]

Score one dynamic graph sequence with regimes marginalized out.

Parameters:: x (Sequence[Any])
Return type:: float

decode(x)[source]

Viterbi: the most likely regime governing each transition.

Parameters:: x (Sequence[Any])
Return type:: list

seq_encode(x)[source]

Validate and encode latent-regime graph observations.

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

Score a batch of latent-regime graph observations.

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for latent-regime graph sequences.

Parameters:: seed (int | None)
Return type:: LatentTemporalGraphGrammarSampler

estimator(pseudo_count=None)[source]

Return the Baum-Welch estimator for the latent-regime grammar.

Parameters:: pseudo_count (float | None)
Return type:: LatentTemporalGraphGrammarEstimator

dist_to_encoder()[source]

Return the validated graph encoder.

Return type:: TemporalGraphGrammarDataEncoder

class LatentTemporalGraphGrammarEstimator(state_estimators, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

EM (Baum-Welch) for the regime-switching grammar: forward-backward E-step, per-regime weighted M-step.

Parameters:

state_estimators (Sequence[Any])
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: LatentTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate regime priors, transitions, and state grammars from EM statistics.

Parameters:

nobs (float | None)
suff_stat (LatentTemporalGraphGrammarStatistics)

Return type:

LatentTemporalGraphGrammarDistribution

class LatentAttributedTemporalGraphGrammarDistribution(structures, node_dists=None, edge_dists=None, initial_probs=None, transition_matrix=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A regime-switching dynamic graph where the hidden regime drives the STRUCTURE and the ATTRIBUTES.

Each of K regimes carries a full edit grammar plus (optionally) a node-attribute distribution and an edge-attribute distribution, all switched by one latent Markov state z_t. So a single regime change can densify the topology AND spike communication volume / shift node properties together – e.g. an “active” phase with bursty triadic closure and high message counts, vs a “quiet” phase. The per-transition emission under regime k is structure_k(transition) + node_attrs_k(nodes added this step) + edge_attrs_k(edges added this step); the sequence likelihood marginalises the regime path by the forward algorithm and EM does forward-backward + a per-regime weighted M-step over each piece.

Observation = (snapshots, node_features, edge_features) where node_features[t] / edge_features[t] are the attribute records of the nodes / edges that appear at transition t (lists, length = #transitions).

Parameters:

structures (Sequence[TemporalGraphGrammarDistribution])
node_dists (Sequence[Any] | None)
edge_dists (Sequence[Any] | None)
initial_probs (Sequence[float] | None)
transition_matrix (Sequence[Sequence[float]] | None)
name (str | None)

log_density(x)[source]

Score one attributed graph sequence with regimes marginalized out.

Parameters:: x (tuple)
Return type:: float

decode(x)[source]

Viterbi: the most likely regime governing each transition (jointly explaining structure+attrs).

Parameters:: x (tuple)
Return type:: list

seq_encode(x)[source]

Validate and encode attributed latent-regime observations.

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

Score a batch of attributed latent-regime observations.

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for attributed latent-regime graph sequences.

Parameters:: seed (int | None)
Return type:: LatentAttributedTemporalGraphGrammarSampler

estimator(pseudo_count=None)[source]

Return the EM estimator for structure and attribute regime models.

Parameters:: pseudo_count (float | None)
Return type:: LatentAttributedTemporalGraphGrammarEstimator

dist_to_encoder()[source]

Return the event-aligned latent attributed encoder.

Return type:: LatentAttributedTemporalGraphGrammarDataEncoder

class LatentAttributedTemporalGraphGrammarEstimator(structure_estimators, node_estimators=None, edge_estimators=None, *, structures, node_encoders=None, edge_encoders=None, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

Parameters:

structure_estimators (Sequence[Any])
node_estimators (Sequence[Any] | None)
edge_estimators (Sequence[Any] | None)
structures (Sequence[TemporalGraphGrammarDistribution])
node_encoders (Sequence[Any] | None)
edge_encoders (Sequence[Any] | None)
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: LatentAttributedTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (LatentAttributedTemporalGraphGrammarStatistics)

Return type:

LatentAttributedTemporalGraphGrammarDistribution

class LatentChurningTemporalGraphGrammarDistribution(states, node_remove_rates=None, initial_probs=None, transition_matrix=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A regime-switching dynamic graph where the hidden regime also governs NODE TURNOVER.

Combines the latent regime HMM with identity-tracked node churn: each of K regimes carries a full edit grammar AND its own node-removal rate, so the graph can switch between e.g. a stable phase (slow turnover, triadic growth) and a churn phase (fast member departure, fragmentation). Each snapshot is (adjacency, node_ids); per transition the active regime first removes nodes (those whose id disappears) then edits the surviving subgraph, and the per-transition emission under regime k is node_removal_k(#removed) + grammar_k(edit on the aligned surviving subgraph). The sequence likelihood marginalises the regime path by the forward algorithm; EM does forward-backward then a per-regime weighted M-step over both the grammar and the turnover rate. decode recovers the active regime.

Observation = (snapshots, node_ids) where node_ids is a list of per-snapshot id arrays. Dense.

Parameters:

states (Sequence[TemporalGraphGrammarDistribution])
node_remove_rates (Sequence[float] | None)
initial_probs (Sequence[float] | None)
transition_matrix (Sequence[Sequence[float]] | None)
name (str | None)

log_density(x)[source]

Score one identity-tracked sequence with regimes marginalized out.

Parameters:: x (tuple)
Return type:: float

decode(x)[source]

Return the most likely churn/edit regime for each transition.

Parameters:: x (tuple)
Return type:: list

seq_encode(x)[source]

Validate and encode latent churning observations.

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

Score a batch of latent churning graph observations.

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for latent churning graph sequences.

Parameters:: seed (int | None)
Return type:: LatentChurningTemporalGraphGrammarSampler

estimator(pseudo_count=None)[source]

Return the EM estimator for regime-specific edit grammars and churn rates.

Parameters:: pseudo_count (float | None)
Return type:: LatentChurningTemporalGraphGrammarEstimator

dist_to_encoder()[source]

Return the validated identity-tracked graph encoder.

Return type:: ChurningTemporalGraphGrammarDataEncoder

class LatentChurningTemporalGraphGrammarEstimator(state_estimators, *, states=None, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

Parameters:

state_estimators (Sequence[Any])
states (Sequence[TemporalGraphGrammarDistribution] | None)
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:: LatentChurningTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (LatentChurningTemporalGraphGrammarStatistics)

Return type:

LatentChurningTemporalGraphGrammarDistribution

class StochasticBlockGraphDistribution(block_probs, block_assignments=None, block_prior=None, directed=False, self_loops=False, include_assignment_prior=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Bernoulli stochastic block graph distribution.

The distribution can be used conditionally on observed block assignments, or as a population model that samples assignments from block_prior for new graphs. Exact marginal likelihood over unknown assignments is intentionally not implied.

Parameters:

block_probs (Any)
block_assignments (Any | None)
block_prior (Any | None)
directed (bool)
self_loops (bool)
include_assignment_prior (bool | None)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Return backend capabilities for block-structured Bernoulli graph scoring.

classmethod from_model(model, block_prior=None, include_assignment_prior=False)[source]

Create a distribution wrapper from a random-graph SBM model.

Parameters:

model (Any)
block_prior (Any | None)
include_assignment_prior (bool)

Return type:

StochasticBlockGraphDistribution

to_model()[source]

Convert this distribution to the corresponding random-graph model.

Return type:: Any

density(x)[source]

Return the probability mass of one graph observation.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the conditional block-model log probability of one graph.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Score a batch of graph observations.

Parameters:: x (Sequence[GraphObservation])
Return type:: np.ndarray

backend_seq_log_density(x, engine)[source]

Engine-routed block-structured Bernoulli edge log-likelihood.

Each graph’s edges are flattened host-side into per-edge (value, block-pair probability) arrays with a graph-segment id; the Bernoulli terms and the segment reduction run on the active engine (differentiable in block_probs on torch). The optional assignment prior is added per graph.

Parameters:

x (Sequence[GraphObservation])
engine (Any)

Return type:

Any

link_probability(i, j, block_assignments=None)[source]

Return the marginal or assignment-conditional edge probability for node pair (i, j).

Parameters:

i (int)
j (int)
block_assignments (Any | None)

Return type:

edge_marginals(block_assignments=None, num_nodes=None)[source]

Return the matrix of edge probabilities under fixed or prior-predictive assignments.

Parameters:

block_assignments (Any | None)
num_nodes (int | None)

Return type:

block_marginals(x=None)[source]

Return empirical block proportions for x or the model block prior.

Parameters:: x (Any)
Return type:: ndarray

posterior(x)[source]

Return block counts, block proportions, and edge marginals for an observed graph.

Parameters:: x (Any)
Return type:: dict[str, Any]

sampler(seed=None)[source]

Return a sampler for SBM graph observations.

Parameters:: seed (int | None)
Return type:: StochasticBlockGraphSampler

enumerator()[source]

Enumerate binary graphs in descending probability order, for FIXED block assignments.

With the node block assignments fixed (block_assignments set on the distribution), each edge (i, j) is an independent Bernoulli with its own probability block_probs[a_i, a_j], so the graph distribution is a product of edge factors – enumerated by best-first over the per-edge supports and assembled into an adjacency matrix (mirrored when undirected).

Marginalizing over UNKNOWN assignments is intentionally not modeled by this family, so enumeration requires fixed assignments; otherwise EnumerationError.

Return type:: DistributionEnumerator

estimator(pseudo_count=None)[source]

Return an estimator for observed-assignment SBM fitting.

Parameters:: pseudo_count (float | None)
Return type:: StochasticBlockGraphEstimator

dist_to_encoder()[source]

Return the graph encoder used by vectorized scoring and fitting.

Return type:: GraphDataEncoder

class StochasticBlockGraphEstimator(num_blocks=None, block_assignments=None, directed=False, self_loops=False, pseudo_count=None, prior_p=0.5, block_prior=None, estimate_block_prior=True, include_assignment_prior=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate an SBM from graphs with observed block assignments.

Parameters:

num_blocks (int | None)
block_assignments (Any | None)
directed (bool)
self_loops (bool)
pseudo_count (float | None)
prior_p (float)
block_prior (Any | None)
estimate_block_prior (bool)
include_assignment_prior (bool | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: StochasticBlockGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate block probabilities and the block prior from sufficient statistics.

Parameters:

nobs (float | None)
suff_stat (StochasticBlockGraphStatistics)

Return type:

StochasticBlockGraphDistribution

class StochasticBlockGraphStatistics(schema_version, successes, totals, block_counts, total_nodes, num_graphs, directed, self_loops)[source]

Bases: NamedTuple

Versioned, configuration-bound sufficient statistics for an SBM.

Parameters:

schema_version (int)
successes (ndarray)
totals (ndarray)
block_counts (ndarray)
total_nodes (float)
num_graphs (float)
directed (bool)
self_loops (bool)

schema_version: int: Alias for field number 0

successes: ndarray: Alias for field number 1

totals: ndarray: Alias for field number 2

block_counts: ndarray: Alias for field number 3

total_nodes: float: Alias for field number 4

num_graphs: float: Alias for field number 5

directed: bool: Alias for field number 6

self_loops: bool: Alias for field number 7

class LatentAPIEntry(name, source, status, lazy=True)[source]

Bases: object

One immutable entry in the reviewed latent-package export manifest.

Parameters:

name (str)
source (str)
status (Literal['stable', 'provisional'])
lazy (bool)

latent_api_manifest()[source]

Return the immutable, ordered latent-package export manifest.

Return type:: tuple[LatentAPIEntry, …]

class EffectiveSampleReceipt(declared_mass, assigned_mass, unassigned_mass, allows_unassigned, schema_version=1, contract='mixle.latent_effective_sample/v1')[source]

Bases: object

Validated relationship between declared and assigned effective mass.

Parameters:

declared_mass (float | None)
assigned_mass (float)
unassigned_mass (float)
allows_unassigned (bool)
schema_version (int)
contract (str)

validated_positive_integer(value, label)[source]

Return a positive exact non-boolean integer.

Parameters:

value (Any)
label (str)

Return type:

validated_observation_weight(value, label='observation weight')[source]

Return one finite non-negative, non-boolean observation weight.

Parameters:

value (Any)
label (str)

Return type:

validated_observation_weights(values, rows, label='observation weights')[source]

Return an owned finite non-negative weight vector with exact row geometry.

Parameters:

values (Any)
rows (int)
label (str)

Return type:

validated_count_array(values, shape, label='sufficient-statistic counts')[source]

Return an owned finite non-negative count array with exact geometry.

Parameters:

values (Any)
shape (tuple[int, ...])
label (str)

Return type:

validated_statistic_tuple(values, arity, label)[source]

Return a statistic tuple only when its public schema arity is exact.

Parameters:

values (Any)
arity (int)
label (str)

Return type:

tuple[Any, …]

validate_effective_sample_mass(declared_mass, assigned_mass, *, label, allow_unassigned=False)[source]

Validate declared outer mass against mass assigned to latent children.

declared_mass=None means the caller did not provide outer-mass metadata. Otherwise exact agreement is required, except that families whose documented impossible-evidence policy assigns zero responsibility may set allow_unassigned=True. Assigned mass may never exceed declared mass.

Parameters:

declared_mass (Any)
assigned_mass (Any)
label (str)
allow_unassigned (bool)

Return type:

EffectiveSampleReceipt

validated_weighted_responsibilities(values, weights, components, *, label, allow_unassigned=False)[source]

Validate an owned (rows, components) matrix of assigned posterior mass.

Parameters:

values (Any)
weights (Any)
components (int)
label (str)
allow_unassigned (bool)

Return type:

class GatedMixtureStatistics(component_statistics, covariates, responsibilities, buffer_receipt, component_counts, schema_version=1)[source]

Bases: Sequence[Any]

Versioned gated-mixture statistics with backward four-slot iteration.

Parameters:

component_statistics (tuple[Any, ...])
covariates (ndarray)
responsibilities (ndarray)
buffer_receipt (GateBufferReceipt)
component_counts (ndarray)
schema_version (int)

class GaussianMixtureDistribution(mu, sig2, w=MISSING, name=None, weights=MISSING)[source]

Bases: MixtureDistribution

Finite mixture of full-covariance multivariate Gaussian components.

The constructor packs each (mu[k], sig2[k]) pair into a MultivariateGaussianDistribution. Density, posterior responsibility, and vectorized scoring behavior are inherited from MixtureDistribution.

Parameters:

mu (Sequence[Sequence[float]] | ndarray) – Component means with shape (K, d).
sig2 (Sequence[Any] | ndarray) – Component covariance matrices with shape (K, d, d) or diagonal variances with shape (K, d).
w (Sequence[float] | ndarray) – Mixture weights with length K.
name (str | None) – Optional diagnostic name.
weights (Sequence[float] | ndarray) – Alias for w.

mu: Component means as a (K, d) NumPy array.

sig2: Component covariance matrices as a (K, d, d) NumPy array.

dim: Observation dimension.

density_semantics()[source]: Return exact-or-approximate density semantics joined from Gaussian components.

sampler(seed=None)[source]

Return a sampler that draws vectors from this Gaussian mixture.

Parameters:: seed (int | None) – Optional seed for reproducible component and Gaussian draws.
Returns:: GaussianMixtureSampler bound to this distribution.
Return type:: GaussianMixtureSampler

estimator(pseudo_count=None)[source]

Return an estimator with matching Gaussian component structure.

Parameters:: pseudo_count (float | None) – Optional smoothing mass for mixture weights.
Returns:: GaussianMixtureEstimator suitable for fitting length-d vectors.
Return type:: GaussianMixtureEstimator

dist_to_encoder()[source]

Return the Gaussian mixture encoder for iid vector observations.

Return type:: GaussianMixtureDataEncoder

class GaussianMixtureEstimator(estimators, name=None, conj_prior_params=None, suff_stat=None, pseudo_count=None, keys=(None, None), robust=False, init=None)[source]

Bases: MixtureEstimator

EM estimator for a multivariate Gaussian mixture.

The weight M-step and robustness options are inherited from MixtureEstimator. The specialization repacks fitted Gaussian components into (mu, sig2, w) arrays for a GaussianMixtureDistribution.

Parameters:

estimators (Sequence[ParameterEstimator]) – Component estimators whose fitted components carry a mean vector and a covariance (mu and covar) – typically MultivariateGaussianEstimator or DiagonalGaussianEstimator. The univariate GaussianEstimator is refused at construction (its fitted component has no covariance to pack); spell a univariate Gaussian mixture MixtureEstimator([GaussianEstimator(), ...]).
name (str | None) – Optional diagnostic name.
conj_prior_params (Any | None) – Reserved compatibility slot.
suff_stat (ndarray | None) – Optional prior component-count vector used with pseudo_count.
pseudo_count (float | None) – Optional smoothing mass for mixture weights.
keys (tuple[str | None, str | None]) – Optional shared-statistic keys for weights and components.
robust (bool) – Enable the robust weight floor, as on MixtureEstimator.
init (str | None) – Initialization strategy, one of MIXTURE_INIT_STRATEGIES; None selects the default "kmeans++".

accumulator_factory()[source]

Return a Gaussian mixture accumulator factory.

Return type:: GaussianMixtureEstimatorAccumulatorFactory

accumulatorFactory()[source]

Deprecated alias for accumulator_factory().

New code should call accumulator_factory. The camelCase name remains available for older callers and returns the same factory, but now emits a DeprecationWarning (see docs/support-policy.rst).

Return type:: GaussianMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a Gaussian mixture from aggregated EM sufficient statistics.

The component M-step and weight estimate reuse the generic mixture estimator path. The fitted component means and covariances are then repacked into a GaussianMixtureDistribution.

Parameters:

nobs (float | None) – Unused compatibility argument from ParameterEstimator.
suff_stat (tuple[ndarray, tuple[Any, ...]]) – (component_counts, component_suff_stats) tuple.

Returns:

Fitted Gaussian mixture distribution.

Return type:

GaussianMixtureDistribution

class PCFGTerminationCertificate(proper, reachable_nonterminals, progeny_spectral_radius, critical_singular_classes, reason)[source]

Bases: object

Finite certificate that the start-symbol branching process dies out almost surely.

Parameters:

proper (bool)
reachable_nonterminals (tuple[Any, ...])
progeny_spectral_radius (float)
critical_singular_classes (tuple[tuple[Any, ...], ...])
reason (str)

class HeterogeneousPCFGStatistics(terminal_counts, binary_counts, emission_statistics, observation_mass, schema_version=1)[source]

Bases: Sequence[Any]

Mass-aware PCFG statistics with backward three-slot iteration.

Parameters:

terminal_counts (ndarray)
binary_counts (ndarray)
emission_statistics (tuple[Any, ...])
observation_mass (float)
schema_version (int)

class HeterogeneousPCFGFisherView(dist)[source]

Bases: FixedFisherView

Inside-outside Fisher view for heterogeneous PCFGs.

Coordinates are expected complete-data rule counts followed by terminal emission sufficient statistics gated by the posterior probability of the corresponding terminal rule at each token. For finite enumerable PCFGs, the model Fisher is the exact observed Fisher covariance of these posterior-expected complete-data statistics under the model distribution. Recursive or infinite-support grammars should use observed_fisher_* on data.

Parameters:: dist (Any)

fisher_information(stats=None, diagonal=False, ridge=1.0e-8, **kwargs)[source]

Return model Fisher information, falling back to observed statistics.

Parameters:

stats (ndarray | None)
diagonal (bool)
ridge (float)
kwargs (Any)

Return type:

fisher_vectors(stats=None, metric='diagonal', center=None, fisher=None, ridge=1.0e-8, **kwargs)[source]

Whiten PCFG statistics under the requested Fisher metric.

Parameters:

stats (ndarray | None)
metric (str)
center (ndarray | None)
fisher (ndarray | None)
ridge (float)
kwargs (Any)

Return type:

class HiddenAssociationStatistics(conditional, given, size, conditional_mass, observation_mass, schema_version=1)[source]

Bases: Sequence[Any]

Mass-aware statistics with backward three-child iteration.

Parameters:

conditional (Any)
given (Any)
size (Any)
conditional_mass (float)
observation_mass (float)
schema_version (int)

class HiddenAssociationEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate hidden-association support pairs in best-first order.

Parameters:: dist (HiddenAssociationDistribution)

hmm_dirichlet_default_prior(num_states)[source]

Returns the default (init_prior, row_priors) pair of unit-parameter Dirichlets.

Parameters:: num_states (int) – Number of hidden states S.
Returns:: Tuple (DirichletDistribution, list of S DirichletDistribution).

terminal_forward_loglik(log_w, log_a, log_b, term_mask)[source]

Log-likelihood of a terminal-state HMM sequence (length is a stopping time at the first terminal state).

log_b is the per-position, per-state emission log-density (L, K). The forward only transitions from non-terminal states and the likelihood sums the final position over terminal states. Shared by every HMM variant whose forward is a linear state trellis (base, lookback, …).

Parameters:

log_w (ndarray)
log_a (ndarray)
log_b (ndarray)
term_mask (ndarray)

Return type:

terminal_forward_backward(log_w, log_a, log_b, term_mask)[source]

Terminal-state forward-backward; returns (loglik, gamma (L,K), xi (L-1,K,K)) (gamma/xi None if 0-prob).

The backward pass mirrors the forward: only the final position may be terminal, and only non-terminal states have a future. Responsibilities are normalized by the sequence likelihood.

Parameters:

log_w (ndarray)
log_a (ndarray)
log_b (ndarray)
term_mask (ndarray)

Return type:

tuple[float, ndarray | None, ndarray | None]

class HiddenMarkovFisherView(dist)[source]

Bases: FixedFisherView

Observed Fisher view for HMMs via forward-backward statistics.

The per-observation vectors are posterior-expected complete-data sufficient statistics: initial-state counts, transition counts, per-state emission statistics, optional length statistics, and state occupancies when the model accumulator exposes them. For finite enumerable HMMs, the full model Fisher is the exact observed covariance of these statistics under the model distribution. For continuous or otherwise non-enumerable HMMs, diagonal model moments remain available; use observed_fisher_information() for empirical full covariance on data.

Parameters:: dist (Any)

structured_statistics(x, estimate=None, weight=1.0)[source]

Return Baum-Welch sufficient statistics for one weighted sequence.

Parameters:

x (Any)
estimate (Any | None)
weight (float)

Return type:

fisher_information(stats=None, diagonal=False, ridge=1.0e-8, **kwargs)[source]

Return HMM Fisher information, using exact finite-support moments when available.

Parameters:

stats (ndarray | None)
diagonal (bool)
ridge (float)
kwargs (Any)

Return type:

fisher_vectors(stats=None, metric='diagonal', center=None, fisher=None, ridge=1.0e-8, **kwargs)[source]

Return Fisher-normalized HMM sufficient statistics.

Full Fisher normalization is available when the model has finite enumerable support or when an explicit Fisher matrix is supplied. Otherwise callers should use the diagonal metric or observed Fisher routes.

Parameters:

stats (ndarray | None)
metric (str)
center (ndarray | None)
fisher (ndarray | None)
ridge (float)
kwargs (Any)

Return type:

class HierarchicalNormalDistribution(mu, tau, sigma, name=None, keys=None, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Two-level normal hierarchy over groups: y[g,i] ~ N(theta[g], sigma^2), theta[g] ~ N(mu, tau^2).

Each observation is one group (a sequence of values). mu is the population mean, tau the between-group sd and sigma the within-group sd. The latent group mean is marginalized out, so a group’s likelihood is the multivariate normal N(mu*1, sigma^2 I + tau^2 11^T) (computed in closed form). group_posterior / shrinkage give the partial-pooling estimates.

Parameters:

mu (float)
tau (float)
sigma (float)
name (str | None)
keys (str | None)
fit_diagnostics (HierarchicalNormalFitDiagnostics | None)

density(group)[source]

Return the marginal density of one observed group.

Return type:: float

log_density(group)[source]

Marginal log-likelihood of one group (latent group mean integrated out).

Return type:: float

seq_log_density(x)[source]

Return vectorized marginal log likelihoods for encoded groups.

Return type:: ndarray

group_posterior(ybar, n)[source]

Posterior (mean, sd) of a group’s true mean given its sample mean ybar and size n.

The shrinkage estimate mu + shrink*(ybar - mu) with shrink = tau^2/(tau^2 + sigma^2/n).

Parameters:

ybar (float)
n (int)

Return type:

tuple[float, float]

shrinkage(n)[source]

The shrinkage weight for a size-n group (0 = full pooling to mu, 1 = its own mean).

Parameters:: n (int)
Return type:: float

sampler(seed=None)[source]

Return a sampler for grouped observations from this hierarchy.

Parameters:: seed (int | None)
Return type:: HierarchicalNormalSampler

estimator(pseudo_count=None)[source]

Return an empirical-Bayes EM estimator for the hierarchy.

Parameters:: pseudo_count (float | None)
Return type:: HierarchicalNormalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution.

Return type:: HierarchicalNormalDataEncoder

class HierarchicalNormalEstimator(max_iter=500, tol=1e-9, max_group_sizes=_DEFAULT_MAX_GROUP_SIZES, name=None, keys=None)[source]

Bases: ParameterEstimator

Weighted empirical-Bayes EM over size-bucketed group sufficient statistics.

Parameters:

max_iter (int)
tol (float)
max_group_sizes (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for bounded size-bucketed statistics.

Return type:: StatisticAccumulatorFactory

estimate(nobs, suff_stat)[source]

Fit mu, tau, and sigma with a weighted EM receipt.

Return type:: HierarchicalNormalDistribution

class HierarchicalNormalFitDiagnostics(converged, identifiable, iterations, termination_reason, objective_trace, final_parameter_delta, n_group_sizes, total_group_weight, total_observation_weight)[source]

Bases: object

Machine-readable receipt for the empirical-Bayes EM fit.

Parameters:

converged (bool)
identifiable (bool)
iterations (int)
termination_reason (str)
objective_trace (tuple[float, ...])
final_parameter_delta (float | None)
n_group_sizes (int)
total_group_weight (float)
total_observation_weight (float)

determinize_quantized_terminal(dist, max_states=1 << 16)[source]

Determinize a terminal-value quantized HMM into a DeterminizedSequenceDistribution.

Raises EnumerationError if the HMM has no terminal_values, or if the belief expansion exceeds max_states (the twins property fails – not finitely determinizable).

Parameters:: max_states (int)

determinize_terminal_hmm(dist, max_states=1 << 16, max_denominator=10**9)[source]

Determinize a GENERAL terminal-value HMM (any transitions/initial, finite-discrete emissions).

Belief equality must be decidable, so each row of the model’s float probabilities is first rationalized (Fraction(p).limit_denominator(max_denominator)) and then normalized exactly. Determinization is exact on that stochastic rational model, which approximates the source to the requested rationalization precision. Requires terminal_values and enumerable finite emissions. Raises EnumerationError if not finitely determinizable within max_states or if an emission support is not finite/enumerable.

Parameters:

max_states (int)
max_denominator (int)

class DeterminizedSequenceDistribution(trans, accept, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A deterministic weighted machine over terminal-ended sequences (one path per sequence).

trans[q][x] = (log_weight, next_state) for a non-terminal symbol; accept[q][x] = log_weight for a terminal symbol that completes the sequence. log_density(x) is the unique path’s summed log-weight (== the original HMM’s exact marginal); enumeration yields exact, duplicate-free n-best-strings.

Parameters:: name (str | None)

density(x)[source]

Return the probability of a terminal-ended sequence.

Return type:: float

log_density(x)[source]

Return the unique deterministic path log-weight for a sequence.

Return type:: float

seq_log_density(x)[source]

Return log-densities for a batch of encoded sequences.

Return type:: ndarray

dist_to_encoder()[source]

Return the passthrough sequence encoder for determinized machines.

Return type:: DeterminizedDataEncoder

enumerator()[source]

Return an exact descending-probability enumerator.

Return type:: DeterminizedEnumerator

quantized_count_index(quantizer, max_fine_bucket)[source]

Structural count index over the deterministic machine -> sub-linear exact seek/rank.

The machine is deterministic (one path per sequence), so a forward reach DP over states counts each sequence exactly once at its (floored) cost: reach_by_len[t][q] is the count histogram of length-t non-terminal prefixes reaching state q; an accept edge then completes a length-(t+1) sequence. Unranking walks the reach DP backward through the (precomputed) incoming edges. Exact up to quantization tie granularity; no path over-count (the determinization already removed it).

Parameters:: max_fine_bucket (int)

sampler(seed=None)[source]

Return a sampler that walks the deterministic weighted machine.

Parameters:: seed (int | None)
Return type:: DeterminizedSampler

estimator(pseudo_count=None)[source]

Raise because determinized machines are derived views, not fitted families.

Parameters:: pseudo_count (float | None)

class DeterminizedEnumerator(dist)[source]

Bases: DistributionEnumerator

Exact descending-probability enumeration of sequences over the deterministic machine (n-best strings). Best-first with an admissible per-state best-completion bound (Viterbi over the machine).

Parameters:: dist (DeterminizedSequenceDistribution)

seek(index)[source]

Sub-linear exact seek over the deterministic machine (no prefix enumeration).

Deepens the structural count index until index is covered or the support is provably exhausted (the count-DP’s reliable truncated flag), then unranks within the located fine bucket. Robust to gaps in the cost spectrum, unlike the shared total-growth deepening heuristic.

Parameters:: index (int)

class IndianBuffetProcessFisherView(dist)[source]

Bases: FixedFisherView

Fixed Fisher view whose statistics are the binary feature indicators.

Parameters:: dist (Any)

class IndianBuffetProcessEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate finite IBP feature rows in descending plug-in probability order.

Parameters:: dist (IndianBuffetProcessDistribution)

class IntegerHiddenAssociationStatistics(initial_counts, weight_counts, state_counts, previous, size, observation_mass, schema_version=1)[source]

Bases: Sequence[Any]

Mass-aware statistics with backward five-slot iteration.

Parameters:

initial_counts (ndarray)
weight_counts (ndarray)
state_counts (ndarray)
previous (Any)
size (Any)
observation_mass (float)
schema_version (int)

class IntegerHiddenAssociationEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate integer hidden-association support pairs in best-first order.

Parameters:: dist (IntegerHiddenAssociationDistribution)

class IntegerPLSIEncodedData(value_ids, counts, entry_doc_ids, row_ids, totals, doc_ids, num_vals, num_docs)[source]

Bases: object

Owned, validated flattened representation of canonical integer PLSI bags.

Parameters:

value_ids (ndarray)
counts (ndarray)
entry_doc_ids (ndarray)
row_ids (ndarray)
totals (ndarray)
doc_ids (ndarray)
num_vals (int)
num_docs (int)

class IntegerProbabilisticLatentSemanticIndexingEnumerator(dist)[source]

Bases: DistributionEnumerator

Best-first enumerator for document-labelled integer PLSI bag observations.

Parameters:: dist (IntegerProbabilisticLatentSemanticIndexingDistribution)

multinomial_bag_stream(log_p_vec, min_val, len_dist, combine)[source]

Enumerate normalized integer count-vector bags in descending probability order.

Each fixed-size stream includes log(n!) - sum_w log(c_w!). A real length law is required because a conditional multinomial law for every possible length has infinite total mass when joined without length probabilities.

bag_stream(element_stream, len_dist, combine)[source]

Enumerate bags (multisets) drawn from a sorted element stream, in descending bag-score order.

element_stream is a descending (value, log_prob) iterator over the element distribution (any enumerable element distribution – a fixed categorical, or e.g. a per-document/per-given mixture). A bag scores by the sum of its elements’ log-probs plus log P_len(n) from len_dist; bags enumerate by the per-size multiset best-first search (MultisetProductEnumerator) under a length frontier. When len_dist is Null there is no length term and a synthetic n*log p_max frontier orders the (countably infinite) support by the element term alone. combine maps the tuple of (value, count) pairs to the emitted bag.

class JointMixtureFisherView(dist)[source]

Bases: MixtureFisherView

Complete-data Fisher view for joint mixtures without concrete proxies.

Parameters:: dist (Any)

property num_pairs: int: Number of positive-weight component pairs represented by this Fisher view.

log_density(x)[source]

Evaluate the Fisher-view mixture log-density for one paired observation.

Parameters:: x (Any)
Return type:: float

structured_statistics(x, estimate=None, weight=1.0)[source]

Return posterior pair weights and child sufficient statistics for one observation.

Parameters:

x (Any)
estimate (Any | None)
weight (float)

Return type:

class LabeledLDADistribution(topics, alphas, set_dist=None, len_dist=None, gamma_threshold=1.0e-8, max_gamma_iter=1000, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Labeled LDA model for documents with label sets.

Compatible with data type Tuple[Sequence[Tuple[T, float]], Sequence[int]], where T is the data type of the topic distributions.

density(x)[source]

Returns the density (exp of the variational lower bound) for a labeled document x.

Parameters:: x (Tuple[Sequence[Tuple[T, float]], Sequence[int]]) – Document as (value, count) pairs and a list of label indices.
Returns:: Density value for the document x.

density_semantics()[source]: Return density semantics for the labeled-LDA variational bound.

log_density(x)[source]

Returns the variational lower bound (ELBO) on the log-density for a labeled document x.

Parameters:: x (Tuple[Sequence[Tuple[T, float]], Sequence[int]]) – Document as (value, count) pairs and a list of label indices.
Returns:: Lower bound on the log-density of the document x.

seq_log_density(x)[source]

Vectorized evaluation of the variational lower bound (ELBO) for encoded documents.

Arg ‘x’ is the output of ‘LabeledLDADataEncoder.seq_encode()’.

Parameters:: x – Encoded sequence of iid LabeledLDA observations (see LabeledLDADataEncoder.seq_encode()).
Returns:: Numpy array with one lower-bound value per encoded document.

seq_encode(x)[source]

Deprecated alias for dist_to_encoder().seq_encode(): encode iid LabeledLDA observations.

Use dist_to_encoder() and LabeledLDADataEncoder.seq_encode() instead.

Parameters:: x (Sequence[Tuple[Sequence[Tuple[T, float]], Sequence[int]]]) – Sequence of labeled documents.
Returns:: Encoded sequence (see LabeledLDADataEncoder.seq_encode()).

seq_component_log_density(x)[source]

Vectorized per-topic log-density evaluation for encoded documents.

Parameters:: x – Encoded sequence of iid LabeledLDA observations (see LabeledLDADataEncoder.seq_encode()).
Returns:: 2-d numpy array (num_documents by nTopics) of per-topic document log-densities.

seq_posterior(x)[source]

Vectorized posterior topic weights for encoded documents.

Parameters:: x – Encoded sequence of iid LabeledLDA observations (see LabeledLDADataEncoder.seq_encode()).
Returns:: 2-d numpy array (num_documents by nTopics) of normalized posterior topic weights.

compute_capabilities()[source]: Return backend capability metadata for this concrete LabeledLDA instance.

backend_seq_log_density(x, engine)[source]: Backend-neutral labeled-LDA joint variational lower-bound scoring.

enumerator()[source]

Not supported: LabeledLDA’s log_density is a variational lower bound, not the true marginal.

Each document’s score is an ELBO obtained by running per-document variational inference (seq_posterior), not the exact marginal probability, so enumerating “in descending probability order” is ill-defined – the ELBO ranking need not match the true-probability ranking, and the per-document optimum isn’t a closed-form density over a countable support. Use sampler() and the (approximate) log_density directly.

Return type:: DistributionEnumerator

sampler(seed=None)[source]

Create a sampler for labeled LDA documents.

Note: Requires ‘set_dist’ and ‘len_dist’ to be set.

Parameters:: seed (Optional[int]) – Set seed for random sampling.
Returns:: Sampler bound to this distribution.
Return type:: LabeledLDASampler

estimator(pseudo_count=None)[source]

Create an estimator initialized from this labeled LDA distribution.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight sufficient statistics in estimation.
Returns:: Estimator configured with matching topic estimators.
Return type:: LabeledLDAEstimator

dist_to_encoder()[source]: Return a data encoder for iid labeled LDA observations.

class LabeledLDALabelSetStats(stats=None)[source]

Bases: object

Sufficient statistics for the coupled alpha update, grouped by distinct document label set.

Maps each distinct label set S (a sorted tuple of unique label indices) to a pair [n_S, m_S], where n_S is the total weight of the documents carrying label set S and m_S is the weighted sum of the per-document expected log topic weights E[log theta] (a vector with one entry per topic) over those documents.

add(label_set, weight, sum_log_p)[source]

Accumulate document weight and summed expected log topic weights for one label set.

Parameters:

label_set (Tuple[int, ...]) – Sorted tuple of label indices.
weight (float) – Total document weight to add for the label set.
sum_log_p (np.ndarray) – Weighted sum of per-document E[log theta] vectors to add.

Returns:

None.

combine(other)[source]

Merge the statistics of another LabeledLDALabelSetStats instance into this instance.

Parameters:: other (LabeledLDALabelSetStats) – Statistics to merge in (left unmodified).
Returns:: LabeledLDALabelSetStats object (self).

copy()[source]: Returns a deep copy of the LabeledLDALabelSetStats instance.

arrays()[source]

Returns the statistics as parallel arrays in sorted label-set order.

Returns:: Tuple of the sorted label-set tuples (List[Tuple[int, …]]), the per-set weights n_S (1-d numpy array), and the per-set summed expected log topic weights m_S (2-d numpy array with one row per label set).

class LabeledLDAEstimator(estimators, num_alphas, suff_stat=None, pseudo_count=None, keys=(None, None), fixed_alpha=None, gamma_threshold=1.0e-8, alpha_threshold=1.0e-8, max_gamma_iter=1000, max_alpha_iter=2000, set_dist=None, len_dist=None)[source]

Bases: ParameterEstimator

Estimate labeled LDA distributions from aggregated sufficient statistics.

accumulator_factory()[source]: Return an accumulator factory configured from this estimator.

accumulatorFactory()[source]: Deprecated alias for accumulator_factory().

estimate(nobs, suff_stat)[source]

Estimate a labeled LDA distribution from aggregated sufficient statistics.

suff_stat is a tuple containing:: suff_stat[0] (Optional[np.ndarray]): Previous alphas matrix. suff_stat[1] (LabeledLDALabelSetStats): Per-label-set expected log topic weights and counts. suff_stat[2] (Union[float, np.ndarray]): Per-label weighted document counts. suff_stat[3] (np.ndarray): Label-allocated weighted topic counts. suff_stat[4] (Sequence): Sufficient statistics for the topic distribution accumulators.

If ‘fixed_alpha’ is None, the alphas matrix is re-estimated by maximizing the coupled objective over all label rows (see ‘update_alpha_coupled()’). When every document carries exactly one label the objective decouples and the per-row fixed-point updates are used (see ‘update_alpha()’). Otherwise the alphas matrix is set to ‘fixed_alpha’.

Parameters:

nobs (Optional[float]) – Number of observations used in estimation.
suff_stat – See above for details.

Returns:

Estimated distribution.

Return type:

LabeledLDADistribution

doc_label_sets(nbx, nbcnt)[source]

Returns the sorted label-set tuple of each encoded document.

Parameters:

nbx (np.ndarray) – Flattened array of label indices over all documents (document-contiguous).
nbcnt (np.ndarray) – Number of labels for each document.

Returns:

List of sorted label-index tuples, one per document.

coupled_alpha_objective(alpha, label_sets, set_counts, set_mean_logs)[source]

Coupled multi-label alpha objective (terms independent of alpha dropped).

F(alpha) = sum_S n_S * [ log Gamma(sum_k a_Sk) - sum_k log Gamma(a_Sk) + sum_k a_Sk * mbar_Sk ], where a_S = mean_{l in S} alpha[l], n_S = set_counts[S], and mbar_S = set_mean_logs[S] are the per-set mean expected log topic weights.

Parameters:

alpha (np.ndarray) – Alphas matrix (num_alphas by num_topics).
label_sets (Sequence[Tuple[int, ...]]) – Label-set tuples.
set_counts (np.ndarray) – Per-set document weights n_S.
set_mean_logs (np.ndarray) – Per-set mean expected log topic weights mbar_S (one row per set).

Returns:

Objective value F(alpha).

coupled_alpha_gradient(alpha, label_sets, set_counts, set_mean_logs)[source]

Gradient of the coupled multi-label alpha objective with respect to alpha.

dF/d alpha[l,k] = sum_{S contains l} (n_S/|S|) * [ psi(sum_j a_Sj) - psi(a_Sk) + mbar_Sk ], with one term per occurrence of l in S.

Parameters:

alpha (np.ndarray) – Alphas matrix (num_alphas by num_topics).
label_sets (Sequence[Tuple[int, ...]]) – Label-set tuples.
set_counts (np.ndarray) – Per-set document weights n_S.
set_mean_logs (np.ndarray) – Per-set mean expected log topic weights mbar_S (one row per set).

Returns:

Numpy 2-d array with the same shape as alpha.

update_alpha_coupled(current_alpha, label_sets, set_counts, set_mean_logs, alpha_threshold, max_its=2000, *, return_diagnostics=False)[source]: Maximize the validated coupled label-row objective with bounded ascent.

class LDAOptimizationDiagnostics(algorithm, converged, iterations, max_iterations, termination_reason, final_residual, objective_trace=(), residual_trace=(), impossible_documents=())[source]

Bases: object

Serializable termination record for an LDA inner optimization.

Parameters:

algorithm (str)
converged (bool)
iterations (int)
max_iterations (int)
termination_reason (str)
final_residual (float)
objective_trace (tuple[float, ...])
residual_trace (tuple[float, ...])
impossible_documents (tuple[int, ...])

exception LDAConvergenceError(diagnostics)[source]

Bases: RuntimeError

Raised when an LDA inner optimization cannot meet its declared contract.

Parameters:: diagnostics (LDAOptimizationDiagnostics)

class LookbackHiddenMarkovModelDistribution(topics, w=MISSING, transitions=MISSING, lag=0, init_dist=None, len_dist=NullDistribution(), name=None, weights=MISSING, terminal_states=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Hidden Markov model whose state emissions condition on the previous lag observations.

Parameters:

topics (Sequence[SequenceEncodableProbabilityDistribution])
w (ndarray)
lag (int)
init_dist (Sequence[SequenceEncodableProbabilityDistribution] | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
weights (ndarray)
terminal_states (set[int] | Sequence[int] | None)

get_prior()[source]

Returns the chain conjugate prior in (init_prior, row_priors) form (or None).

Per-state emission/init component priors are owned by those distributions themselves – mirrors get_prior().

set_prior(prior)[source]

Set the conjugate Dirichlet chain prior over w/transitions and flag has_conj_prior.

Mirrors set_prior() exactly (no digamma-expectation caching: this class has no expected_log_density counterpart to feed). prior=None leaves the distribution a plain point model.

Parameters:: prior – (init_prior, row_priors) tuple or None.
Return type:: None

density(x)[source]

Evaluate the density of the distribution at sequence x.

Parameters:: x (Sequence[T]) – Observed sequence.
Returns:: Density at x.
Return type:: float

log_density(x)[source]

Evaluate the log-density of the distribution at sequence x.

Marginalizes the hidden state path with a scaled forward pass. The initial segment x[:lag] is scored by init_dist, each window x[t-lag:t+1] by the topic distributions, and the number of hidden positions by len_dist. When lag == 0 there is no initial segment: the first state emits the window x[0:1] directly (ordinary HMM).

Parameters:: x (Sequence[T]) – Observed sequence with len(x) >= lag.
Returns:: Log-density at x.
Return type:: float

viterbi_sequence(x)[source]

Compute the most likely hidden state sequence for observed sequence x.

Parameters:

x (Sequence[T]) – Observed sequence with len(x) >= lag.

Returns:

Integer array of len(x) - lag + 1 (len(x) when lag == 0) most likely hidden: state indices.

Return type:

np.ndarray

seq_log_density(x)[source]

Vectorized evaluation of the log-density at encoded sequences x.

Parameters:: x – Encoded sequence data produced by seq_encode() / dist_to_encoder().
Returns:: Log-density value for each encoded sequence.
Return type:: np.ndarray

compute_capabilities()[source]: Return backend capability metadata for this concrete lookback-HMM instance.

backend_seq_log_density(x, engine)[source]: Engine-neutral lookback-HMM scoring via the shared HMM forward pass.

seq_posterior(x)[source]

Compute posterior hidden state probabilities for encoded sequences x.

Parameters:

x – Encoded sequence data produced by seq_encode() / dist_to_encoder().

Returns:

For each sequence, an array of per-position posterior state: probabilities with shape (num_windows, num_states).

Return type:

List[np.ndarray]

density_semantics()[source]: Return exact-or-approximate density semantics joined from child models.

sampler(seed=None)[source]

Create a LookbackHiddenMarkovModelSampler for this distribution.

Parameters:: seed (Optional[int]) – Seed for random number generator.
Returns:: Sampler object (requires a non-null len_dist).
Return type:: LookbackHiddenMarkovModelSampler

enumerator()[source]

Not supported: lookback emissions condition on the previous lag observations.

Unlike the standard / segmental HMM, each emission depends on the preceding lag symbols, so the effective state is (hidden_state, last lag observations). Best-first enumeration over that augmented (and, for large/continuous alphabets, unbounded) state space is not implemented; use sampler() or the exact log_density / viterbi_sequence instead.

Return type:: DistributionEnumerator

estimator(pseudo_count=None)[source]

Create a LookbackHiddenMarkovModelEstimator from this distribution.

Parameters:

pseudo_count (Optional[float]) – Regularize the initial-state and transition estimates.

Returns:

Estimator built from the topic, initial-segment, and: length distributions, preserving the lag.

Return type:

LookbackHiddenMarkovModelEstimator

seq_encode(x)[source]

Encode a sequence of observed sequences for vectorized seq_ calls.

Parameters:: x (Sequence[Sequence[T]]) – Sequence of iid observed sequences.
Returns:: Encoded data consistent with seq_log_density(), seq_posterior(), and seq_update().

dist_to_encoder()[source]

Return a LookbackHiddenMarkovModelDataEncoder for encoding sequences of iid observations.

Returns:

Encoder built from the topic, initial, and length: distributions of this instance.

Return type:

LookbackHiddenMarkovModelDataEncoder

class LookbackHiddenMarkovModelEstimator(estimators, lag=0, init_estimators=None, len_estimator=NullEstimator(), suff_stat=None, pseudo_count=(None, None), name=None, keys=(None, None, None), terminal_states=None, prior=None)[source]

Bases: ParameterEstimator

Estimator for a lookback hidden Markov model from aggregated sufficient statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
lag (int)
init_estimators (Sequence[ParameterEstimator] | None)
len_estimator (ParameterEstimator | None)
pseudo_count (float | tuple[float | None, float | None] | None)
name (str | None)
keys (tuple[str | None, str | None, str | None] | None)

get_prior()[source]

Returns the chain conjugate prior in (init_prior, row_priors) form (or None).

Mirrors get_prior().

set_prior(prior)[source]

Set the conjugate Dirichlet chain prior and flag whether it admits the conjugate update.

Mirrors set_prior() exactly.

Parameters:: prior – (init_prior, row_priors) tuple or None; has_conj_prior is set when both the initial-state prior and all row priors are Dirichlet.
Return type:: None

model_log_density(model)[source]

Log-density of the model parameters under the priors (ELBO global term).

Sums the Dirichlet log-densities of the initial-state and transition probabilities (when a conjugate chain prior is set) plus each topic/init-segment estimator’s own model_log_density of its fitted distribution. Mirrors model_log_density() (which does not include its own len_estimator either – kept at parity here rather than widening scope beyond the sibling class).

Parameters:: model (LookbackHiddenMarkovModelDistribution) – Model to score.
Returns:: Prior log-density of the model parameters.
Return type:: float

accumulator_factory()[source]

Create a LookbackHiddenMarkovModelEstimatorAccumulatorFactory from the member estimators.

Returns:

Factory for accumulators consistent: with this estimator.

Return type:

LookbackHiddenMarkovModelEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a LookbackHiddenMarkovModelDistribution from aggregated sufficient statistics.

Parameters:

nobs (Optional[float]) – Weighted number of observations (passed to the length estimator).
suff_stat (Tuple) – Sufficient statistics in the format returned by LookbackHiddenMarkovModelEstimatorAccumulator.value().

Returns:

M-step estimate of the distribution.

Return type:

LookbackHiddenMarkovModelDistribution

validated_state_ids(values, n_states, *, context, field)[source]

Return exact in-range state IDs without lossy integer coercion.

Parameters:

values (Iterable[Any] | None)
n_states (int)
context (str)
field (str)

Return type:

frozenset[int] | None

validated_terminal_states(values, n_states, *, context)[source]

Return exact in-range terminal state IDs without lossy integer coercion.

Parameters:

values (Iterable[Any] | None)
n_states (int)
context (str)

Return type:

frozenset[int] | None

validated_terminal_values(values, *, context)[source]

Return an owned non-empty set of terminal emissions.

Parameters:

values (Iterable[Any] | None)
context (str)

Return type:

frozenset[Any] | None

validate_terminal_reachability(initial, transitions, terminal_states, *, context)[source]

Require every initially reachable state to have a positive-probability path to termination.

Parameters:

initial (Any)
transitions (Any)
terminal_states (frozenset[int] | None)
context (str)

Return type:

None

validated_terminal_step_cap(value)[source]

Return an exact positive stopping-time sampling bound.

Parameters:: value (Any)
Return type:: int

require_terminal_reached(reached, *, mode, max_steps, last_state=None)[source]

Raise the typed bounded-sampling failure when the stop event was not reached.

Parameters:

reached (bool)
mode (str)
max_steps (int)
last_state (int | None)

Return type:

None

class MixtureFisherView(dist)[source]

Bases: FixedFisherView

Complete-data Fisher view for finite mixture distributions.

Coordinates are component assignment indicators followed by each component’s sufficient statistics gated by that assignment. Observed data map to posterior-expected complete-data statistics.

Parameters:: dist (Any)

structured_statistics(x, estimate=None, weight=1.0)[source]

Return mixture responsibility statistics and weighted component statistics for one observation.

Parameters:

x (Any)
estimate (Any | None)
weight (float)

Return type:

class ProbabilisticCircuitStatistics(sum_counts, leaf_statistics, leaf_counts, observation_mass, schema_version=1)[source]

Bases: Sequence[Any]

Mass-aware circuit statistics with backward two-slot iteration.

Parameters:

sum_counts (dict[int, ndarray])
leaf_statistics (dict[int, Any])
leaf_counts (dict[int, float])
observation_mass (float)
schema_version (int)

leaf(scope, dist)[source]

A leaf node: an existing mixle dist over the variable indices scope (an int or a tuple).

Parameters:

scope (Any)
dist (Any)

Return type:

_Node

prod(children)[source]

A product node over children with PAIRWISE-DISJOINT scopes (the decomposability requirement).

Parameters:: children (list[_Node])
Return type:: _Node

summ(children, w=None)[source]

A sum (mixture) node over children that share ONE scope (smoothness); w are mixing weights.

Parameters:

children (list[_Node])
w (Any)

Return type:

_Node

class ProbabilisticCircuitDistribution(root, num_vars, lns_step=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A sum-product network density; build with leaf()/prod()/summ() then pass the root.

Parameters:

root (_Node)
num_vars (int)
lns_step (float | None)

log_density(x)[source]

Return the log-density of one full observation by an upward circuit pass.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-densities for encoded observations.

Parameters:: x (Any)
Return type:: ndarray

dist_to_encoder()[source]

Return the encoder that projects observations into each leaf scope.

Return type:: ProbabilisticCircuitEncoder

sampler(seed=None)[source]

Return an ancestral sampler for this fixed circuit.

Parameters:: seed (int | None)
Return type:: ProbabilisticCircuitSampler

estimator(pseudo_count=None)[source]

Return an EM estimator for this fixed circuit structure.

Parameters:: pseudo_count (float | None)
Return type:: Any

with_params(new_nodes, new_leaf_dists)[source]

A new circuit with the same structure but re-estimated sum-weights / leaf parameters (M-step output).

Parameters:

new_nodes (list[tuple])
new_leaf_dists (dict[int, Any])

Return type:

ProbabilisticCircuitDistribution

class ProbabilisticCircuitEncoder(leaf_dists, leaf_scope)[source]

Bases: DataSequenceEncoder

Encode each leaf’s projected columns once with the leaf’s own encoder (shared across EM iterations).

Parameters:

leaf_dists (dict[int, Any])
leaf_scope (dict[int, tuple])

seq_encode(x)[source]

Encode a batch for every leaf distribution using its projected scope.

Parameters:: x (Any)
Return type:: dict[int, Any]

row_count(x)[source]

Return the common number of encoded circuit rows.

Parameters:: x (Any)
Return type:: int

class ProbabilisticCircuitEstimator(dist, pseudo_count=None)[source]

Bases: ParameterEstimator

Fits a fixed-structure circuit by EM: renormalize each sum node’s weights to its expected child counts, and re-estimate each leaf from its responsibility-weighted sufficient statistic.

Parameters:

dist (ProbabilisticCircuitDistribution)
pseudo_count (float | None)

accumulator_factory()[source]

Return a factory for circuit-flow sufficient-statistic accumulators.

Return type:: ProbabilisticCircuitAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate sum-node weights and leaf distributions from accumulated circuit flows.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

ProbabilisticCircuitDistribution

class QuantizedHMMFitDiagnostics(converged, fixed_theta, theta, objective, iterations_per_start, converged_starts, termination_reasons, selected_start, selected_start_converged, scalar_optimizer_evaluations, split_count, schema_version=1, algorithm='multistart_coordinate_ascent')[source]

Bases: object

Immutable convergence and provenance record for one quantized M-step.

Parameters:

converged (bool)
fixed_theta (bool)
theta (float)
objective (float)
iterations_per_start (tuple[int, ...])
converged_starts (tuple[bool, ...])
termination_reasons (tuple[str, ...])
selected_start (int)
selected_start_converged (bool)
scalar_optimizer_evaluations (int)
split_count (int)
schema_version (int)
algorithm (str)

exception QuantizedHMMOptimizationError(message, diagnostics)[source]

Bases: RuntimeError

Raised when the quantized coordinate or scalar optimization fails.

Parameters:

message (str)
diagnostics (QuantizedHMMFitDiagnostics)

Return type:

None

class PhaseSchedule[source]

Bases: object

Maps a position t in a length-L sequence to a phase index in [0, n_phases).

phase(t, length)[source]

Return the phase index for position t in a sequence of length.

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

Serialize the schedule to a JSON-compatible dictionary.

Return type:: dict[str, Any]

static from_dict(d)[source]

Deserialize a schedule produced by to_dict().

Parameters:: d (dict[str, Any])
Return type:: PhaseSchedule

class SemiSupervisedHiddenMarkovModelDistribution(topics, transitions, len_dist=None, name=None, keys=None, use_numba=None, terminal_states=None)[source]

Bases: SequenceEncodableProbabilityDistribution

HMM with shared emissions/transitions where each observation may carry a per-position state prior.

compute_capabilities()[source]: Declare the legacy NumPy execution path for semi-supervised HMM inference.

density(x)[source]

Return the probability of one semi-supervised HMM observation.

Return type:: float

log_density(x)[source]

Return the log-likelihood of one (emissions, state_prior) observation.

Return type:: float

seq_log_density(x)[source]

Return vectorized log-likelihoods for encoded semi-supervised HMM observations.

Return type:: ndarray

density_semantics()[source]: Return the joined density semantics of emission and optional length distributions.

sampler(seed=None)[source]: Return a sampler for emission sequences with no external state priors.

estimator(pseudo_count=None)[source]: Return a Baum-Welch estimator for transitions, emissions, and optional length.

dist_to_encoder()[source]: Return the encoder for emission sequences, priors, and optional lengths.

class SemiSupervisedHiddenMarkovEstimator(estimators, len_estimator=None, pseudo_count=None, name=None, keys=(None, None), terminal_states=None)[source]

Bases: ParameterEstimator

Estimate transitions, emissions, and optional length from semi-supervised HMM statistics.

accumulator_factory()[source]: Return a factory for semi-supervised HMM sufficient-statistic accumulators.

estimate(nobs, suff_stat)[source]: Estimate the HMM transition matrix and child distributions from accumulated statistics.

SemiSupervisedHiddenMarkovModelEstimator: alias of SemiSupervisedHiddenMarkovEstimator

class SparseScore(lower, upper, exact, n_scored)[source]

Bases: object

A certified bracket on a mixture’s log p(x) from scoring only the top components.

lower <= log p(x) <= upper always holds; exact is True when the bracket collapsed (all components scored, or max_components covered the support). n_scored components were exactly evaluated. When exact, lower == upper == log p(x).

Parameters:

lower (float)
upper (float)
exact (bool)
n_scored (int)

log_density_sup(dist)[source]

Maximum log p(x) of a single distribution, or None if unbounded / unknown.

A finite value certifies the component can contribute at most this much, which is what makes the dropped-tail bound sound. None (unbounded density or an unrecognized family) forces the exact path.

Parameters:: dist (Any)
Return type:: float | None

sparse_mixture_score(mixture, x, max_components)[source]

Score mixture.log_density(x) exactly on the top max_components and certify the rest.

Ranks components by the low-cost upper bound log w_k + sup_k (x-independent), scores the exact contribution of only the top ones, and bounds the dropped tail by the remaining upper bounds. Returns a SparseScore bracket. If any positive-weight component’s density is unbounded (log_density_sup is None), falls back to exact full scoring (lower == upper, no speedup).

Parameters:

mixture (Any)
x (Any)
max_components (int)

Return type:

SparseScore

collapse_identical(mixture)[source]

Merge components that are identical (same family + parameters) by summing their weights – EXACT.

A fitted huge mixture often carries duplicate components; pooling exact duplicates leaves log p(x) unchanged while shrinking K. Identity requires the same fully qualified family and canonical serialized state. A component that cannot produce that representation is conservatively left separate. ‘Blend a mixture of closed forms’ with zero approximation.

Parameters:: mixture (Any)
Return type:: Any

collapse_gaussian_mixture(mixture, max_components)[source]

Reduce an all-Gaussian mixture to <= max_components by moment-matching the nearest pair.

Greedily merges the two closest components (by mean) into the single Gaussian preserving their combined weight, mean, and variance, until max_components remain. Approximate (it widens), but it preserves the OVERALL mixture mean and variance exactly – the analytic ‘collapse a huge mixture of closed forms’ that lets scoring/sampling scale.

Parameters:

mixture (Any)
max_components (int)

Return type:

class FinalStateEnumeration(hmm, len_dist)[source]

Bases: object

Result of _final_state_enumerate(): top_k(k) -> [(sequence, log_prob), …] descending.

top_k(k)[source]: Return the top k final-state-constrained sequences.

class IOHMMEstimator(emission_estimators, transition_protos, name=None)[source]

Bases: ParameterEstimator

Estimator (M-step) for an InputOutputHMM: re-estimates pi, one transition operator per input symbol (from the per-input expected counts), and each state’s emission.

accumulator_factory()[source]: Return the accumulator factory used by this estimator.

estimate(nobs, suff_stat)[source]: Estimate an IOHMM from Baum-Welch sufficient statistics.

class EDHMMEstimator(emission_estimators, k, d, name=None)[source]

Bases: ParameterEstimator

Estimator (M-step) for an ExplicitDurationHMM: re-estimates pi, the zero-diagonal transition, the per-state DURATION distributions, and each state’s emission from the segment-posterior statistics.

accumulator_factory()[source]: Return the accumulator factory used by this estimator.

estimate(nobs, suff_stat)[source]: Estimate an explicit-duration HMM from segment posterior statistics.

chunked_state_posteriors(hmm, seq, *, chunk, overlap)[source]

State posteriors gamma for one long sequence via overlapping chunks, each run INDEPENDENTLY (embarrassingly parallel). The first chunk uses the model’s pi; interior chunks start from the uniform belief and the overlap context lets the chain forget that wrong boundary – so the kept interior matches the exact forward-backward up to an error that decays at the mixing rate in overlap.

Parameters:

hmm (StructuredHMM)
chunk (int)
overlap (int)

Return type:

fit_chunked(hmm, seqs, *, chunk, overlap, max_its=50, workers=0, tol=1e-6, weights=None)[source]

Baum-Welch where each long sequence’s forward-backward is split into overlapping chunks run in PARALLEL (the forgetting property bounds the boundary error). workers>0 runs the per-chunk E-steps on a thread pool (NumPy releases the GIL in its array kernels); workers=0 runs them serially. The interior suff-statistics are accumulated exactly as in StructuredHMM.fit(); this only changes how the E-step is computed, trading a small, overlap-controlled approximation for intra-sequence parallelism. The returned HMMFitResult remains unpackable as (fitted_hmm, loglik_trace) and marks the receipt’s objective as approximate.

Parameters:

hmm (StructuredHMM)
chunk (int)
overlap (int)
max_its (int)
workers (int)
tol (float)

find_level(parents)[source]

Find the level in the tree for nodes, given an array of parents.

Parameters:: parents (np.ndarray) – Numpy array of integers with first entry -1.
Returns:: Level of each node in the free excluding the first entry which is the root (level = 0).
Return type:: list[int]

level_state_prob(levels, num_states, tr_mat, init_prob, out)[source]: Numba kernel: marginal state probabilities per tree level, out[k] = init_prob @ tr_mat^k.

closure(x, total=1.0)[source]

Normalize strictly positive finite rows to a positive finite total.

Parameters:

x (ndarray)
total (float)

Return type:

clr(x)[source]

Return centered logratios for strictly positive finite compositions.

Parameters:: x (ndarray)
Return type:: ndarray

clr_inv(y)[source]

Map finite clr-coordinate rows to the unit simplex.

Parameters:: y (ndarray)
Return type:: ndarray

ilr(x, basis=None)[source]

Map strictly positive D-part rows to D-1 ilr coordinates.

Parameters:

x (ndarray)
basis (ndarray | None)

Return type:

ilr_inv(y, basis=None)[source]

Map finite D-1 ilr rows to strictly positive unit compositions.

Parameters:

y (ndarray)
basis (ndarray | None)

Return type: