mixle.utils.hvis.goals module

Embedding goals: declarative objectives layered onto an HViS embedding.

The data term (t-SNE row-KL / UMAP cross-entropy) says “preserve the model’s neighborhood structure”; a goal says what else the layout is FOR. Goals steer the same optimization – they are not a post-hoc warp of a finished layout, which would break exactly the neighborhood structure the embedding exists to show.

Rate semantics (the stability contract). A goal’s gradient(Y) returns a bounded per-iteration DISPLACEMENT, applied as Y -= gradient once per optimizer iteration – decoupled from the data optimizer’s learning rate and adaptive gains on purpose. t-SNE’s data gradient lives on probability scale and is driven with eta ~ n/12 and delta-bar-delta gains; a raw quadratic penalty routed through that machinery is amplified by orders of magnitude and diverges. Under rate semantics every goal’s weight is a fraction-per-step in (0, 1], contraction-stable by construction regardless of the optimizer it rides along with.

Three goals, and two headline features are special cases:

  • Anchor – ANCHORING: pin chosen points to given coordinates. Hard (weight=None) is an exact projection every step; soft (weight in (0, 1]) closes that fraction of the remaining gap per step – unconditionally stable exponential relaxation. Anchors fix the translational gauge, so the optimizers skip their usual mean-centering (they would fight).

  • LabelCohesion – PARTIAL LABELING: labels for any subset of points (None = unlabeled). Labeled points move toward their label centroid at weight per step; an optional margin hinge pushes centroid pairs apart. Unlabeled points are shaped only by the data term – semi-supervision, not relabeling.

  • AxisAlign – a layout GOAL: a per-point scalar (time, depth, severity, …) should run along a chosen embedding axis, ascending the Pearson correlation along its scale-normalized direction (translation/scale invariant, so it orders the axis without dictating layout scale).

class Anchor(indices, coordinates, weight=None)[source]

Bases: object

Pin indices to coordinates: hard when weight is None (exact projection each step), soft for weight in (0, 1] (close that fraction of the remaining gap per step).

Parameters:

  • indices (Sequence[int])

  • coordinates (Any)

  • weight (float | None)

class AxisAlign(values, axis=0, weight=0.5)[source]

Bases: object

A per-point scalar should run along embedding axis axis: each step ascends the Pearson correlation r(y[:, axis], values) along its scale-normalized direction (bounded norm <= 2, so weight – recommended at most ~1 – is a stable per-step rate in embedding units). Pass -values to reverse direction.

Parameters:
class LabelCohesion(labels, weight=0.1, margin=None)[source]

Bases: object

Partial labels shape the layout: each labeled point moves toward its label’s centroid at weight (a per-step fraction in (0, 1]); with margin, centroid pairs closer than margin are pushed apart (every member displaced alike, which moves the centroid by exactly the intended amount). labels has one entry per point; None marks a point unlabeled.

Parameters:

  • labels (Sequence[Any])

  • weight (float)

  • margin (float | None)

apply_projections(goals, y, velocity=None)[source]

Apply anchor projections/relaxations after a step; zero the velocity of hard-pinned rows so momentum cannot accumulate against the pin.

Parameters:
Return type:

ndarray

goals_fix_gauge(goals)[source]

True when any goal pins absolute coordinates – the optimizers must then skip mean-centering (centering re-translates the cloud every step, which would fight the pins).

Parameters:

goals (Sequence[Any] | None)

Return type:

bool

total_goal_gradient(goals, y)[source]

Summed per-step goal displacement at y (applied as Y -= result), or None when there are no goals so the optimizers skip the add entirely.

Parameters:
Return type:

ndarray | None