mixle.stats package ¶

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:

Sequence encoded data for use with ‘seq_’ functions.

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 the sum of log_density values for a given SequenceEncodableProbabilityDistribution: over encoded data.

Returns a Tuple containing the sum of all observations in enc_data, and the sum of the log_density evaluated at all encoded data observations in enc_data. This is a fully vectorized evaluation.

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)[source]

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

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; if the cap is hit before the threshold, the (sub-threshold) prefix gathered so far is returned. p >= 1.0 on an infinite support therefore requires max_items.

Parameters:

p (float) – Target cumulative probability; p <= 0 returns the empty set.
max_items (Optional[int]) – Hard cap on the number of values pulled.

Returns:

List of (value, log_prob) pairs in non-increasing probability order.

Return type:

list[tuple[Any, float]]

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 honest 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.

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

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)

count: int

payload: Any

engine: ComputeEngine

nbytes: int

encoder: DataSequenceEncoder | None = 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)

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)

engine_ready: tuple[str, ...] = ('numpy',)

kernel_status: str = 'generic'

numpy_only_reason: str | None = 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)

name: str

distribution_type: type[Any]

parameters: tuple[ParameterSpec, ...]

statistics: tuple[StatisticSpec, ...]

support: str

children: tuple[DistributionDeclaration, ...] = ()

child_roles: tuple[str, ...] = ()

differentiable: bool = True

exponential_family: ExponentialFamilySpec | None = None

legacy_sufficient_statistics: Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None = 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, 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)
fixed_base (bool)
runtime_scoring (bool)

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 = None

sufficient_statistics_from_params: Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None = None

base_measure_from_params: Callable[[Any, dict[str, Any], Any], Any] | None = None

legacy_sufficient_statistics: Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None = None

fixed_base: bool = True

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)

name: str

constraint: str = 'real'

differentiable: bool = True

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)

name: str

kind: str = 'moment'

additive: bool = True

scales: bool = True

exception BackendScoringError[source]

Bases: NotImplementedError

Raised when a distribution has no backend scoring hook.

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]]

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]

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'. field('x_copy', source='x') names a second model variable that reads the same input key, useful for dependence features and repeated views.

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 StackedComponentParams(component_type, strategy, params)[source]

Bases: object

A generic route for homogeneous component scoring.

Parameters:

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

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])

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 component-stat payload in the legacy local-slice format.

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() and returns (component_start, (counts, stats)). Non-sharded engines naturally return the full component range starting at zero.

Return type:: 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_start, component_stop, components, weights, total_count)[source]

Bases: object

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

Parameters:

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

component_start: int

component_stop: int

components: tuple[Any, ...]

weights: ndarray

total_count: float

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)

component_type: type[Any]

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_start, value, total_count=None)[source]

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

Parameters:

estimator (ParameterEstimator)
component_start (int)
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, tuple[Any, tuple[Any, ...]]]])

Return type:

tuple[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]

classmethod compute_declaration()[source]

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 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]

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]

classmethod compute_declaration()[source]

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 type:: BetaAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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 type:: LaplaceAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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.

Parameters:

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

accumulator_factory()[source]

Return type:: LogisticAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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

cdf(x)[source]

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

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

quantile(q)[source]

Inverse CDF F^{-1}(q) (via scipy logser).

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

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 type:: LogSeriesAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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]

Creates a BinomialDataEncoder object for seqeunce encoding data.

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}).

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

seq_log_density(x)[source]

Return vectorized log-mass for an array of counts.

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

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, 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)
min_conc (float)
max_conc (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: BetaBinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

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

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]

Creates a BinomialAccumulatorFactory object from member varaibles.

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 BinomialDistribution from BinomialEstimator using sufficient statistics in suff_stat.

Note: nobs is not used here. Kept for consistency with other ParameterEstimators.

Memeber variable suff_stat is simply the proportion (p) of the BinomialDistributon passed to BinomalEstimator. The pseudo_count is used to inflate (p) in estimation.

Parameters:

nobs (Optional[float]) – Not used.
suff_stat (Tuple[float, float, Optional[int], Optional[int]]) – Tuple of count, sum, min_val max_val, obtained from aggregation of data.

Returns:

BinomialDistribution estimated from suff_stat input and member variables suff_stat and pseudo_count.

class BinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Parameters:: dist (BinomialDistribution)

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

Bases: SequenceEncodableProbabilityDistribution

Categorical distribution over hashable labels.

Parameters:

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

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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.

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

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]

Creates CategoricalSampler for sampling from CategoricalDistribution.

Parameters:: seed (Optional[int]) – Seed for setting random number generator used to sample.
Returns:: CategoricalSampler object.
Return type:: CategoricalSampler

estimator(pseudo_count=None)[source]

Creates a CategoricalEstimator for estimating parameters of CategoricalDistribution.

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

dist_to_encoder()[source]

Creates a CategoricalDataEncoder object for sequence encoding data.

Returns:: CategoricalDataEncoder object.
Return type:: CategoricalDataEncoder

enumerator()[source]

Creates a CategoricalEnumerator iterating the support in descending probability order.

Returns:: CategoricalEnumerator object.
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 type:: ChineseRestaurantProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

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

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]

Create CategoricalAccumulatorFactory with keys passed is set.

Returns:: CategoricalAccumulatorFactory
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

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]

compute_declaration()[source]

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 a ‘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), we score the un-normalized log-density:

log(p_mat(x)) = sum_{j=0}^{n-1} 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. The multinomial coefficient is intentionally omitted (see the module docstring), so this is a per-category scoring form, not a normalized mass over count vectors.

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]

Create a MultinomialSampler object from MultinomialDistribution object instance.

Parameters:: seed (Optional[int]) – Set the seed for sampling from MultinomialDistribution.
Returns:: MultinomialSampler object.
Return type:: MultinomialSampler

estimator(pseudo_count=None)[source]

Create an MultinomialEstimator object from an MultinomialDistribution object instance.

Parameters:: pseudo_count (Optional[float]) – Re-weight member sufficient statistics when estimating from aggregated data.
Returns:: MultinomialEstimator object.
Return type:: MultinomialEstimator

dist_to_encoder()[source]

Create a MultinomialDataEncoder object from object instance.

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

Parameters:

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

accumulator_factory()[source]

Create MultinomialAccumulatorFactory object from MultinomialEstimator object instance.

Return type:: MultinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a MultinomialDistribution object from aggregated data contained in arg ‘suff_stat’.

Parameters:

nobs (Optional[float]) – Number of observations used in aggregation of ‘suff_stat’.
suff_stat (Tuple[SS1, Optional[SS2]]) – Tuple of sufficient statistics for distribution of values and trial distribution.

Returns:

MultinomialDistribution object.

Return type:

MultinomialDistribution

class MultinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates multinomial observations (lists of (value, count) pairs) in descending probability order.

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]

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]

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. 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 (dict[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]

What log_density returns relative to the true log-density (default: exact).

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]

Create CompositeSampler for sampling from CompositeDistribution instance.

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

estimator(pseudo_count=None)[source]

Create CompositeEstimator for estimating CompositeDistribution.

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]

Creates CompositeDataEncoder for encoding sequence of tuple data.

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

Parameters:

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

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]

Creates CompositeAccumulatorFactory from each ParameterEstimator in estimators.

Returns:: CompositeAccumulatorFactory.
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

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]

compute_declaration()[source]

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 per-component legacy conditional sufficient statistics.

Parameters:

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

Return type:

tuple[dict[Any, Any], Any, 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:

sampler(seed=None)[source]

Creates ConditionalDistributionSampler object for sampling from ConditionalDistribution instance.

Parameters:: seed (Optional[int]) – Set seed for sampling from ConditionalDistributionSampler object.
Returns:: ConditionalDistributionSampler object.
Return type:: ConditionalDistributionSampler

estimator(pseudo_count=None)[source]

Creates ConditionalDistributionEstimator object from sufficient statistics of ConditionalDistribution object.

Used to estimate a ConditionalDistribution from data observations.

Parameters:: pseudo_count (Optional[float]) – Used to inflate the sufficient statistics of ConditionalDistribution.
Returns:: ConditionalDistributionEstimator object.
Return type:: ConditionalDistributionEstimator

dist_to_encoder()[source]

Creates ConditionalDistributionDataEncoder object for encoding sequences of ConditionalDistribution data.

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]

Creates ConditionalDistributionAccumulatorFactory from estimator member values.

Returns:: ConditionalDistributionAccumulatorFactory object.
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.

Returns a ConditionalDistribution object estimated from the sufficient statistics in suff_stat.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency.
suff_stat (tuple[dict[T0, SS0], SS1 | None, SS2 | None]) – 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)

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)[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)

compute_capabilities()[source]

compute_declaration()[source]

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 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 type:: ChowLiuTreeAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple[float, int, list[dict[Hashable, float]], list[dict[Hashable, Any]], dict[tuple[int, int], dict[tuple[Hashable, Hashable], float]], tuple[Any, ...], dict[tuple[int, int], dict[Hashable, Any]]])

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

DiracLengthMixtureDistribution object defined by a length distribution, choice of dirac value, and p.

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]) – Set name for object instance.
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

Name for object instance.

Type:: Optional[str]

compute_capabilities()[source]

compute_declaration()[source]

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

DiracLengthMixtureEstimator object for estimating DiracLengthMixtureDistribution objects.

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]) – Set name for object instance.
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

Name for object instance.

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]

classmethod compute_declaration()[source]

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.
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]

Create a DirichletSampler for sampling from this distribution.

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

estimator(pseudo_count=None)[source]

Create a DirichletEstimator for estimating this distribution.

If pseudo_count is passed, the current normalized alpha is used to regularize the estimate.

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

dist_to_encoder()[source]

Create DirichletDataEncoder object for encoding sequences of 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

DirichletEstimator object for estimating a Dirichlet distribution from aggregated sufficient statistics.

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 DirichletAccumulator object from attributes variables.

Return type:: DirichletAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a Dirichlet distribution from aggregated sufficient statistics.

Suff_stat is a Tuple of size 4 containing:: suff_stat[0] (float): Sum of observation weights. suff_stat[1] (np.ndarray): Weighted sum of the log of observation vectors. suff_stat[2] (np.ndarray): Weighted sum of observation vectors. suff_stat[3] (np.ndarray): Weighted sum of squared observation vectors.

The concentration parameters are solved from the mean-log-probability sufficient statistic with a fixed-point solver (dirichlet_param_solve, or find_alpha when use_mpe is set).

Parameters:

nobs (Optional[float]) – Not used. Counts are taken from suff_stat[0].
suff_stat (Tuple[int, np.ndarray, np.ndarray, np.ndarray]) – See above for details.

Returns:

DirichletDistribution object.

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]

classmethod compute_declaration()[source]

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).

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]

Create a DiagonalGaussianSampler for sampling from this distribution.

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

estimator(pseudo_count=None)[source]

Create a DiagonalGaussianEstimator for estimating this distribution.

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

dist_to_encoder()[source]

Returns a DiagonalGaussianDataEncoder object for encoding sequences of iid 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

DiagonalGaussianEstimator object for estimating a diagonal Gaussian distribution from aggregated sufficient statistics.

Parameters:

dim (int | None)
pseudo_count (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]

Returns a DiagonalGaussianAccumulatorFactory built from the estimator’s attributes.

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, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Exponential distribution on non-negative real values with scale beta.

Parameters:

beta (float)
name (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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 an ExponentialSampler object 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]

Create ExponentialEstimator with beta passed as suff_stat.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: ExponentialEstimator.
Return type:: ExponentialEstimator

