mixle.utils.hvis.embed module

Top-level model-based embedding entry points: htsne, humap, dpmsne.

These orchestrate the pieces in this package: fit/accept a mixture model, resolve the affinity, build the (sparse or dense) probability matrix from the model posteriors, and run the chosen embedding engine.

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)

humap(data, emb_dim=2, n_neighbors=15, min_dist=0.1, max_components=50, seed=None, mix_model=None, enc_data=None, dpm_max_its=200, print_iter=100, affinity='auto', field_weights=None, evidence_cap=1.0, fisher_metric='diagonal', fisher_ridge=1.0e-8, fisher_information='observed', n_epochs=None, out=None, **umap_kwargs)[source]

Embed heterogeneous data with model-based UMAP.

The same mixture-model affinities as htsne (see the affinity and evidence_cap arguments there), but the k-nearest-neighbor graph of model distances -log s_ij is handed to UMAP’s fuzzy simplicial set construction and layout (umap-learn) instead of t-SNE. Scales like UMAP: the dense affinity matrix is never built.

Extra keyword arguments are passed to umap.UMAP. Returns the n x emb_dim embedding.

Parameters:

  • emb_dim (int)

  • n_neighbors (int)

  • min_dist (float)

  • max_components (int)

  • seed (int | None)

  • dpm_max_its (int)

  • print_iter (int)

  • evidence_cap (float | None)

  • fisher_metric (str)

  • fisher_ridge (float)

  • fisher_information (str)

  • n_epochs (int | None)

dpmsne(P=None, emb_dim=2, alpha=1.0, Y=None, 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, early_exaggeration=12.0, tol=1.0e-7, out=None, **_compat_kwargs)[source]

Embed a precomputed (symmetric, non-negative) affinity matrix P with exact t-SNE.

Parameters: