mixle.utils package

General utility namespace.

Most utility subpackages stay lazy. A few user-facing review helpers are also exposed here so examples do not have to teach implementation paths.

analyze_structure(data, pairwise=True, max_pairwise_fields=32, max_pairwise_pairs=512, max_cardinality=128, num_bins=8, sample_size=5000, validate_marginals=True, validation_fraction=0.25, max_validation_rows=1000, validation_min_count=30, validation_seed=17, mi_threshold_bits=0.05, bic_gain_threshold_bits=0.0, pairwise_permutations=0, permutation_alpha=0.05, dependency_tree=True, rng=None, pseudo_count=1.0, emp_suff_stat=True, use_bstats=False)[source]

Profile data and return marginal recommendations plus pairwise hints.

Integer marginals are compared by BIC-style average code length. Pairwise hints report plug-in MI, finite-sample adjusted MI, and BIC edge gain. Pairwise hints are deliberately unconditional and encoded through cheap empirical/quantile codes. They are useful evidence, not proof of topology: latent classes or states can explain the same bit gains. Marginal validation is a bounded deterministic train/validation split over scalar fields, meant as a cheap predictive sanity check on the BIC choice.

Parameters:

  • pairwise (bool)

  • max_pairwise_fields (int)

  • max_pairwise_pairs (int)

  • max_cardinality (int)

  • num_bins (int)

  • sample_size (int | None)

  • validate_marginals (bool)

  • validation_fraction (float)

  • max_validation_rows (int)

  • validation_min_count (int)

  • validation_seed (int)

  • mi_threshold_bits (float)

  • bic_gain_threshold_bits (float)

  • pairwise_permutations (int)

  • permutation_alpha (float)

  • dependency_tree (bool)

  • rng (RandomState | None)

  • pseudo_count (float | None)

  • emp_suff_stat (bool)

  • use_bstats (bool)

Return type:

StructureProfile

htsne(data, emb_dim=2, alpha=1.0, max_components=50, Y=None, perplexity=30.0, max_its=1000, print_iter=100, eta=None, momentum=0.8, min_gain=0.01, min_value=1.0e-128, optimize_alpha=False, min_alpha=1.0e-6, max_alpha_its=3, seed=None, mix_model=None, enc_data=None, method='auto', early_exaggeration=12.0, tol=1.0e-7, dpm_max_its=200, affinity='auto', field_weights=None, evidence_cap=1.0, fisher_metric='diagonal', fisher_ridge=1.0e-8, fisher_information='observed', out=None, variable_length=False, barnes_hut_theta=0.5, barnes_hut_leaf_size=16, neighbor_method='auto', neighbor_threshold=5000, neighbor_trees=8, neighbor_leaf_size=None, candidate_multiplier=8, repulsion_method='auto', exact_repulsion_threshold=5000)[source]

Embed heterogeneous data with model-based t-SNE.

A mixture model is fit to the data (a Dirichlet process mixture with automatically typed components by default, or pass mix_model), pairwise affinities are computed from the model, and the affinities are embedded with t-SNE. Passing affinity=’fisher’ with any model that exposes to_fisher(), or passing a pre-built affinity factor list, bypasses the mixture-posterior affinity path and does not require a DPM/mixture model.

method:

‘exact’ - full-matrix gradient descent (supports optimize_alpha) ‘barnes_hut’ - sparse model probabilities + internal Barnes-Hut t-SNE ‘auto’ - barnes_hut for n > 10 unless optimize_alpha is set

affinity:
‘auto’ (default) - ‘local’ whenever raw data is available and the

model decomposes into leaf fields, else ‘bhattacharyya’

‘local’ - per-field posterior overlap plus component-local

Mahalanobis geometry for continuous/count fields, estimated from the realized data; discrete fields fall back to posterior overlap

‘balanced’ - per-field posteriors (the model’s flattened leaves:

nested composites, sequence element/length models, and optional wrappers all decompose) combined by per-field Bhattacharyya, so a sharp discrete field cannot drown an overlapping continuous one (or vice versa); optional field_weights sets exponents on whole field-level Bhattacharyya coefficients

‘fisher’ - posterior-expected sufficient statistics from

mix_model.to_fisher(), whitened by an observed Fisher metric; fisher_information=’observed’ uses the empirical covariance of observed score vectors, while ‘model’ uses the view’s model metric; fisher_metric is ‘diagonal’ by default, with ‘identity’ and ‘full’ also accepted

‘bhattacharyya’ - Bhattacharyya coefficient between joint posteriors;

graded even under hard assignments, so embeddings retain within-cluster geometry

‘coassign’ - co-assignment probability P(z_i = z_j | x); exact but

near-binary when posteriors are sharp

‘likelihood’ - predictive affinity sum_k p(x_i|theta_k) z_jk

variable_length is retained for backward compatibility and does not rescale densities. Variable-length behavior is determined by the fitted sequence model: ordinary SequenceDistribution leaves use summed element log-likelihood with length as a separate field, while SequenceDistribution(len_normalized=True) intentionally uses a per-token composition quotient for the element field.

evidence_cap (default 1.0 nats) bounds the dissimilarity evidence any single field may contribute to a pair’s distance under multi-field affinities: without it, one spuriously sharp field (a serial-number-like categorical the model micro-clustered) drives its per-field affinity to zero and vetoes the pair’s similarity no matter what every other field says. None disables the cap; single-field affinities ignore it.

barnes_hut_theta controls the Barnes-Hut opening angle for method=’barnes_hut’; 0.0 gives exact repulsive forces and larger values are faster/coarser.

repulsion_method controls repulsive forces for method=’barnes_hut’: ‘exact’ uses a vectorized all-pairs calculation, ‘barnes_hut’ uses the tree approximation, and ‘auto’ uses exact repulsion when n is at most exact_repulsion_threshold.

neighbor_method controls graph construction for method=’barnes_hut’: ‘exact’ uses blockwise all-pairs top-k, ‘approx’ uses a random-projection candidate forest, and ‘auto’ switches to ‘approx’ when n >= neighbor_threshold.

Returns the n x emb_dim embedding.

Parameters:

  • emb_dim (int)

  • alpha (float)

  • max_components (int)

  • Y (ndarray | None)

  • perplexity (float | None)

  • max_its (int)

  • print_iter (int)

  • eta (float | None)

  • momentum (float)

  • min_gain (float)

  • min_value (float)

  • optimize_alpha (bool)

  • min_alpha (float)

  • max_alpha_its (int)

  • seed (int | None)

  • method (str)

  • early_exaggeration (float)

  • tol (float)

  • dpm_max_its (int)

  • evidence_cap (float | None)

  • fisher_metric (str)

  • fisher_ridge (float)

  • fisher_information (str)

  • variable_length (bool)

  • barnes_hut_theta (float)

  • barnes_hut_leaf_size (int)

  • neighbor_method (str)

  • neighbor_threshold (int)

  • neighbor_trees (int)

  • neighbor_leaf_size (int | None)

  • candidate_multiplier (int)

  • repulsion_method (str)

  • exact_repulsion_threshold (int)

Subpackages

Submodules