dist_to_encoder()[source]

Returns an ExponentialDataEncoder object.

Return type:: ExponentialDataEncoder

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

Bases: ParameterEstimator

Parameters:

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

accumulator_factory()[source]

Create ExponentialAccumulatorFactory object with keys passed.

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)[source]

Bases: SequenceEncodableProbabilityDistribution

Gamma distribution parameterized by shape and scale.

Parameters:

k (float)
theta (float)
name (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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]

Returns 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]

Create a GammaSampler object from GammaDistribution.

Parameters:: seed (Optional[int]) – Set seed on random number generator.
Returns:: GammaSampler object.
Return type:: GammaSampler

estimator(pseudo_count=None)[source]

Creates GammaEstimator object from GammaDistribution instance.

Parameters:: pseudo_count (Optional[float]) – Re-weight the sufficient statistics of GammaDistribution instance if not None.
Returns:: GammaEstimator object.
Return type:: GammaEstimator

dist_to_encoder()[source]

Returns GammaDataEncoder object for encoding sequence of GammaDistribution 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

Parameters:

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

accumulator_factory()[source]

Create GammaAccumulatorFactory with keys passed.

Return type:: GammaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Obtain GammaDistribution from aggregated sufficient statistics of observed data.

Takes sufficient statistic aggregated from observed data:: suff_stat[0]: weighted sum of observations suff_stat[1]: weighted sum of log-observations suff_stat[2]: weighted observation count.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[float, float, float]) – See description above for details.

Returns:

GammaDistribution object.

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, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Univariate Gaussian distribution.

Parameters:

mu (float)
sigma2 (float)
name (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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]

Create an GaussianSampler object from parameters of GaussianDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: GaussianSampler object.
Return type:: GaussianSampler

estimator(pseudo_count=None)[source]

Create GaussianEstimator with mu and sigma2 passed if pseudo_count is not None.

Arg variable pseudo_count is used to pass and re-weight mu and sigma2 of GaussianDistribution instance. Simply creates a GaussianEstimator with name passed if pseudo_count is None.

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

dist_to_encoder()[source]

Returns a GaussianDataEncoder object for encoding sequences of data.

Return type:: GaussianDataEncoder

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

Bases: ParameterEstimator

Parameters:

pseudo_count (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)

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 GaussianDistribution object from sufficient statistics aggregated from data.

Arg passed suff_stat is tuple of four floats:: suff_stat[0] (float): Sum of weighted observations (sum_i w_i*X_i), suff_stat[1] (float): Sum of weighted observations (sum_i w_i*X_i^2), suff_stat[2] (float): Sum of weighted observations (sum_i w_i), suff_stat[3] (float): Sum of weighted observations (sum_i w_i),

obtained from aggregation of observations.

If member variable pseudo_count is not None, suff_stat is combined with re-weighted member instance variables suff_stat. If pseudo_count is None, arg suff_stat is used to form maximum likelihood estimates for mu and sigma2 of GaussianDistribution object.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[float, float, float, float]) – See above for details.

Returns:

GaussianDistribution object.

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]

classmethod compute_declaration()[source]

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

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 type:: InverseGammaAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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

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 type:: InverseGaussianAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

InverseGaussianDistribution

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

Bases: SequenceEncodableProbabilityDistribution

Geometric distribution on {1, 2, ...} with success probability p.

Parameters:

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

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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]

Creates GeometricSampler object from GeometricDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed on random number generator.
Returns:: GeometricSampler object.
Return type:: GeometricSampler

estimator(pseudo_count=None)[source]

Creates GeometricEstimator object.

Parameters:: pseudo_count (Optional[float]) – Regularize summary statistics from object instance.
Returns:: GeometricEstimator object.
Return type:: GeometricEstimator

dist_to_encoder()[source]

Returns GeometricDataEncoder object for encoding sequence of GeometricDistribution 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

Parameters:

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

accumulator_factory()[source]

Create GeometricAccumulatorFactory object with name and keys passed.

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 geometric distribution from aggregated sufficient statistics (suff_stat).

Uses suff_stat (Tuple[float, float]):: suff_stat[0] (float): sum of weights of the observations (count), suff_stat[1] (float): weighted sum of observations (sum).

If member variable pseudo_count is not None, then suff_stat arg is combined with pseudo_count weighted member variable of sufficient statistics.

If member variable pseudo_count is not None, and member variable sufficient statistic is None, suff_stat arg is reweighted by pseudo_count alone.

If no pseudo_count is set, p = suff_stat[0]/suff_stat[1] is passed to GeometricDistribution.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (Tuple[float, float]) – See above.

Returns:

GeometricDistribution object.

Return type:

GeometricDistribution

class GeometricEnumerator(dist)[source]

Bases: DistributionEnumerator

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]

classmethod compute_declaration()[source]

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

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.

Parameters:

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

accumulator_factory()[source]

Return type:: GumbelAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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

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 type:: HalfNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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

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 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]

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]

classmethod compute_declaration()[source]

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 type:: ParetoAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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 type:: RayleighAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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

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.

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 type:: StudentTAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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 type:: UniformAccumulatorFactory

estimate(nobs, suff_stat)[source]

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.

Parameters:

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

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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).

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]

classmethod compute_declaration()[source]

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=1.0 - 1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate mu and rho from the mean resultant (the first trigonometric moment).

Parameters:

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

accumulator_factory()[source]

Return type:: WrappedCauchyAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

WrappedCauchyDistribution

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]

classmethod compute_declaration()[source]

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 type:: ProjectedNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

ProjectedNormalDistribution

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]

classmethod compute_declaration()[source]

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=1.0e6, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate mu and sigma2 from the mean resultant (rho = exp(-sigma2/2)).

Parameters:

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

accumulator_factory()[source]

Return type:: WrappedNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

WrappedNormalDistribution

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]

static backend_log_density_from_params(x, mu, alpha, beta, engine)[source]

Engine-neutral generalized-Gaussian log-density: log_norm - (|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(beta_bounds=(0.25, 50.0), name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator: mu = mean, beta from excess kurtosis, alpha from variance.

Parameters:

beta_bounds (tuple[float, float])
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: GeneralizedGaussianAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 (-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]

classmethod compute_declaration()[source]

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 from explicit parameters (-inf for x <= 0).

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

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(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).

Parameters:

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

accumulator_factory()[source]

Return type:: NakagamiAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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

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(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).

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: RicianAccumulatorFactory

estimate(nobs, suff_stat)[source]

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).

Parameters:

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

accumulator_factory()[source]

Return type:: VonMisesAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

VonMisesDistribution

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]

classmethod compute_declaration()[source]

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]

classmethod compute_declaration()[source]

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 |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

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, 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.

Parameters:

loc (float)
pseudo_count (float | None)
min_scale (float)
xi_max (float)
xi_min (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: GeneralizedParetoAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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

Per-row GEV moment sums in accumulator order (sum, sum2, sum3, count).

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 |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:

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

Stacked GEV moment sums (sum, sum2, sum3, 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*(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

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, min_scale=1.0e-12, xi_max=1.0 / 3.0 - 1.0e-4, xi_min=-1.0, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for GEV location, scale and shape.

Parameters:

pseudo_count (float | None)
min_scale (float)
xi_max (float)
xi_min (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: GeneralizedExtremeValueAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple[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 type:: WeibullAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

WeibullDistribution

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]

compute_declaration()[source]

density(x)[source]

Evaluate density of heterogeneous mMixture distribution at observation x.

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]

What log_density returns relative to the true log-density (default: exact).

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]

Create HeterogeneousMixtureSampler for sampling from HeterogeneousMixtureDistribution instance.

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

estimator(pseudo_count=None)[source]

Create HeterogeneousMixtureEstimator for estimating HeterogeneousMixtureDistribution.

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]

Returns a HeterogeneousMixtureDataEncoder object for encoding sequences of iid observations from HeterogeneousMixtureDistribution.

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

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]

Returns HeterogeneousMixtureAccumulatorFactory object passing component StatisticAccumulatorFactory objects and keys.

Return type:: HeterogeneousMixtureAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate HeterogeneousMixtureDistribution from aggregated sufficient statistics.

Args suff_stat is a Tuple length two containing:: suff_stat[0] (np.ndarray): Sufficient statistic for the weights of the mixture components. suff_stat[1] (Tuple[T1,…,Tk]): Tuple of K sufficient statistics for the heterogeneous mixture components.

suff_stat[1] is passed to estimate() function of each corresponding entry in member variable ‘estimators’.

If fixed_weights is not None, suff_stat[0] is not used and the weights of the HeterogeneousMixtureDistribution: are set to fixed_weights.

If pseudo_count is passed, arg suff_stat[0] is aggregated with re-weighted member variable suff_stat. If member variable suff_stat is None, then the arg suff_stat[0] is re-weighted with pseudo_count to estimate the weights.

If pseudo_count is None, ar suff_stat[0] is used to estimate 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:

HeterogeneousMixtureDistribution object.

Return type:

HeterogeneousMixtureDistribution

class HeterogeneousMixtureEnumerator(dist)[source]

Bases: DistributionEnumerator

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 type:: HeterogeneousPCFGAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 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]

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]

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]

Create a HiddenAssociationSampler object from this distribution.

Requires non-null given_dist and len_dist.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: HiddenAssociationSampler object.
Return type:: HiddenAssociationSampler

estimator(pseudo_count=None)[source]

Create a HiddenAssociationEstimator from the component distributions’ estimators.

Parameters:: pseudo_count (Optional[float]) – Unused (kept for protocol consistency).
Returns:: HiddenAssociationEstimator object.
Return type:: HiddenAssociationEstimator

dist_to_encoder()[source]

Returns a HiddenAssociationDataEncoder object for encoding sequences of data.

Return type:: HiddenAssociationDataEncoder

class HiddenAssociationEstimator(cond_estimator, given_estimator=NullEstimator(), len_estimator=NullEstimator(), pseudo_count=None, name=None, keys=(None, None))[source]

Bases: ParameterEstimator

HiddenAssociationEstimator object for estimating a HiddenAssociationDistribution from aggregated sufficient statistics.

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]

Returns a HiddenAssociationAccumulatorFactory for creating HiddenAssociationAccumulator objects.

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]

state_posteriors(seq)[source]: The full smoothing posteriors gamma[t,k] = P(z_t = k | x).

seq_log_density(seqs)[source]

Return type:: ndarray

sampler(seed=None)[source]

fit(seqs, *, max_its=50, tol=1e-6, fast=True)[source]

EM (Baum-Welch) through the transition operator. Returns (fitted_hmm, loglik_trace).

fast=True uses the numba-jitted dense forward-backward (~30x over the numpy Python loop) when the transition is a plain DenseTransition with no terminal states; structured operators (low-rank / sparse / combinator) use the operator’s per-step accumulate as before.

Parameters:

max_its (int)
tol (float)
fast (bool)

dist_to_encoder()

estimator(pseudo_count=None)

log_density(x)

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]

estimate(nobs, suff_stat)[source]

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 cheap operators never materialize A.

n_states: int

forward(alpha)[source]

Parameters:: alpha (ndarray)
Return type:: ndarray

backward(v)[source]

Parameters:: v (ndarray)
Return type:: ndarray

as_matrix()[source]

Return type:: ndarray

new_accumulator()[source]

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]

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]

backward(v)[source]

as_matrix()[source]

new_accumulator()[source]

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).

estimate(acc)[source]

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]

backward(v)[source]

as_matrix()[source]

