mixle.represent.modality module

Deterministic modality vectorization helpers.

vectorize() maps a raw item to a fixed-length vector that can be used by structure-learning and heterogeneous Bayesian-network workflows:

  • text / record -> the learned embedding (mixle.represent.fit_embedder());

  • image (a 2-D or 3-D numeric array) -> grid-pooled intensities (a coarse, deterministic, torch-free descriptor that captures brightness / spatial layout);

  • signal (a 1-D numeric array) -> per-window statistics (mean, energy, range) across the trace.

The image and signal descriptors are deterministic and dependency-free. They are intended as a baseline vectorization layer; learned encoders can be placed behind the same vectorize surface when a workflow needs richer features.

image_features(img, dim=16, *, grid=None)[source]

A fixed dim descriptor of an image: mean intensity over a rows x cols partition of cells.

img is (H, W) or (H, W, C); channels are averaged. The cell grid is the most nearly square factorization rows * cols == dim (_cell_grid()), so the cells tile the image: every pixel lies in exactly one cell and therefore influences exactly one output coordinate. That is what makes this a spatial-layout vector – enough for an image field to correlate with structured fields in a discovered graph.

This used to choose a square grid with ceil(sqrt(dim)) cells per side and truncate the row-major cell list to dim. For any dim that is not a perfect square that is not pooling to a coarser resolution – it permanently deletes the bottom/right cells. At the default grid for dim=2, changing the entire bottom half of a 4x4 image from 0 to 100 left the descriptor exactly [0, 0]; at dim=3 the whole bottom-right quadrant was invisible. A descriptor presented as capturing spatial layout must not have location-dependent blind spots.

grid overrides the automatic choice with an explicit square side and must satisfy grid * grid == dim, so an explicit grid partitions the image too.

The image must be non-empty and finite (see _require_measured()).

Parameters:
Return type:

ndarray

signal_features(sig, dim=16, *, windows=None)[source]

A fixed dim descriptor of a 1-D signal: (mean, energy, range) over evenly-spaced windows.

The trace must be non-empty and finite (see _require_measured()): an empty signal used to return the all-zero vector, which is indistinguishable from a measured zero-energy trace, and NaN samples used to travel through as NaN features padded out to dim.

Parameters:
Return type:

ndarray

vectorize(item, kind, *, dim=16, embedder=None)[source]

Map a raw item of modality kind to a fixed dim vector (see module docstring).

Parameters:

  • item (Any) – the raw item (a string, a record, an image array, a signal array).

  • kind (str) – 'text' | 'record' | 'image' | 'signal'.

  • dim (int) – output vector dimension.

  • embedder (Any) – required for text/record: a fitted Embedder defining the shared coordinate system the vector lives in.

Raises:

ValueError – for text/record without an embedder. There is no safe default. The fallback used to fit a fresh autoencoder on four copies of the single item being transformed, so every call returned coordinates from a different learned basis while presenting them as a common fixed-length vector. Independently vectorized "alpha alpha" and "beta beta" came out at cosine +0.81; fitting the same two items in one shared corpus space gave -0.77. Neither sign nor magnitude survived, so any downstream correlation/graph/distance built from such vectors measured the fitting noise of single-item autoencoders. Fit one space with fit_embedder() and pass it here, or vectorize the whole corpus at once with vectorize_all(), which fits and applies a single shared embedder.

Return type:

ndarray

vectorize_all(items, kind, *, dim=16)[source]

Vectorize a sequence of same-modality items to an (n, dim) array (one shared embedder for text).

Parameters:
Return type:

ndarray