mixle.utils.hvis.affinity module¶
Factor/affinity computation for model-based (hierarchical) t-SNE/UMAP.
This module turns a fitted mixture model (or pre-built factors) into the per-pair log affinities that drive the embedding: it builds the affinity factor list for each affinity mode, computes the dense log-affinity matrix, and converts a log-affinity matrix into row-conditional t-SNE probabilities. See the package docstring for the affinity definitions.
- balanced_factors(mix_model, data, field_weights=None)[source]
Per-field Bhattacharyya affinity factors for heterogeneous models.
The joint posterior is dominated by whichever field has the largest log-likelihood contrast across components - sharp categorical fields, long token-sequence fields, or collapsed continuous components can contribute many nats of contrast while overlapping continuous fields contribute fractions of one. The drowned fields’ relationships then become invisible to any affinity computed from the joint posterior.
‘balanced’ fixes the scale problem at the affinity level: a field- restricted posterior z^f is computed from each field’s likelihoods alone (fields are the model’s flattened leaves - nested composites, sequence element/length models, and optional wrappers all decompose; see _field_log_densities), and the affinity combines per-field Bhattacharyya coefficients, so every field contributes comparably regardless of its likelihood scale. field_weights apply as exponents on whole field coefficients, i.e. weights on log field-affinities. Combined with an evidence cap (see model_log_affinity) no single field can veto a pair’s similarity either.
- local_factors(mix_model, data, field_weights=None)[source]
Per-field local statistical affinity factors.
Each leaf field is first represented by its field-restricted component posterior. If the leaf has meaningful local coordinates (continuous/count leaves, and averages of such leaves inside sequences), the factor also carries component-local inverse covariances estimated from the realized data. Pair affinities then use
sum_k sqrt(z_ik z_jk) exp(-delta_ijk / 8),
where delta_ijk is the component-local Mahalanobis distance in that field’s coordinates. This is the local Fisher quadratic in the plug-in model, with posterior overlap handling component uncertainty.
- fisher_factors(model, data=None, enc_data=None, metric='diagonal', ridge=1.0e-8, weight=1.0, information='observed')[source]
Fisher-vector affinity factor for a model and observations.
The model supplies posterior-expected sufficient statistics through to_fisher(). By default those statistics are treated as observed score vectors and whitened by their empirical observed Fisher covariance. Set information=’model’ to use the view’s model Fisher metric directly. Pair affinities are s_ij = exp(-0.5 ||v_i - v_j||^2).
- model_log_affinity(posterior_mat, ll_mat=None, affinity='bhattacharyya', evidence_cap=None)[source]
Dense n x n matrix of log affinities (see module docstring) with -inf diagonal.
Rows are comparable up to a per-row shift, which both the row-conditional normalization and per-row perplexity calibration are invariant to.
evidence_cap bounds the dissimilarity evidence any single factor (field) may contribute: each factor’s log affinity is floored at -evidence_cap nats before the factors are summed. Without the cap a single sharp field with (near-)disjoint per-field posteriors drives its log affinity to -inf and vetoes the pair no matter what every other field says; with it, a field can at most testify “these differ by evidence_cap nats”. The cap is only applied to multi-factor (per-field) affinities - for a single factor it could only create ties.
- conditional_pmat(log_aff, perplexity=None)[source]
Row-conditional probabilities p_{j|i} from log affinities (diagonal -inf).
With perplexity set, each row is calibrated so its entropy equals log(perplexity); otherwise the raw row softmax is used.
- get_pmat(posterior_mat, ll_mat=None, targ_perplexity=None, vlen=False, affinity='bhattacharyya', evidence_cap=None)[source]
Symmetrized t-SNE input probabilities from model posteriors (and optionally component log-likelihoods, for affinity=’likelihood’).
The vlen flag is kept for backward compatibility and ignored.