new_accumulator()[source]

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).

estimate(acc)[source]

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]

backward(v)[source]

as_matrix()[source]

new_accumulator()[source]

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).

estimate(acc)[source]

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]

backward(v)[source]

as_matrix()[source]

new_accumulator()[source]

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).

estimate(acc)[source]

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]

backward(v)[source]

as_matrix()[source]

new_accumulator()[source]

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).

estimate(acc)[source]

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).

fit(obs_seqs, input_seqs, *, max_its=50, tol=1e-6)[source]

Parameters:

max_its (int)
tol (float)

log_density(seq)[source]

dist_to_encoder()[source]

estimator(pseudo_count=None)[source]

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). The forward variable alpha_t(j) = P(obs_1:t, a segment ends at t in state j); the likelihood is sum_j alpha_T(j). Forward/EM are O(T * K * max_duration). Verified against brute-force segmentation.

forward_loglik(seq)[source]: Total log-likelihood log sum_j alpha_T(j) via the scaled explicit-duration forward.

fit(seqs, *, max_its=50, tol=1e-6)[source]

Baum-Welch (EM) for the explicit-duration HMM: re-estimates emissions, the per-state duration distributions, the (zero-diagonal) transition, and pi. Returns (fitted_hmm, loglik_trace).

Parameters:

max_its (int)
tol (float)

log_density(seq)[source]

seq_log_density(x)[source]

dist_to_encoder()[source]

estimator(pseudo_count=None)[source]

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’). final_states = the (k,1) sub-states require the last segment to COMPLETE, so the expanded forward log-likelihood EQUALS this EDHMM’s exactly. This hands the HSMM the full StructuredHMM read-out API – Viterbi (recover state+remaining-duration), posterior decoding, the standard forward – and, with len_dist, enumeration. O(K*D) states.

enumerator(len_dist)[source]: Enumerate observation sequences in descending marginal probability under this HSMM (complete final segment), given a len_dist over total sequence length. Built on the exact HMM expansion + the final-state best-first enumerator; .top_k(k) -> [(sequence, log_prob), …]. Needs discrete (Categorical) emissions and a Categorical-like len_dist.

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, duration) segments covering the sequence, O(T K D). The HSMM analog of Viterbi decoding.

sampler(seed=None)[source]

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.

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)

class HiddenMarkovModelDistribution(topics, w=MISSING, transitions=MISSING, taus=None, len_dist=NullDistribution(), name=None, terminal_values=None, use_numba=None, weights=MISSING, prior=None, terminal_states=None)[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)

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]

compute_declaration()[source]

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)|x_mat(0),…,x_mat(t-1)) = p_mat(x_mat(t)|Z(t))*p_mat(Z(t)|Z(t-1))*p_mat(Z(t-1)|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 vectorized log-density values for sequence-encoded observations.

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)[source]

Return vectorized posterior state probabilities for encoded observations.

Parameters:: x (tuple[tuple[ndarray, ndarray, ndarray], Any | None])
Return type:: list[ndarray] | None

viterbi(x)[source]

Return the most likely latent-state path for a single observation sequence.

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 Viterbi paths for sequence-encoded observation sequences.

Parameters:: x (tuple[tuple[ndarray, ndarray, ndarray], Any | None])

to_fisher(**kwargs)[source]: Forward-backward Fisher view for the HMM.

density_semantics()[source]

What log_density returns relative to the true log-density (default: exact).

sampler(seed=None)[source]

Create a HiddenMarkovSampler object with seed passed.

Note: Throws exception if ‘len_dist’and ‘terminal_values’ are not set.

If len_dist is set, it should be a SequenceEncodableProbabilityDistribution with data type int and support on non-negative integers.

Parameters:: seed (Optional[int]) – Set seed for random sampling.
Returns:: HiddenMarkovSampler object.
Return type:: HiddenMarkovSampler

estimator(pseudo_count=None)[source]

Create HiddenMarkovEstimator for estimating HiddenMarkovDistribution objects from aggregated sufficient: statistics.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight sufficient statistics of HiddenMarkovDistribution object instance.
Returns:: HiddenMarkovEstimator object.
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]

Returns HiddenMarkovDataEncoder object for encoding sequences of iid HMM observations.

Return type:: HiddenMarkovDataEncoder

enumerator()[source]

Returns HiddenMarkovModelEnumerator iterating 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

Parameters:

estimators (list[ParameterEstimator])
len_estimator (ParameterEstimator | None)
pseudo_count (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]: Returns an HiddenMarkovAccumulatorFactory object.

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

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=False, terminal_states=None)[source]

Bases: HiddenMarkovModelDistribution

Hidden Markov model distribution with quantized observation summaries.

Parameters:

theta (float)
levels (Sequence[Any])
transition_exponents (Sequence[Sequence[int]] | ndarray)
emission_exponents (Sequence[Sequence[int]] | ndarray)
initial_exponents (Sequence[int] | ndarray | None)
init_mode (str)
k_max (int | None)
len_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)
terminal_values (set | None)
use_numba (bool)
terminal_states (set[int] | Sequence[int] | None)

compute_declaration()[source]

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]

Create QuantizedHiddenMarkovEstimator matching this distribution’s 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]

Returns 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=True, split_nats=math.log(2.0))[source]

Bases: ParameterEstimator

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

HierarchicalMixtureDistribution object defining an outer mixture over sequence mixtures with shared topics.

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]

compute_declaration()[source]

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]

Returns a MixtureDistribution object created from object instance.

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]

What log_density returns relative to the true log-density (default: exact).

sampler(seed=None)[source]

Return HierarchicalMixtureSampler object created from attribute variables.

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

estimator(pseudo_count=None)[source]

Create an HierarchicalMixtureEstimator object from attributes variables.

Parameters:: pseudo_count (Optional[float]) – Re-weight sufficient statistics in estimation step of EM.
Returns:: HierarchicalMixtureEstimator object.
Return type:: HierarchicalMixtureEstimator

dist_to_encoder()[source]

Return an HierarchicalMixtureDataEncoder object for encoding sequences of iid 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

HierarchicalMixtureEstimator object for estimating a HierarchicalMixtureDistribution 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]

Create an HierarchicalMixtureEstimatorAccumulator from object instance.

Return type:: HierarchicalMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate HierarchicalMixtureDistribution from aggregated sufficient statistics.

Arg suff_stat is a Tuple of length 3 containing,: suff_stat[0] (ndarray[float]): Aggregated component counts with shape (num_mixtures, num_topics). suff_stat[1] (Tuple[SS1,…]): Tuple of ‘num_topics’ sufficient statistics for the topics. suff_stat[2] (Optional[SS2]): Optional sufficient statistic for length accumulator.

Parameters:

nobs (Optional[float]) – Number of observations used in accumulation of ‘suff_stat’.
suff_stat (tuple[ndarray, SS1, SS2 | None]) – See above for details.

Returns:

HierarchicalMixtureDistribution object.

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]

classmethod compute_declaration()[source]

density(x)[source]

Return the probability density or mass at a single observation.

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

density_semantics()[source]

What log_density returns relative to the true log-density (default: exact).

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 type:: IndianBuffetProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

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)[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[tuple[int, int | None]])
conditional_log_densities (Sequence[float] | ndarray)
feature_order (Sequence[int] | None)
name (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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 an IntegerChowLiuTreeSampler object from parameters of IntegerChowLiuTreeDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: IntegerChowLiuTreeSampler object.
Return type:: IntegerChowLiuTreeSampler

estimator(pseudo_count=None)[source]

Create an IntegerChowLiuTreeEstimator object.

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

dist_to_encoder()[source]

Returns an IntegerChowLiuTreeDataEncoder object for encoding sequences of data.

Return type:: IntegerChowLiuTreeDataEncoder

enumerator()[source]

Returns IntegerChowLiuTreeEnumerator iterating fixed-length integer vectors in descending probability order.

Return type:: IntegerChowLiuTreeEnumerator

class IntegerChowLiuTreeEstimator(num_features=None, num_states=None, pseudo_count=None, suff_stat=None, keys=None, name=None)[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)

accumulator_factory()[source]: Returns an IntegerChowLiuTreeAccumulatorFactory for creating IntegerChowLiuTreeAccumulator objects.

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)[source]

Bases: DistributionEnumerator

Enumerates the finite support of an integer Chow-Liu tree.

Parameters:: dist (IntegerChowLiuTreeDistribution)

class IgnoredDistribution(dist, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Distribution wrapper that assigns zero log-density while preserving an estimator interface.

Parameters:

dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)

compute_capabilities()[source]

compute_declaration()[source]

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=NullDistribution(), pseudo_count=None, suff_stat=None, keys=None, name=None)[source]

Bases: ParameterEstimator

Parameters:

dist (SequenceEncodableProbabilityDistribution | None)
pseudo_count (float | None)
suff_stat (Any | None)
keys (str | None)
name (str | None)

accumulator_factory()[source]

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]

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

IgnoredDistribution

class IntegerBernoulliEditDistribution(log_edit_pmat, init_dist=NullDistribution(), 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]

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

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 an IntegerBernoulliEditSampler object from this distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: IntegerBernoulliEditSampler object.
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:: IntegerBernoulliEditEstimator object.
Return type:: IntegerBernoulliEditEstimator

dist_to_encoder()[source]

Returns an IntegerBernoulliEditDataEncoder object for encoding sequences of data.

Return type:: IntegerBernoulliEditDataEncoder

enumerator()[source]

Returns IntegerBernoulliEditEnumerator iterating set-pairs in descending probability order.

Return type:: IntegerBernoulliEditEnumerator

class IntegerBernoulliEditEstimator(num_vals=MISSING, init_estimator=NullEstimator(), min_prob=1.0e-128, pseudo_count=None, suff_stat=None, name=None, keys=None, num_values=MISSING)[source]

Bases: ParameterEstimator

IntegerBernoulliEditEstimator object for estimating an IntegerBernoulliEditDistribution 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]

Returns an IntegerBernoulliEditAccumulatorFactory for creating IntegerBernoulliEditAccumulator objects.

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)[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. The step distribution does not carry the non-step keys plumbing.

Parameters:

log_edit_pmat (Sequence[tuple[float, float]] | ndarray)
init_dist (SequenceEncodableProbabilityDistribution | None)
name (str | None)

sampler(seed=None)[source]

Create an IntegerStepBernoulliEditSampler object from this distribution.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: IntegerStepBernoulliEditSampler object.
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:: IntegerStepBernoulliEditEstimator object.
Return type:: IntegerStepBernoulliEditEstimator

dist_to_encoder()[source]

Returns an IntegerStepBernoulliEditDataEncoder object for encoding sequences of data.

Return type:: IntegerStepBernoulliEditDataEncoder

enumerator()[source]

Returns IntegerStepBernoulliEditEnumerator iterating set-pairs in descending probability order.

Return type:: IntegerStepBernoulliEditEnumerator

class IntegerStepBernoulliEditEstimator(num_vals=MISSING, init_estimator=NullEstimator(), min_prob=1.0e-128, pseudo_count=None, suff_stat=None, name=None, keys=None, num_values=MISSING)[source]

Bases: IntegerBernoulliEditEstimator

IntegerStepBernoulliEditEstimator object for estimating an IntegerStepBernoulliEditDistribution from aggregated sufficient statistics, with a two-level step fit to the edit probabilities.

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]

Returns an IntegerStepBernoulliEditAccumulatorFactory for creating accumulator objects.

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=False)[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)

compute_capabilities()[source]: Return backend capability metadata for this concrete integer association model.

