typola.models.distribution

A categorical distribution over a known support, with introspection.

class typola.models.distribution.Distribution(probabilities: Series, counts: Series, support_labels: Series | None = None, estimator_name: str = '', metadata: dict = <factory>)

A categorical probability distribution with provenance.

probabilities

Non-negative, sums to 1. Index labels the support (typically code IDs).

Type:

pd.Series

counts

Raw counts this distribution was built from; same index as probabilities.

Type:

pd.Series

support_labels

Human-readable name for each support element (e.g. “SVO”), same index.

Type:

pd.Series

estimator_name

The estimator used (“mle”, “laplace”, etc.); useful in comparisons.

Type:

str

metadata

Freeform: parameter id, condition, source, etc.

Type:

dict

entropy(*, base: float = 2.0) → float

Shannon entropy of the probability vector (default: bits).

kl_divergence(other: Distribution, *, eps: float = 1e-12) → float

KL(self || other), requires compatible supports.

mode()

Return the label of the most probable support element.

normalized_entropy(*, base: float = 2.0) → float

Entropy / log(K): 1 = uniform, 0 = point mass.

sample(n: int = 1, rng: Generator | None = None) → list

Sample n outcomes from the distribution.

to_frame() → DataFrame

One row per support element with columns: name, count, probability.

top_k(k: int = 5) → DataFrame

Return the k most probable outcomes as a DataFrame.