mixle.utils.hvis.direct module

The direct compositional layout: read the map off the model instead of re-inferring it.

t-SNE/UMAP exist to DISCOVER global and local structure from raw pairwise distances when there is no model. HViS has a model, and the structure the neighbor optimizers spend a thousand stochastic iterations inferring is already known in closed form: WHICH regimes exist and how they relate (the posterior simplex and component overlap geometry), and WHERE each observation sits within its regime (the whitened local/typicality coordinates). This module composes those two levels directly – the (posterior, remainder) decomposition as a layout:

y_i = sum_k z_ik * (vertex_k + frame_k(fiber_scores_ik))

  • vertices: component_map() – geodesic layout of the cover’s nerve (confusable regimes adjacent; rings render as rings). Deterministic.

  • fibers: per component, a responsibility-weighted PCA of the per-field WHITENED local coordinates (native value coordinates or universal typicality coordinates – the same geometry the ‘local’ affinity scores). Deterministic up to sign, and signs are canonicalized. The loadings are returned, so a fiber axis is NAMEABLE: “within regime k, axis 1 is field 2’s coordinate 0”. chart='quadratic' lifts the fiber features with degree-2 terms (explicit polynomial kernel, still closed-form and placeable) for regimes whose within-structure is curved; the per-component chart_residuals report says how much variance the linear chart leaves behind either way.

  • frames: each chart gets its own on-screen frame, major axis oriented tangentially (orthogonal to the nearest other vertex) so neighboring charts’ fringes cannot collide head-on.

  • occlusion: components with NO measured overlap in the model must not overlap on screen – a deterministic push-apart pass enforces it, while genuinely-overlapping components are allowed to overlap visually (screen overlap then MEANS model overlap).

  • composition: barycentric in the posterior, so sharp points sit in their regime’s local chart and mixed-membership points interpolate between charts.

No perplexity, no seed, no optimizer failure modes; out-of-sample placement (ModelMap.place()) is the same closed form, so streaming costs one matrix product. The precedent is Bishop & Tipping’s hierarchical mixture visualization / GTM: per-component local projections composed by responsibility – rebuilt here on HViS’s field decomposition so it covers heterogeneous, variable-length, and sequence data.

When to still reach for the neighbor optimizers: no trustworthy model, strongly nonlinear within-regime manifolds a chart flattens, or pure exploration. refine=True runs t-SNE FROM this layout (informative init, exaggeration off) so the optimizer only polishes local neighborhoods it is actually good at – the composition stays in charge of the global picture.

component_fiber_coords(mix_model, data, field_weights=None)[source]

The shared fiber machinery: posteriors, per-component whitened field coordinates, labels.

Returns (z, [u_k for each component], coord_labels, transforms) where u_k is the (n, D) concatenation of every coordinate-bearing field’s values, whitened by component k’s local inverse covariance and weighted per field. transforms carries everything needed to reproduce the coordinates for NEW data (used by ModelMap.place() and by mixle.utils.hvis.topology.model_fit_health()).

Return type:

tuple[ndarray, list[ndarray], list[str], dict]

class ModelMap(coords, vertices, responsibilities, loadings, coord_labels, frames=<factory>, chart='linear', chart_residuals=<factory>, _model=None, _transforms=<factory>, _pre=<factory>, _fiber_means=<factory>, _fiber_scale=1.0, _emb_dim=2)[source]

Bases: object

A fitted direct layout: coordinates plus everything needed to read and extend the map.

vertices are the component anchors (post occlusion resolution); loadings[k] names what regime k’s chart axes measure (rows = chart features, see coord_labels); frames[k] is the chart’s on-screen frame (row 0 = the major axis’s direction); chart_residuals[k] is the fraction of fiber variance the LINEAR chart leaves beyond emb_dim (high = this regime’s within-structure is not 2-D-linear – consider chart='quadratic' or refine=True); place(data) maps NEW observations with the fit-time transforms – closed form, so streaming is one call.

Parameters:
place(data)[source]

Closed-form out-of-sample placement with the FIT-TIME transforms (means, whiteners, chart directions, frames, scale). Placing the training data reproduces coords exactly.

Return type:

ndarray

model_map(data, mix_model=None, emb_dim=2, *, spread=0.35, chart='linear', occlusion=True, occlusion_margin=1.05, edge_threshold=0.02, field_weights=None, max_components=50, dpm_max_its=200, seed=None, refine=False, refine_kwargs=None)[source]

The deterministic model-native layout (see module docstring). Returns a ModelMap.

spread sets how large regime fibers render relative to the smallest inter-vertex gap – a LEGIBILITY choice made explicit, unlike t-SNE where cluster sizes are a meaningless artifact. chart is 'linear' (default) or 'quadratic' (explicit degree-2 features – a curved within-regime chart that stays closed-form and placeable); either way chart_residuals reports the linear chart’s leftover variance per regime. occlusion=True enforces that components with no measured overlap never overlap on screen. seed/max_components/ dpm_max_its only matter when mix_model is None and a DPM must be fit first; the layout itself uses no randomness. refine=True polishes local neighborhoods with t-SNE initialized FROM this layout (exaggeration off), leaving the global arrangement model-decided.

Parameters:
Return type:

ModelMap