compute_declaration()[source]

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]

Create an IntegerHiddenAssociationSampler object from this distribution.

Requires non-null prev_dist and len_dist.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: IntegerHiddenAssociationSampler object.
Return type:: IntegerHiddenAssociationSampler

estimator(pseudo_count=None)[source]

Create an IntegerHiddenAssociationEstimator with matching dimensions and component estimators.

Parameters:: pseudo_count (Optional[float]) – Unused (kept for protocol consistency).
Returns:: IntegerHiddenAssociationEstimator object.
Return type:: IntegerHiddenAssociationEstimator

dist_to_encoder()[source]

Returns an IntegerHiddenAssociationDataEncoder object for encoding sequences of data.

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

IntegerHiddenAssociationEstimator object for estimating an IntegerHiddenAssociationDistribution from aggregated sufficient statistics.

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]

Returns an IntegerHiddenAssociationAccumulatorFactory for creating accumulator objects.

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]

compute_declaration()[source]

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.

Consider a sequence of length n > 0 s.t. x = (x[0],x[1],…,x[n-1]). With lag > 0, we have log-density given by:

log(P(x)) = log(P_init(x[0:lag]) + sum_{j=0}^{n-1} log(p_mat(x[j + lag] | x[j], x[j+1],..,x[j+lag-1])) +
log(P_len(n)),

where P_len(n) is the density for the length distribution evaluated for length ‘n’, and P_init() is the density for the initial distribution. If the sequence length is less than the lag, i.e. len(x) < lag, then

log(P(x)) = log(P_len(n)).

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]): Lengths of chains - lag. If less than lag length is 0. 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 legacy (transition_counts, initial_stat, length_stat) 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]

Returns an IntegerMarkovChainSampler object.

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

estimator(pseudo_count=None)[source]

Returns an IntegerMarkovChainEstimator object.

Parameters:: pseudo_count (float | None)

dist_to_encoder()[source]

Returns an IntegerMarkovChainDataEncoder object for encoding sequences of 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

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)

accumulator_factory()[source]

Returns an IntegerMarkovChainAccumulatorFactory object from attributes values.

Return type:: IntegerMarkovChainAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate IntegerMarkovChainDistribution object from aggregated sufficient statistics in arg ‘suff_stat’.

Arg ‘suff_stat’ is a Tuple of length 3 containing:: suff_stat[0] (Dict[Tuple[Tuple[int, …], int], float]): Dictionary mapping state transition counts. suff_stat[1] (Optional[SS1]): Optional sufficient statistics for init accumulator of type SS1. suff_stat[2] (Optional[SS2]): Optional sufficient statistics for length accumulator of type SS2.

Parameters:

nobs (Optional[float]) – Number of observations used in aggregation of ‘suff_stat’.
suff_stat (tuple[dict[tuple[tuple[int, ...], int], float], SS1 | None, SS2 | None]) – 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 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]

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 an IntegerProbabilisticLatentSemanticIndexingSampler object from IntegerProbabilisticLatentSemanticIndexingDistribution instance.

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

estimator(pseudo_count=None)[source]

Create an IntegerProbabilisticLatentSemanticIndexingEstimator object from IntegerProbabilisticLatentSemanticIndexingDistribution instance.

Parameters:: pseudo_count (Optional[float]) – Re-weight object instance sufficient statistics when passed to estimator.
Returns:: IntegerProbabilisticLatentSemanticIndexingEstimator object.
Return type:: IntegerProbabilisticLatentSemanticIndexingEstimator

dist_to_encoder()[source]

Returns IntegerProbabilisticLatentSemanticIndexingDataEncoder object.

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

Parameters:

num_vals (int)
num_states (int)
num_docs (int)
len_estimator (ParameterEstimator | None)
pseudo_count (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]

Returns IntegerProbabilisticLatentSemanticIndexingAccumulatorFactory object.

Return type:: IntegerProbabilisticLatentSemanticIndexingAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate IntegerProbabilisticLatentSemanticIndexingDistribution from aggregated sufficient statistics in arg ‘suff_stat’.

Parameters:

nobs (Optional[float]) – Optional number of observations used to accumulate ‘suff_stat’.
suff_stat (tuple[ndarray, ndarray, ndarray, SS1 | None]) – See above for details.

Returns:

IntegerProbabilisticLatentSemanticIndexingDistribution object.

Return type:

IntegerProbabilisticLatentSemanticIndexingDistribution

class IntegerUniformSpikeDistribution(k, num_vals, p, min_val=0, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

IntegerUniformSpikeDistribution object: uniform over an integer range with a spike of mass p at k.

Parameters:

k (int)
num_vals (int)
p (float)
min_val (int | None)
name (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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

IntegerUniformSpikeEstimator object for estimating IntegerUniformSpikeDistribution objects from 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]

compute_declaration()[source]

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 log h = 0 for observations whose values are all in support, -inf otherwise.

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.

Un-normalized log-density given by

log(p_mat(x)) = sum_k x_k*log(p_k), for x having k integer categories.

Note: x has k integer values and p_k denotes the probability of success for integer-category x_k. The multinomial coefficient is intentionally omitted (see the module docstring), so this is a per-category scoring form, not a normalized mass over count vectors.

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 an IntegerMultinomialSampler object for sampling from integer multinomial.

Parameters:: seed (Optional[int]) – Set seed on random number generator used in sampling.
Returns:: IntegerMultinomialSampler object.
Return type:: IntegerMultinomialSampler

estimator(pseudo_count=None)[source]

Create and IntegerMultinomialEstimator object for estimating IntegerMultinomialDistribution from aggregated: sufficient statistics.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight sufficient statistics of object instance when estimated.
Returns:: IntegerMultinomialEstimator object.
Return type:: IntegerMultinomialEstimator

dist_to_encoder()[source]

Returns IntegerMultinomialDataEncoder object with len_encoder created from len_dist.

Return type:: IntegerMultinomialDataEncoder

enumerator()[source]

Returns IntegerMultinomialEnumerator iterating count vectors in descending log-density order.

Return type:: IntegerMultinomialEnumerator

class DirichletMultinomialDistribution(alpha, n, name=None, keys=None)[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)

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 or the total is not n).

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

seq_log_density(x)[source]

Vectorized log-mass for a stack of count vectors, shape (N, K).

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

class DirichletMultinomialEstimator(dim, n, max_iter=500, tol=1.0e-9, name=None, keys=None)[source]

Bases: ParameterEstimator

Minka fixed-point maximum-likelihood estimator for the Dirichlet-multinomial concentration.

Parameters:

dim (int)
n (int)
max_iter (int)
tol (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: DirichletMultinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

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

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]

Create an IntegerMultinomialAccumulatorFactory object from IntegerMultinomialEstimator object instance.

Return type:: IntegerMultinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an IntegerMultinomialDistribution from aggregated sufficient statistics in arg ‘suff_stat’.

Note: If pseudo_count is not set, member sufficient statistics are ignored in estimation.

Arg ‘suff_stat’ contains:: suff_stat[0] (int): A minimum value for aggregated counts. suff_stat[1] (np.ndarray): Numpy array of aggregated counts. suff_stat[2] (Optional[SS0]): Optional sufficient statistics for the length accumulator with type SS0.

Parameters:

nobs (Optional[float]) – Number of observations in accumulated data.
suff_stat (tuple[int, ndarray, SS0 | None]) – See above for details.

Returns:

IntegerMultinomialDistribution object.

Return type:

IntegerMultinomialDistribution

class IntegerMultinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates integer count vectors (lists of (category, count) pairs) in descending log-density order.

Parameters:: dist (IntegerMultinomialDistribution)

class IntegerCategoricalDistribution(min_val, p_vec=MISSING, name=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)
prob_vec (list[float] | ndarray)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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}] - log(1 + default_value). 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]

IntegerCategoricalSampler object for sampling from IntegerCategoricalDistribution instance.

Parameters:: seed (Optional[int]) – Set seed for drawing random samples.
Returns:: IntegerCategoricalSampler object.
Return type:: IntegerCategoricalSampler

estimator(pseudo_count=None)[source]

IntegerCategoricalEstimator object from instance of IntegerCategoricalDistribution object.

If pseudo_count is not None, pass min_val and p_vec as sufficient statistics for aggregated estimaton.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight sufficient statistics of IntegerCategoricalDistribution instance in estimation.
Returns:: IntegerCategoricalEstimator object.
Return type:: IntegerCategoricalEstimator

dist_to_encoder()[source]

Return IntegerCategoricalDataEncoder object for encoding sequences of 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

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]

Returns IntegerCategoricalAccumulatorFactory object from member sufficient statistics of: IntegerCategoricalEstimator.

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 IntegerCategoricalDistribution object from aggregating sufficient statistics.

Arg ‘suff_stat’ is a Tuple of int and np.ndarray[float],: suff_stat[0] (int): Minimum value of the integer categorical distribution, suff_stat[1] (ndarray[float]): Probabilities for each integer observation in range [suff_stat[0], suff_stat[0] + len(suff_stat[1])-1).

Arg suff_stat is aggregated sufficient statistics obtained from observations of integer categorical data, that is used to estimate the integer categorical distribution. If pseudo_count is not None, the integer categorical is estimated by a combing arg suff_stat and a re-weighted member variable ‘suff_stat’.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[int, ndarray] | None)

Returns:

IntegerCategoricalDistribution object.

Return type:

IntegerCategoricalDistribution

class IntegerCategoricalEnumerator(dist)[source]

Bases: DistributionEnumerator

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]

classmethod compute_declaration()[source]

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

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

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 type:: IntegerBernoulliSetAccumulatorFactory

estimate(nobs, suff_stat=None)[source]

Parameters:

nobs (float | None)
suff_stat (ndarray | None)

Return type:

IntegerBernoulliSetDistribution

class IntegerBernoulliSetEnumerator(dist)[source]

Bases: DistributionEnumerator

Parameters:: dist (IntegerBernoulliSetDistribution)

class JointMixtureDistribution(components1, components2, w1, w2, taus12, taus21, keys=(None, None, None), name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

JointMixtureDistribution object defining a joint mixture over paired observations.

Data type: Tuple[T0, T1], where T0 and T1 are the data types of the components for X1 and X2.

Parameters:

components1 (Sequence[SequenceEncodableProbabilityDistribution])
components2 (Sequence[SequenceEncodableProbabilityDistribution])
w1 (Sequence[float] | np.ndarray)
w2 (Sequence[float] | np.ndarray)
taus12 (list[list[float]] | np.ndarray)
taus21 (list[list[float]] | np.ndarray)
keys (tuple[str | None, str | None, str | None] | None)
name (str | None)

compute_capabilities()[source]

compute_declaration()[source]

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]

What log_density returns relative to the true log-density (default: exact).

sampler(seed=None)[source]

Create a JointMixtureSampler object for sampling from this distribution.

Parameters:: seed (Optional[int]) – Seed for the random number generator used in sampling.
Returns:: JointMixtureSampler object.
Return type:: JointMixtureSampler

estimator(pseudo_count=None)[source]

Create a JointMixtureEstimator object from the components of this distribution.

Parameters:: pseudo_count (Optional[float]) – If passed, used to re-weight the state counts in estimation.
Returns:: JointMixtureEstimator object.
Return type:: JointMixtureEstimator

dist_to_encoder()[source]

Return a JointMixtureDataEncoder object for encoding sequences of iid observations.

Return type:: DataSequenceEncoder

enumerator()[source]

Returns a JointMixtureEnumerator iterating (X1, X2) 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

