zen_mapper.cover module

class Data_Balanced_Cover(n_elements, percent_overlap)

Bases: object

A cover of 1D data with roughly equal data points per interval.

The cover is constructed by partitioning the sorted indices \([0, \dots, N-1]\) into intervals of approximately equal size, then mapping those index-regions back to the original data positions.

Each bin has a base size and step calculated as:

\[base\_size = \frac{N}{k - (k - 1) \times \text{overlap}} \]
\[step = base\_size \times (1 - \text{overlap}) \]

where \(k\) is n_elements.

Parameters:

  • n_elements (int) – The number of intervals (cover elements) to create. Must be \(\ge 1\).

  • percent_overlap (float) – The fractional overlap between adjacent intervals, \(0 < \text{overlap} < 1\).

n_elements

The number of cover elements.

Type:

int

percent_overlap

The fractional overlap.

Type:

float

Raises:

ValueError – If n_elements < 1 or percent_overlap is not in the range (0, 1).

Parameters:

  • n_elements (int)

  • percent_overlap (float)

Notes

A percent_overlap of 0.5 means each interval shares approximately 50% of its points with the subsequent interval.

class Width_Balanced_Cover(n_elements, percent_overlap)

Bases: object

A cover comprised of equally sized rectangular elements

Parameters:

  • n_elements (ArrayLike) – The number of covering elements along each dimension. If the data is dimension $d$ and this is a scalar $n$ this results in $n^d$ covering elements.

  • percent_overlap (float) – a number between 0 and 1 representing the ammount of overlap between adjacent covering elements.

Raises:

  • Value Error – if n_elements < 1

  • Value Error – if percent_overlap is not in (0,1)

precomputed_cover(cover)

A precomputed cover

Parameters:

cover (Cover) – the precomputed cover to use

Return type:

CoverScheme

rectangular_cover(centers, widths, data, tol=1e-09)

Partition data points into multi-dimensional rectangular cover elements.

Note

This is a low-level structural function that requires pre-computed bounding box geometries. For most use cases, you should use width_balanced_cover or data_balanced_cover instead, which handle the geometry generation automatically.

Parameters:

  • centers (ndarray) – The coordinates of the centers for each hyper-rectangle. Shape should be (n_centers, n_features) or (n_centers,).

  • widths (ndarray) – The width of the covering elements. Must be broadcastable against the feature dimensions (e.g., a scalar or a 1D array of shape (n_features,)).

  • data (ndarray) – The dataset to be partitioned into the cover elements. Shape should be (n_samples, n_features) or (n_samples,).

  • tol (float, default: 1e-09) – A small numerical tolerance added to the boundary calculations to prevent floating-point precision issues for points resting exactly on an edge. Defaults to 1e-9.

Returns:

list[ndarray] – A list of length n_centers. Each entry is a 1D array of integers containing the row indices of data that fall inside that specific rectangular cover element.

Return type:

list[ndarray]

See also

width_balanced_cover: compute a cover comprised of equally sized rectangular elements.

data_balanced_cover compute a cover where each element has the same number of data points.