JointMixtureEstimator object for estimating a JointMixtureDistribution from sufficient statistics.

Parameters:

estimators1 (Sequence[ParameterEstimator])
estimators2 (Sequence[ParameterEstimator])
suff_stat (tuple[np.ndarray, np.ndarray, np.ndarray, tuple[E0, ...], tuple[E1, ...]] | None)
pseudo_count (tuple[float, float, float] | None)
keys (tuple[str | None, str | None, str | None] | None)
name (str | None)

accumulator_factory()[source]

Returns a JointMixtureEstimatorAccumulatorFactory object from attribute variables.

Return type:: JointMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a Joint mixture distribution from aggregated sufficient statistics.

suff_stat is a Tuple containing:: suff_stat[0] (np.ndarray): Component counts for outer mixture. suff_stat[1] (np.ndarray): Component counts for the inner mixture. suff_stat[2] (np.ndarray): Component counts for the comps of inner mix given an outer mix component. suff_stat[3] (Tuple[E0,…]): Suff-stats for outer comps suff_stat[4] (Tuple[E1,…]): Suff-stats for the inner comps.

Parameters:

nobs (Optional[float]) – Weighted number of observations used in aggregation of suff_stats.
suff_stat (tuple[ndarray, ndarray, ndarray, tuple[E0, ...], tuple[E1, ...]]) – See above for details.

Returns:

JointMixtureDistribution object.

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, 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)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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 an LogGaussianSampler object from parameters of LogGaussianDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: LogGaussianSampler object.
Return type:: LogGaussianSampler

estimator(pseudo_count=None)[source]

Create LogGaussianEstimator from attribute variables.

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

dist_to_encoder()[source]

Returns a LogGaussianDataEncoder object for encoding sequences of data.

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

Parameters:

pseudo_count (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 LogGaussianDistribution object from sufficient statistics aggregated from data.

Arg passed suff_stat is tuple of four floats:: suff_stat[0] (float): Sum of weighted observations (sum_i w_i*log(X_i)), suff_stat[1] (float): Sum of weighted observations (sum_i w_i*log(X_i)^2), suff_stat[2] (float): Sum of weighted observations (sum_i w_i), suff_stat[3] (float): Sum of weighted observations (sum_i w_i),

obtained from aggregation of observations.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[float, float, float, float]) – See above for details.

Returns:

LogGaussianDistribution object.

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]

compute_declaration()[source]

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 per-component legacy (initial_counts, transition_counts, length_stat) 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[Any, …]

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]

Create MarkovChainSampler from MarkovChainDistribution instance.

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

estimator(pseudo_count=None)[source]

Create MarkovChainEstimator from instance of MarkovChainDistribution object.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight the sufficient statistics of MarkovChainDistribution.
Returns:: MarkovChainEstimator object.
Return type:: MarkovChainEstimator

dist_to_encoder()[source]

Create MarkovChainDataEncoder object for encoding sequences of MarkovChainDistribution observations.

Note: len_encoder is passed as NullDataEncoder() if len_dist is not to be estimated.

Returns:: MarkovChainDataEncoder object.
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 MarkovChainEstimator(pseudo_count=None, levels=None, len_estimator=NullEstimator(), name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

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 (tuple[dict[T, float], dict[T, dict[T, float]], Any | None]) – 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’.

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 (tuple[dict[T, float], dict[T, dict[T, float]], Any | None]) – 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 (tuple[dict[T, float], dict[T, dict[T, float]], Any | None]) – Seed above for details.

Returns:

MarkovChainDistribution object.

Return type:

MarkovChainDistribution

class MarkovChainEnumerator(dist)[source]

Bases: DistributionEnumerator

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]

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 type:: ProbabilisticPCAAccumulatorFactory

estimate(nobs, suff_stat)[source]

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

MixtureDistribution object defined by component distributions and weights.

The args components (Sequence[SequenceEncodableProbabilityDistribution]) define the component distributions of the mixture distribution as well as the data type. The data type of the MixtureDistribution object is taken to be the data type (T) of the component distributions (all must be the same subclass of SequenceEncodableProbabilityDistribution super class).

Parameters:

components (Sequence[SequenceEncodableProbabilityDistribution]) – Set component distributions. Must be same subclass of SequenceEncodableProbabilityDistribution super class with type T.
w (ndarray[float]) – Mixture weights, must sum to 1.0.
name (Optional[str]) – Assign string name to MixtureDistribution object.
weights (np.ndarray | list[float])
prior (SequenceEncodableProbabilityDistribution | None)

components

List of component distributions (data type T).

Type:: List[SequenceEncodableProbabilityDistribution]

w

Mixture weights assigned from args (w).

Type:: ndarray[float]

name

String name to MixtureDistribution object.

Type:: Optional[str]

zw

True if a weight is 0.0, else False.

Type:: ndarray[bool]

log_w

Log of weights (w). set to -np.inf, where zw is True.

Type:: ndarray[float]

num_components

Number of components in MixtureDistribution instance.

Type:: int

compute_capabilities()[source]

compute_declaration()[source]

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]

Variational expected log-density at observation x.

Uses E[log w_k] under the (symmetric) Dirichlet weight prior together with each component’s expected_log_density. Falls back to the plug-in log_density(x) when no conjugate weight prior is attached.

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

seq_expected_log_density(x)[source]

Vectorized variational expected log-density at sequence-encoded input x.

Falls back to seq_log_density(x) when no conjugate weight prior is attached.

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

density(x)[source]

Evaluate density of Mixture distribution at observation x.

See log_density() for details.

Parameters:: x (T) – (T): Single observation from mixture distribution. T is data type of components.
Returns:: Density at x.
Return type:: float

density_semantics()[source]

What log_density returns relative to the true log-density (default: exact).

log_density(x)[source]

Evaluate log-density of Mixture distribution at observation x.

A K-component Mixture has log-density,

log(P(x)) = log(sum_{z=k}^{K} P(x|z=k)*P(z=k)),

where P(x|z=k) is component-k log-density at x, and P(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).

Parameters:: x (T) – (T): Single observation from mixture distribution. T is data type of components.
Returns:: Log-density at x.
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]

Evaluate component-wise log-density of Mixture distribution at observation x.

A K-component Mixture has log-density, log(P(x|z=k)) for the K-th component.

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 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 mixture distribution. T is data type of components.
Returns:: Numpy array of floats containing posterior distribution at observation x.
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 sequence encoded from MixtureDataEncoder.seq_encode(data) with data type Sequence[T] for data, or results from an equivalent encoding from a DataSequenceEncoder object for the components. The resulting encoded sequence is assumed to be data type T1.

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 (T1) – 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

seq_log_density(x)[source]

Vectorized evaluation of log-density for encoded sequence x.

Evaluates the log-density of each observation in the encoded sequence x (see log_density() 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.

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 (T1) – See above for details.
Returns:: Numpy array of floats containing the log_density of each observation in encoded sequence.
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]

Vectorized evaluation of posterior of MixtureDistribution for encoded sequence x.

Vectorized evaluation the posterior of each observation in the encoded sequence x (see posterior() for details).

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 (T1) – See above for details.
Returns:: Numpy array of floats containing the posterior of each observation in encoded sequence.
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]

Create MixtureSampler for sampling from MixtureDistribution instance.

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

estimator(pseudo_count=None)[source]

Create MixtureEstimator for estimating MixtureDistribution.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics in estimation.
Returns:: MixtureEstimator object.
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]

Returns a MixtureDataEncoder object for encoding sequences of iid observations from MixtureDistribution.

Return type:: MixtureDataEncoder

enumerator()[source]

Returns a MixtureEnumerator iterating the union of component supports in descending mixture probability order.

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 drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

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 type:: ResponsibilityAttentionAccumulatorFactory

estimate(nobs, suff_stat)[source]

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.

Honest 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)[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)

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

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

Variational-EM estimator; holds the embedding posterior + Adam state across EM iterations.

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 type:: VariationalEmbeddingAttentionAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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

log_density(x)[source]

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

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

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded 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 drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

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 type:: ChainedAttentionAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: ChainedAttentionDistribution

class VariationalMultiHopAttentionDistribution(mean, log_var, emission, sigma2=0.3, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A 2-hop chain over tied latent embeddings (mean-field posterior).

Parameters:

sigma2 (float)
name (str | None)

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Return type:: float

log_density(x)[source]

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

Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded 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 type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

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

Variational-EM estimator with prior annealing (KL weight ramped over EM iterations).

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]

estimate(nobs, suff_stat)[source]

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

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

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

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

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]

Returns MixtureAccumulatorFactory object passing component StatisticAccumulatorFactory objects and keys.

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 MixtureDistribution from aggregated sufficient statistics.

Args suff_stat is a Tuple length two containing:: suff_stat[0] (np.ndarray): Sufficient statistic for the weights of the mixture components. suff_stat[1] (Tuple[T2, …]): A tuple of length K (number of mixture components), containing the

sufficient statistics of each mixture component of data type T2.
If fixed_weights is not None, suff_stat[0] is not used and the weights of the MixtureDistribution are set to: fixed_weights.

If pseudo_count is None, ar suff_stat[0] is used to estimate the wieghts.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator super class.
suff_stat (tuple[ndarray, tuple[Any, ...]]) – See above for details.

Returns:

MixtureDistribution object.

Return type:

MixtureDistribution

class MixtureEnumerator(dist)[source]

Bases: DistributionEnumerator

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]

classmethod compute_declaration()[source]

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]

Create a MultivariateGaussianSampler for sampling from this distribution.

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

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 the dimensions keep (Gaussian marginals just drop rows).

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]

Create a MultivariateGaussianEstimator for estimating this distribution.

If pseudo_count is passed, the current mean and covariance are used to regularize the estimate.

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

dist_to_encoder()[source]

Returns a MultivariateGaussianDataEncoder object for encoding sequences of iid 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)[source]

Bases: ParameterEstimator

MultivariateGaussianEstimator object for estimating a multivariate normal distribution from aggregated sufficient statistics.

Parameters:

dim (int | None)
pseudo_count (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)

accumulator_factory()[source]

Returns a MultivariateGaussianAccumulatorFactory built from the estimator’s attributes.

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

Place-holder distribution assigning density 1.0 (log-density 0.0) to any observation (Any data type).

Parameters:: name (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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

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]

Create a NullSampler object.

Parameters:: seed (Optional[int]) – Seed for random number generator (unused).
Returns:: NullSampler object.
Return type:: NullSampler

estimator(pseudo_count=None)[source]

Create a NullEstimator object.

Parameters:: pseudo_count (Optional[float]) – Kept for interface consistency (has no effect on estimation).
Returns:: NullEstimator object.
Return type:: NullEstimator

dist_to_encoder()[source]

Returns a NullDataEncoder object for encoding sequences of data.

Return type:: NullDataEncoder

enumerator()[source]

Returns a NullEnumerator object enumerating the support of the NullDistribution.

Return type:: NullEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build the single-item bounded bit-quantized index for NullDistribution.

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 null distributions.

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 null distributions.

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]

Returns a NullAccumulatorFactory for creating NullAccumulator objects.

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 object.

Return type:

NullDistribution

class NullEnumerator(dist)[source]

Bases: DistributionEnumerator

Yields the single value None with probability one, matching NullSampler.sample().

Parameters:: dist (NullDistribution)

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]

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]

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]

What log_density returns relative to the true log-density (default: exact).

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

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 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]

Parameters:

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

Return type:

OptionalDistribution

class OptionalEnumerator(dist)[source]

Bases: DistributionEnumerator

Parameters:: dist (OptionalDistribution)

class PoissonDistribution(lam, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Poisson distribution over non-negative integer counts with rate lam.

Parameters:

lam (float)
name (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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

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]

Create PoissonSampler object with PoissonDistribution instance and seed (Optional[int]) passed.

Parameters:: seed (Optional[int]) – Optional seed for random number generator used in sampling.
Returns:: PoissonSampler object.
Return type:: PoissonSampler

estimator(pseudo_count=None)[source]

Creates PoissonEstimator object.

Parameters:: pseudo_count (Optional[float]) – If passed, used to re-weight summary statistic lam from PoissonDistribution instance.
Returns:: PoissonEstimator object.
Return type:: PoissonEstimator

dist_to_encoder()[source]

Return PoissonDataEncoder object.

Return type:: PoissonDataEncoder

enumerator()[source]

Returns PoissonEnumerator iterating the support {0, 1, …} 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

Parameters:

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

accumulator_factory()[source]

Return PoissonAccumulatorFactory object with name and keys passed.

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 lambda of PoissonDistribution from aggregated sufficient statistcs suff_stat.

Arg passed suff_stat is a Tuple of two floats containing:: suff_stat[0] (float): Aggregated sum of observation weights, suff_stat[1] (float): Aggregated sum of weighted observations.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[float, float]) – See above for details.

Returns:

PoissonDistribution object.

Return type:

PoissonDistribution

class PoissonEnumerator(dist)[source]

Bases: DistributionEnumerator

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]

classmethod compute_declaration()[source]

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 type:: PointMassAccumulatorFactory

estimate(nobs, suff_stat=None)[source]

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)

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]

compute_declaration()[source]

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[list[tuple[Any, 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]: Fisher view for the select combinator.

sampler(seed=None)[source]

Creates a SelectSampler object for sampling from the child distributions.

Parameters:: seed (Optional[int]) – Seed for the random number generator used in sampling.
Returns:: SelectSampler object.
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]

Creates a SelectDataEncoder object for encoding sequences of SelectDistribution data.

Returns:: SelectDataEncoder object.
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)

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 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]

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]

density(x)[source]

Evaluate the density of SequenceDistribution at observed sequence x.

Assume x is a Sequence of data type T with length n > 0. Assume P_dist() is the density for the base distribution with data type T of SequenceDistribution, and P_len() is the length distribution with data type int. Then,

P(x) = P_dist(x[0])*…*P_dist(x[n-1])*P_len(n), if len_normalize is False,

or,

P(x) = (P_dist(x[0])*…*P_dist(x[n-1])*P_len(n))^(1/n) if len_normalize is True.

Parameters:: x (Sequence[T]) – Sequence of iid observations from base distribution of SequenceDistribution.
Returns:: Density evaluated at observation x.
Return type:: float

density_semantics()[source]

What log_density returns relative to the true log-density (default: exact).

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 SequenceSampler object from instance of SequenceDistribution.

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]

Create SequenceEstimator from instance of SequenceDistribution with pseudo_count passed if not None.

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]

Create SequenceDataEncoder for encoding sequences of iid observations of SequenceDistribution.

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 SequenceEstimator(estimator, len_estimator=NullEstimator(), len_dist=NullDistribution(), len_normalized=False, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

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]

Parameters:

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

Return type:

SequenceDistribution

class SequenceEnumerator(dist)[source]

Bases: DistributionEnumerator

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-density or log-mass at a single observation.

Parameters:: x (list[Any])
Return type:: float

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: ScheduledHMMDataEncoder

class ScheduledHMMEstimator(n_states, schedule, emission_estimator, len_estimator=None, pseudo_count=1e-8, name=None)[source]

Bases: ParameterEstimator

EM estimator for a ScheduledHiddenMarkovModelDistribution with a fixed schedule.

emission_estimator is the estimator for ONE emission distribution (reused for every phase x state); len_estimator (optional) estimates the length distribution. The schedule is fixed (it defines the parameter sharing); only the per-phase parameters are learned.

Parameters:

n_states (int)
schedule (PhaseSchedule)
emission_estimator (Any)
len_estimator (Any)
pseudo_count (float)
name (str | None)

accumulator_factory()[source]

Return type:: ScheduledHMMAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

Return type:

ScheduledHiddenMarkovModelDistribution

class Homogeneous[source]

Bases: PhaseSchedule

One phase for everything – the ordinary time-homogeneous HMM.

n_phases: int = 1

phase(t, length)[source]

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

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]

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

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]

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

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]

Parameters:

t (int)
length (int)

Return type:

to_dict()[source]

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]

compute_declaration()[source]

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 (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 type:: SegmentalHiddenMarkovAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

classmethod compute_declaration()[source]

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 object 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 BernoulliSetSampler object from parameters of BernoulliSetDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: BernoulliSetSampler object.
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:: BernoulliSetEstimator object.
Return type:: BernoulliSetEstimator

dist_to_encoder()[source]

Returns a BernoulliSetDataEncoder object for encoding sequences of data.

Return type:: BernoulliSetDataEncoder

enumerator()[source]

Returns BernoulliSetEnumerator iterating subsets of the support in descending probability order.

Return type:: BernoulliSetEnumerator

class BernoulliSetEstimator(min_prob=1.0e-128, pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

BernoulliSetEstimator object for estimating a BernoulliSetDistribution 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)

accumulator_factory()[source]

Returns a BernoulliSetAccumulatorFactory for creating BernoulliSetAccumulator objects.

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

SparseMarkovAssociationDistribution object modeling a 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]

Engine-routed sparse-association scoring.

The conditional probabilities for the observed word pairs are gathered host-side from the SciPy sparse matrix; the smoothing p*b + a, the logs, and the segment-sum reductions (initial-state and association terms) run on the active engine via index_add. Falls back to the engine-lifted NumPy path for the low-memory encoding that lacks the flat pair index.

Return type:: Any

sampler(seed=None)[source]

Create a SparseMarkovAssociationSampler object from this instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: SparseMarkovAssociationSampler object.
Return type:: SparseMarkovAssociationSampler

estimator(pseudo_count=None)[source]

Create a SparseMarkovAssociationEstimator object from this instance.

Parameters:: pseudo_count (Optional[float]) – Kept for protocol compatibility (unused).
Returns:: SparseMarkovAssociationEstimator object.
Return type:: SparseMarkovAssociationEstimator

dist_to_encoder()[source]

Returns a SparseMarkovAssociationDataEncoder object for encoding sequences of data.

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

SparseMarkovAssociationEstimator object for estimating SparseMarkovAssociationDistribution objects.

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]

Returns a SparseMarkovAssociationAccumulatorFactory object for this estimator.

Return type:: SparseMarkovAssociationAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate SparseMarkovAssociationDistribution objects 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)[source]

Bases: SequenceEncodableProbabilityDistribution

Spearman ranking distribution over permutations of 0,…,K-1 with location sigma and decay rate rho.

Data type: List[int] (a permutation of the integers 0,1,…,K-1).

Parameters:

sigma (Sequence[float] | ndarray)
rho (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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, sigma, rho, log_const, engine)[source]

Engine-neutral Spearman ranking log-density from fitted parameters.

Parameters:

x (Any)
sigma (Any)
rho (Any)
log_const (Any)
engine (Any)

Return type:

density(x)[source]

Density of Spearman ranking distribution at observation x.

See log_density() for details.

Parameters:: x (List[int]) – Permutation of the integers 0,1,…,K-1.
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of Spearman ranking distribution at observation x.

The log-density is given by

log(p(x; rho, sigma)) = -rho * ||x - sigma||^2 - log_const,

where log_const normalizes over all K! permutations.

Parameters:: x (List[int]) – Permutation of the integers 0,1,…,K-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.

Parameters:: x (np.ndarray) – 2-d numpy array of N permutations with K 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 permutations.

Parameters:

x (ndarray)
engine (Any)

Return type:

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for equal-dimensional Spearman ranking mixtures.

Parameters:

dists (Sequence[SpearmanRankingDistribution])
engine (Any)

Return type:

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

Return an (n, k) matrix of Spearman ranking 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_rank_sum) statistics.

Parameters:

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

Return type:

sampler(seed=None)[source]

Create a SpearmanRankingSampler object from parameters of SpearmanRankingDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: SpearmanRankingSampler object.
Return type:: SpearmanRankingSampler

estimator(pseudo_count=None)[source]

Create a SpearmanRankingEstimator with matching dimension and concentration rho.

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

dist_to_encoder()[source]

Returns a SpearmanRankingDataEncoder object for encoding sequences of data.

Return type:: SpearmanRankingDataEncoder

enumerator()[source]

Returns SpearmanRankingEnumerator iterating permutations in descending probability order.

Return type:: SpearmanRankingEnumerator

class SpearmanRankingEstimator(dim, rho=None, pseudo_count=None, suff_stat=None, name=None, keys=None, max_rho=1.0e6)[source]

Bases: ParameterEstimator

Estimator for the SpearmanRankingDistribution from aggregated sufficient statistics.

The consensus ranking sigma and, by default, the concentration rho are estimated by maximum likelihood. Pass a numeric rho to hold the concentration fixed.

Parameters:

dim (int)
rho (float | None)
pseudo_count (float | None)
suff_stat (tuple[float, ndarray] | None)
name (str | None)
keys (str | None)
max_rho (float)

accumulator_factory()[source]

Returns a SpearmanRankingAccumulatorFactory for creating SpearmanRankingAccumulator objects.

Return type:: SpearmanRankingAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a SpearmanRankingDistribution from sufficient statistics.

The consensus ranking sigma is the maximum likelihood estimate, given by the rank order (argsort) of the component-wise rank sums. When rho is None, the concentration is the nonnegative MLE satisfying E_rho[||X-sigma||^2] = observed mean squared distance. If no data was observed, rho is set to 0.0.

Parameters:

nobs (Optional[float]) – Number of observations (unused).
suff_stat (Tuple[float, np.ndarray]) – Tuple of count and component-wise rank sums.

Returns:

SpearmanRankingDistribution object.

Return type:

SpearmanRankingDistribution

class SpearmanRankingEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate permutations in descending Spearman probability order, lazily.

The Spearman distance sum_i (x_i - sigma_i)^2 is a linear assignment cost (assigning value j to position i costs (j - sigma_i)^2), so descending probability is increasing assignment cost: Murty’s k-best assignment streams the permutations in order without materializing the K! support.

Parameters:: dist (SpearmanRankingDistribution)

class KnowledgeGraphDistribution(entity_embeddings, relation_embeddings, name=None, keys=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)

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 the log-density or log-mass at a single observation.

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: KnowledgeGraphDataEncoder

class KnowledgeGraphEstimator(num_entities, num_relations, dim=16, lr=0.5, epochs=100, batch_size=256, weight_decay=1.0e-4, init_scale=0.3, max_norm=1.0, directions=('tail', 'head', 'relation'), negatives=None, seed=1, pseudo_count=None, name=None, keys=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)

accumulator_factory()[source]

Return type:: KnowledgeGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

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)[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)

classmethod compute_capabilities()[source]

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.

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

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.

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 type:: PlackettLuceAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 MallowsDistribution(sigma0, theta=1.0, name=None, keys=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)

classmethod compute_capabilities()[source]

kendall_distance(x)[source]

Return the Kendall tau distance between ordering x and the central permutation.

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

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, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for the Mallows central permutation (Copeland aggregation) and dispersion theta.

Parameters:

dim (int)
theta (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: MallowsAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 GeneralizedMallowsDistribution(sigma0, theta=1.0, metric='kendall', name=None, keys=None, n_mc=20000, seed=0, max_exact=16, max_enum=9)[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)

classmethod compute_capabilities()[source]

distance(x)[source]

Distance between ordering x and the central permutation under this metric.

Parameters:: x (Sequence[int])
Return type:: int

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

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

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

Return the data encoder used by this distribution for 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)[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)

accumulator_factory()[source]

Return type:: GeneralizedMallowsAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: GeneralizedMallowsDistribution

class GeneralizedMallowsModelDistribution(sigma0, theta=None, name=None, keys=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)

classmethod compute_capabilities()[source]

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

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

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: GeneralizedMallowsModelDataEncoder

class GeneralizedMallowsModelEstimator(dim, reservoir=10000, name=None, keys=None)[source]

Bases: ParameterEstimator

Copeland consensus for sigma0 and a per-stage moment match for each theta_i.

Parameters:

dim (int)
reservoir (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: GeneralizedMallowsModelAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: GeneralizedMallowsModelDistribution

class BradleyTerryDistribution(log_w, name=None, keys=None)[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)

classmethod compute_capabilities()[source]

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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

log_density(x)[source]

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

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

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

Return the data encoder used by this distribution for 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).

Parameters:

dim (int)
pseudo_count (float | None)
max_iter (int)
tol (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: BradleyTerryAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: BradleyTerryDistribution

class LowRankPermutationDistribution(u, v, name=None, keys=None, max_exact=12, sinkhorn_iter=200)[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)

classmethod compute_capabilities()[source]

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

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

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

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

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

marginals()[source]

Model first-order marginals P[item, rank] (Sinkhorn doubly-stochastic transport plan).

Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: LowRankPermutationDataEncoder

class LowRankPermutationEstimator(dim, rank=2, max_exact=12, sinkhorn_iter=200, max_iter=300, lr=0.5, 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)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: LowRankPermutationAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: LowRankPermutationDistribution

class ThurstoneDistribution(mu, name=None, keys=None, n_mc=4000, seed=0)[source]

Bases: SequenceEncodableProbabilityDistribution

Thurstone Case V Gaussian random-utility ranking model with mean utilities mu.

Parameters:

mu (Sequence[float] | np.ndarray)
name (str | None)
keys (str | None)
n_mc (int)
seed (int)

classmethod compute_capabilities()[source]

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

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

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: ThurstoneDataEncoder

class ThurstoneEstimator(dim, n_mc=4000, seed=0, name=None, keys=None)[source]

Bases: ParameterEstimator

Thurstone-Mosteller Case V estimator: mu_i - mu_j = sqrt(2) * Phi^{-1}(P(i before j)).

Parameters:

dim (int)
n_mc (int)
seed (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: ThurstoneAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: ThurstoneDistribution

class ThurstoneMostellerDistribution(mu, name=None, keys=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)

classmethod compute_capabilities()[source]

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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

log_density(x)[source]

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

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

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: PairDataEncoder

class ThurstoneMostellerEstimator(dim, 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).

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: PairWinAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: ThurstoneMostellerDistribution

class DavidsonDistribution(log_w, nu=1.0, name=None, keys=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)

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)

class DavidsonEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood Davidson worths and tie parameter (L-BFGS on the count matrices).

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: _TieAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:: nobs (float | None)
Return type:: DavidsonDistribution

class RaoKupperDistribution(log_w, nu=1.5, name=None, keys=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)

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)

class RaoKupperEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood Rao-Kupper worths and threshold (L-BFGS on the count matrices).

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: _TieAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Parameters:: x (Sequence[int])
Return type:: float

log_density(x)[source]

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

Parameters:: x (Sequence[int])
Return type:: float

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: EwensDataEncoder

class EwensEstimator(dim, theta=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)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: EwensAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

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 sequence of canonical 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 an exact finite enumerator over all supported spanning trees in probability order.

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

class SpanningTreeEstimator(dim, pseudo_count=None, max_steps=500, learning_rate=1.0, tol=1.0e-7, 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)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: SpanningTreeAccumulatorFactory

estimate(nobs, suff_stat)[source]

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)

class MatchingDistribution(weights, max_nodes=_DEFAULT_MAX_NODES, name=None, keys=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)

classmethod compute_capabilities()[source]

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

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=500, 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 type:: MatchingAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 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]] | ndarray)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]

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:: 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:

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, name=None, keys=None)[source]

Bases: ParameterEstimator

Adjacency Spectral Embedding estimator for the RDPG latent positions.

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: RandomDotProductGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

compute_declaration()[source]

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]

What log_density returns relative to the true log-density (default: exact).

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]

Creates a SemiSupervisedMixtureEstimatorAccumulatorFactory from the child estimators.

Returns:: SemiSupervisedMixtureEstimatorAccumulatorFactory object.
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:

SemiSupervisedMixtureDistribution object.

Return type:

SemiSupervisedMixtureDistribution

class TreeHiddenMarkovModelDistribution(topics, w=MISSING, transitions=MISSING, len_dist=NullDistribution(), terminal_level=10, name=None, use_numba=False, 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)
weights (Sequence[float] | ndarray)

compute_capabilities()[source]

compute_declaration()[source]

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]

What log_density returns relative to the true log-density (default: exact).

sampler(seed=None)[source]

Create a TreeHiddenMarkovSampler object from parameters of distribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: TreeHiddenMarkovSampler object.
Raises:: Exception – If len_dist is a NullDistribution (a length distribution with support on the non-negative integers is required for sampling).
Return type:: TreeHiddenMarkovSampler

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]

Returns TreeHiddenMarkovDataEncoder object for encoding sequences of 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=True)[source]

Bases: ParameterEstimator

Estimator for the TreeHiddenMarkovModelDistribution from aggregated sufficient statistics.

Parameters:

estimators (list[ParameterEstimator])
len_estimator (ParameterEstimator | None)
pseudo_count (tuple[float | None, float | None] | None)
name (str | None)
keys (tuple[str | None, str | None, str | None] | None)
use_numba (bool)

accumulator_factory()[source]

Returns a TreeHiddenMarkovAccumulatorFactory for creating TreeHiddenMarkovAccumulator objects.

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. Rows of the transition matrix with no observed transitions are left as zeros when no pseudo-count is given. 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:

TreeHiddenMarkovModelDistribution object.

Return type:

TreeHiddenMarkovModelDistribution

TreeHiddenMarkovModelEstimator: alias of TreeHiddenMarkovEstimator

class TransformDistribution(dist, transform=None, density_correction=None, name=None, keys=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)

compute_capabilities()[source]

compute_declaration()[source]

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:

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

Return child legacy statistics for valid inverse-transformed observations.

Parameters:

x (tuple[Any, ndarray, ndarray])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (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

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 type:: TransformAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 type:: FiniteStochasticTransformAccumulatorFactory

estimate(nobs, suff_stat)[source]

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)[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)

accumulator_factory()[source]

Return type:: ZeroInflatedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

ZeroInflatedDistribution

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 type:: HurdleAccumulatorFactory

estimate(nobs, suff_stat)[source]

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 type:: SurvivalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

SurvivalDistribution

class TruncatedDistribution(base, allowed=None, forbidden=None, name=None, keys=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)

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 an estimator that re-fits the base on the (in-support) data, keeping the truncation.

This is the fixed-truncation estimator: it maximizes the base likelihood over the observed (already in-support) data and re-wraps with the same support restriction. It does not solve the full truncated MLE (whose normalizer Z depends on the base parameters); use it when the truncation set is fixed and known, which is the typical censored/restricted-support case.

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

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

class TruncatedEstimator(base_estimator, allowed=None, forbidden=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Fixed-truncation estimator: fit the base on in-support data, re-wrap with the truncation.

Parameters:

base_estimator (ParameterEstimator)
allowed (Sequence[Any] | None)
forbidden (Sequence[Any] | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: TruncatedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

TruncatedDistribution

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)[source]

Bases: SequenceEncodableProbabilityDistribution

A base distribution whose observations may be interval/left/right censored.

Parameters:

base (SequenceEncodableProbabilityDistribution)
name (str | None)
keys (str | 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(F(b) - F(a)).

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 a sampler that draws exact values from the base (sampling is uncensored).

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

estimator(pseudo_count=None)[source]

Return an estimator that fits the base on the exact observations, re-wrapping with censoring.

The censored MLE has no generic closed form (the bounds couple with the base parameters), so this fits the base distribution on the exact (uncensored) observations and re-wraps. Use it when the censored fraction is modest; prefer a dedicated censored MLE otherwise.

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

dist_to_encoder()[source]

Return the data encoder (exact observations + censoring intervals split out).

Return type:: CensoredDataEncoder

class CensoredEstimator(base_estimator, name=None, keys=None)[source]

Bases: ParameterEstimator

Fit the base on the exact observations, re-wrap with censoring.

Parameters:

base_estimator (ParameterEstimator)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: CensoredAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

CensoredDistribution

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]

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]

Returns an ExponentiallyModifiedGaussianDataEncoder object.

Return type:: ExponentiallyModifiedGaussianDataEncoder

class ExponentiallyModifiedGaussianEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

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

classmethod compute_capabilities()[source]

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]

Returns a SkellamDataEncoder object.

Return type:: SkellamDataEncoder

class SkellamEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate (mu1, mu2) by the (exact, closed-form) method of moments.

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

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]

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

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(min_scale=1.0e-12, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for skew-normal location, scale and shape.

Parameters:

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

accumulator_factory()[source]

Return type:: SkewNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

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)[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)

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]

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]

Returns a TweedieDataEncoder object.

Return type:: TweedieDataEncoder

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

Bases: ParameterEstimator

Estimate (mu, phi) at fixed power p by the (exact) method of moments.

Parameters:

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

accumulator_factory()[source]

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)[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)

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 an (N, 5) array of per-trajectory sufficient statistics.

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 BirthDeathSamplingEstimator (closed-form rate MLE).

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

dist_to_encoder()[source]

Returns a BirthDeathSamplingDataEncoder object.

Return type:: BirthDeathSamplingDataEncoder

class BirthDeathSamplingEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form rate MLE: rate = (total events of that type) / integral_n.

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: BirthDeathSamplingAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate per-capita rates from accumulated event counts and population time-integral.

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)[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)

property generator: ndarray: The generator matrix Q (off-diagonal rates, diagonal = -exit rate).

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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 (Any)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: ContinuousTimeMarkovChainDataEncoder

class ContinuousTimeMarkovChainEstimator(num_states, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form rate MLE: q_ij = n_ij / T_i (independent Poisson rates, unique global optimum).

Parameters:

num_states (int)
pseudo_count (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: ContinuousTimeMarkovChainAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

ContinuousTimeMarkovChainDistribution

class InhomogeneousPoissonProcessDistribution(rates, t_max=None, edges=None, name=None, keys=None)[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)

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 InhomogeneousPoissonProcessEstimator(num_bins=None, t_max=None, edges=None, name=None, keys=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)

accumulator_factory()[source]

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)[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)

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 RenewalProcessEstimator(interarrival_estimator, window, name=None, keys=None)[source]

Bases: ParameterEstimator

Fit the inter-arrival distribution to observed gaps (standard renewal-process MLE).

Parameters:

interarrival_estimator (ParameterEstimator)
window (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: RenewalProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

RenewalProcessDistribution

class HawkesProcessDistribution(mu, alpha, beta, window, name=None, keys=None)[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)

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 sorted event-time sequence in [0, window]).

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)[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)

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 a branching-EM estimator over the same window and dimension.

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)[source]

Bases: ParameterEstimator

Veen-Schoenberg branching-EM estimator for the multivariate Hawkes parameters.

Parameters:

dim (int)
window (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: MultivariateHawkesProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

Return type:

MultivariateHawkesProcessDistribution

class HawkesProcessEstimator(window, name=None, keys=None)[source]

Bases: ParameterEstimator

EM branching M-step: mu=S0/total_window, beta=G/W, alpha=beta*G/n_events.

Parameters:

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

accumulator_factory()[source]

Return type:: HawkesProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate (mu, alpha, beta) from the accumulated branching sufficient statistics.

Parameters:

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

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 type:: ExponentialTiltedAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

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

inverse(y)[source]

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

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

invalid_inverse_value()[source]

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]

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

inverse(y)[source]

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

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

invalid_inverse_value()[source]

Return type:: float

class ExpTransform[source]

Bases: object

Exponential transform y = exp(x), mapping real x to positive y.

forward(x)[source]

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

inverse(y)[source]

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

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

invalid_inverse_value()[source]

Return type:: float

class LogTransform[source]

Bases: object

Log transform y = log(x), mapping positive x to real y.

forward(x)[source]

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

inverse(y)[source]

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

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

invalid_inverse_value()[source]

Return type:: float

class LogitTransform[source]

Bases: object

Logistic transform y = 1 / (1 + exp(-x)), mapping real x to (0, 1).

forward(x)[source]

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

inverse(y)[source]

Parameters:: y (Any)
Return type:: Any

log_abs_det_inverse_jacobian(y)[source]

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

invalid_inverse_value()[source]

Return type:: float

class LDADistribution(topics, alpha, len_dist=NullDistribution(), gamma_threshold=1.0e-8, max_gamma_iter=100)[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)

compute_capabilities()[source]: Return backend capability metadata for this concrete LDA instance.

compute_declaration()[source]

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]

What log_density returns relative to the true log-density (default: exact).

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 an LDASampler object for sampling documents from this distribution.

Parameters:: seed (Optional[int]) – Seed for the random number generator used in sampling.
Returns:: LDASampler object.
Return type:: LDASampler

estimator(pseudo_count=None)[source]

Create an LDAEstimator object from the topics of this distribution.

Parameters:: pseudo_count (Optional[float]) – If passed, used to re-weight sufficient statistics during estimation.
Returns:: LDAEstimator object.
Return type:: LDAEstimator

dist_to_encoder()[source]

Return an LDADataEncoder object for encoding sequences of 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)[source]

Bases: ParameterEstimator

LDAEstimator object for estimating an LDADistribution from aggregated sufficient statistics.

Parameters:

estimators (Sequence[ParameterEstimator])
len_estimator (ParameterEstimator | None)
suff_stat (Any | None)
pseudo_count (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)

accumulator_factory()[source]

Returns an LDAEstimatorAccumulatorFactory object from attribute variables.

Return type:: LDAEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an LDADistribution from aggregated sufficient statistics.

Arg suff_stat is a Tuple of length 6 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:

LDADistribution object.

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]

classmethod compute_declaration()[source]

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 VonMisesFisherSampler object from parameters of VonMisesFisherDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: VonMisesFisherSampler object.
Return type:: VonMisesFisherSampler

estimator(pseudo_count=None)[source]

Create a VonMisesFisherEstimator object.

Parameters:: pseudo_count (Optional[float]) – Kept for interface consistency (has no effect on estimation).
Returns:: VonMisesFisherEstimator object.
Return type:: VonMisesFisherEstimator

dist_to_encoder()[source]

Returns a VonMisesFisherDataEncoder object for encoding sequences of data.

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)

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 type:: GaussianCopulaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

GaussianCopulaDistribution

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 type:: MatrixNormalAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

MatrixNormalDistribution

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]

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 a sampler for drawing unit vectors from this 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 type:: WatsonAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

WatsonDistribution

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 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).

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) via Newton’s method on the profile log-likelihood (_solve_wishart_df()).

Parameters:

dim (int)
df (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: WishartAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

WishartDistribution

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 not positive definite).

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

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded array of log det(R) values.

Parameters:: x (ndarray)
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 type:: LKJAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

LKJDistribution

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 probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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]

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 a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

Return the data encoder used by this distribution for 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 type:: KentAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

KentDistribution

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 probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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]

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 a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

Return the data encoder used by this distribution for 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]

Parameters:

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

Return type:

BinghamDistribution

accumulator_factory()[source]

Return type:: BinghamAccumulatorFactory

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 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).

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 a closed-form estimator for the scale at the fixed degrees of freedom df.

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

dist_to_encoder()[source]

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

Return type:: InverseWishartDataEncoder

class InverseWishartEstimator(dim, df, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form scale estimator at fixed df: Psi = (df-p-1) * mean(X) since E[X] = Psi/(df-p-1).

Parameters:

dim (int)
df (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: InverseWishartAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

InverseWishartDistribution

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]: Returns a VonMisesFisherAccumulatorFactory for creating VonMisesFisherAccumulator objects.

estimate(nobs, suff_stat)[source]

Estimate a VonMisesFisherDistribution from sufficient statistics.

The mean direction mu is the normalized weighted vector sum. The concentration kappa solves A_p(kappa) = rhat (rhat = ||ssum|| / count), initialized with the closed-form Banerjee et al. approximation and refined with up to three Newton steps. The Bessel-function ratio A_p(kappa) is evaluated through lniv() so large orders p/2 fall back to the uniform large-order asymptotic instead of underflowing. Two guards keep the solution finite: rhat is clamped below 1 (rhat -> 1 sends kappa -> inf), and Newton refinement is skipped within 1e-9 of 1 where A_p’(kappa) -> 0 makes the iteration ill-conditioned while the initializer is already accurate.

Parameters:

nobs (Optional[float]) – Number of observations (unused).
suff_stat (Tuple[float, np.ndarray]) – Tuple of count and weighted vector sum.

Returns:

VonMisesFisherDistribution object (uniform on the sphere, kappa = 0, if no data observed).

Return type:

VonMisesFisherDistribution

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]

classmethod compute_declaration()[source]

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, 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.

Parameters:

dof (float)
dim (int | None)
min_ridge (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: MultivariateStudentTAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

MultivariateStudentTDistribution

class WeightedDistribution(dist, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

WeightedDistribution object that attaches observation weights to a base distribution.

Parameters:

dist (SequenceEncodableProbabilityDistribution) – Base distribution for the observed values.
name (Optional[str]) – Set name for object instance.

dist

Base distribution for the observed values.

Type:: SequenceEncodableProbabilityDistribution

name

Name for object instance.

Type:: Optional[str]

compute_capabilities()[source]

compute_declaration()[source]

density(x)[source]

Density of the base distribution at observation value x.

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 observation value x.

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]

Return child legacy statistics with posterior weights scaled by observation weights.

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]

Delegates to the base distribution’s enumerator (log_density is pure delegation).

Return type:: DistributionEnumerator

class WeightedEstimator(estimator, name=None)[source]

Bases: ParameterEstimator

WeightedEstimator object for estimating a WeightedDistribution from weighted observations.

Parameters:

estimator (ParameterEstimator) – Estimator for the base distribution.
name (Optional[str]) – Set name for object instance.

estimator

Estimator for the base distribution.

Type:: ParameterEstimator

name

Name for object instance.

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

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]

classmethod compute_declaration()[source]

classmethod from_model(model)[source]

Parameters:: model (Any)
Return type:: ErdosRenyiGraphDistribution

to_model()[source]

Return type:: Any

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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 (Sequence[GraphObservation])
Return type:: 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:

edge_probability(i=None, j=None, context=None)[source]

Parameters:

i (int | None)
j (int | None)
context (Any | None)

Return type:

edge_marginals(num_nodes=None)[source]

Parameters:: num_nodes (int | None)
Return type:: ndarray

posterior(x)[source]

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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 an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

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 type:: ErdosRenyiGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

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]

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

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

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 type:: TemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

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

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 node, and one per added edge. 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]

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

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

seq_encode(x)[source]

Parameters:: x (Sequence[tuple])
Return type:: Sequence[tuple]

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(**kw)[source]

Return an estimator for fitting this distribution from data.

Parameters:: kw (Any)
Return type:: LabeledTemporalGraphGrammarEstimator

dist_to_encoder()[source]

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

Return type:: TemporalGraphGrammarDataEncoder

class LabeledTemporalGraphGrammarEstimator(structure_estimator, node_estimator=None, edge_estimator=None, name=None)[source]

Bases: ParameterEstimator

Parameters:

structure_estimator (Any)
node_estimator (Any)
edge_estimator (Any)
name (str | None)

accumulator_factory()[source]

Return type:: LabeledTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

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]

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

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

seq_encode(x)[source]

Parameters:: x (Sequence[tuple])
Return type:: Sequence[tuple]

seq_log_density(x)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: TemporalGraphGrammarDataEncoder

class HomophilyTemporalGraphGrammarEstimator(M, K, motif=None, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

Parameters:

M (int)
K (int)
motif (CommonNeighbourMotif | None)
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return type:: HomophilyTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

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]

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

Parameters:: x (Sequence[tuple])
Return type:: float

seq_encode(x)[source]

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

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

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: TemporalGraphGrammarDataEncoder

class ChurningTemporalGraphGrammarEstimator(edit_estimator, name=None)[source]

Bases: ParameterEstimator

Parameters:

edit_estimator (Any)
name (str | None)

accumulator_factory()[source]

Return type:: ChurningTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

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]

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

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]

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

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

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

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 type:: LatentTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

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]

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

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]

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

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

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: TemporalGraphGrammarDataEncoder

class LatentAttributedTemporalGraphGrammarEstimator(structure_estimators, node_estimators=None, edge_estimators=None, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

EM for the regime-switching attributed grammar: forward-backward E-step, per-regime weighted M-step over structure + node attrs + edge attrs together.

Parameters:

structure_estimators (Sequence[Any])
node_estimators (Any)
edge_estimators (Any)
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return type:: LatentAttributedTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

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]

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

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

decode(x)[source]

Parameters:: x (tuple)
Return type:: list

seq_encode(x)[source]

Parameters:: x (Sequence[Any])
Return type:: Sequence[Any]

seq_log_density(x)[source]

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

Parameters:: x (Sequence[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: TemporalGraphGrammarDataEncoder

class LatentChurningTemporalGraphGrammarEstimator(state_estimators, pseudo_count=None, name=None)[source]

Bases: ParameterEstimator

Parameters:

state_estimators (Sequence[Any])
pseudo_count (float | None)
name (str | None)

accumulator_factory()[source]

Return type:: LatentChurningTemporalGraphGrammarAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple)

Return type:

LatentChurningTemporalGraphGrammarDistribution

class StochasticBlockGraphDistribution(block_probs, block_assignments=None, block_prior=None, directed=False, self_loops=False, include_assignment_prior=False, 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)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]

classmethod from_model(model, block_prior=None, include_assignment_prior=False)[source]

Parameters:

model (Any)
block_prior (Any | None)
include_assignment_prior (bool)

Return type:

StochasticBlockGraphDistribution

to_model()[source]

Return type:: Any

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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 (Sequence[GraphObservation])
Return type:: 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:

link_probability(i, j, block_assignments=None)[source]

Parameters:

i (int)
j (int)
block_assignments (Any | None)

Return type:

edge_marginals(block_assignments=None, num_nodes=None)[source]

Parameters:

block_assignments (Any | None)
num_nodes (int | None)

Return type: