API reference

The API reference is generated from the package’s source docstrings on every documentation build.

Estimators

class overlapindex.OverlapIndex(rho=0.9, r_hat=np.inf, model_type='MiniBatchKMeans', match_tracking='MT+', kmeans_k=8, kmeans_kwargs=None, ballcover_k='auto', ballcover_radius=0.25, ballcover_kwargs=None, offline_chunk_size=10_000, multilabel_pair_mode='all', top_m=None, exclude_classes=None)[source]

Bases: BaseEstimator

Compute an overlap index over class-owned clustering prototypes.

The class supports centroid-style offline backends by default, along with ARTMAP-style online backends when explicitly selected. All samples are preprocessed before being passed to the backend. The index is updated by comparing each sample’s best matching unit against competing class-owned clusters.

Initialize the overlap index and its clustering backend.

Parameters:

  • rho (float, default=0.9) – ARTMAP vigilance parameter used by Fuzzy and Hypersphere backends.

  • r_hat (float, default=np.inf) – Hypersphere ARTMAP radius constraint.

  • model_type ({"Fuzzy", "Hypersphere", "KMeans", "MiniBatchKMeans", "BallCover"}, default="MiniBatchKMeans") – Backend family used to create class-owned clusters.

  • match_tracking (str, default="MT+") – Match-tracking mode forwarded to ARTMAP partial-fit calls.

  • kmeans_k (int or dict, default=8) – Number of clusters per class for centroid backends. A dictionary may specify class-specific values.

  • kmeans_kwargs (dict, optional) – Keyword arguments forwarded to the selected centroid backend.

  • ballcover_k (int, dict, or "auto", default="auto") – Number of balls per class, class-specific ball counts, or “auto” to greedily add fixed-radius balls until the requested cover fraction is reached.

  • ballcover_radius (float, dict, or "auto", default=0.25) – Ball radius, class-specific radii, or “auto” to infer the radius after selecting a fixed number of balls. Only one of ballcover_k and ballcover_radius may be “auto”.

  • ballcover_kwargs (dict, optional) – Additional keyword arguments forwarded to the BallCover backend, such as metric, cover_fraction, chunk_size, max_balls, or random_state.

  • offline_chunk_size (int or None, default=10000) – Number of samples per chunk for optimized offline centroid scoring. If None, each class block is scored at once.

  • multilabel_pair_mode ({"all", "top_m"}, default="all") – Competitor-pair selection mode used only for multi-label offline scoring.

  • top_m (int, optional) – Number of nearest competing labels per source label when multilabel_pair_mode is “top_m”.

  • exclude_classes (None, scalar label, or iterable of labels, optional) – Label ids to exclude from the global index and weighted_index aggregation. Excluded labels remain fully involved in fitting, singleton scoring, pairwise scoring, and all bookkeeping outputs.

set_params(**params)[source]

Update estimator parameters and rebuild the backend adapter.

Parameters:

params (Any)

Return type:

OverlapIndex

property weighted_index: float

Return the support-weighted overlap index across observed classes.

The default index is a macro average over per-class scores. This property weights each per-class score by that class’s positive support.

property module_a: Any

Return the underlying ARTMAP module A object for ARTMAP backends.

property map: Any | None

Return the underlying ARTMAP map object when available.

get_top2_bmu(x)[source]

Return the first and second global BMU ids for one preprocessed sample.

Parameters:

x (np.ndarray) – A single sample that has already been transformed by _prep_X.

Returns:

The best and second-best global cluster ids. Missing entries are None.

Return type:

tuple of int or None

predict_subset_pairs(x, y)[source]

Return top-2 candidate cluster ids for comparisons between one class and all others.

The candidate sets are taken from self.rev_map to preserve the historical replay semantics used by add_batch and fit_offline.

Parameters:

  • x (ndarray)

  • y (Any)

Return type:

Dict[Any, Tuple[int, …]]

add_sample(x, y)[source]

Incrementally add one labeled sample and update the overlap index.

This method is available only for ARTMAP-style backends. Centroid backends are offline-only and should use fit_offline or add_batch.

Parameters:

  • x (ndarray)

  • y (Any)

Return type:

float

add_batch(X, Y)[source]

Add a labeled batch and update the overlap index.

ARTMAP backends perform a batch partial-fit followed by historical replay. Offline centroid backends delegate to fit_offline with reset_state=True.

Parameters:

  • X (ndarray)

  • Y (Any)

Return type:

float

fit(X, Y)[source]

Fit the overlap index on a complete labeled dataset.

This sklearn-style method delegates to fit_offline with reset_state=True and returns self. The computed overlap index is available through the index attribute.

Parameters:

  • X (np.ndarray) – Raw input samples.

  • Y (np.ndarray) – Class labels aligned with X.

Returns:

The fitted overlap-index instance.

Return type:

OverlapIndex

partial_fit(X, Y)[source]

Update the overlap index from a labeled batch and return self.

For ARTMAP backends, this performs an incremental batch update. For offline backends, this behaves like add_batch, which refits the backend on the provided batch and recomputes the index.

Parameters:

  • X (np.ndarray) – Raw input samples.

  • Y (np.ndarray) – Class labels aligned with X.

Returns:

The updated overlap-index instance.

Return type:

OverlapIndex

score(X=None, Y=None)[source]

Return the current overlap-index score.

If X and Y are provided together, refit on that labeled dataset first.

Parameters:

  • X (ndarray | None)

  • Y (ndarray | None)

Return type:

float

predict(X)[source]

Return the highest-scoring global prototype id for each sample.

Parameters:

X (ndarray)

Return type:

ndarray

fit_predict(X, Y)[source]

Fit the estimator and return per-sample global prototype ids.

Parameters:

  • X (ndarray)

  • Y (ndarray)

Return type:

ndarray

fit_offline(X, Y, reset_state=True)[source]

Fit the backend on a full labeled dataset and compute the overlap index.

Centroid backends use a chunked vectorized class-pair scoring path. Other backends fall back to replaying samples with backend top-k hooks.

Parameters:

  • X (np.ndarray) – Raw input samples.

  • Y (np.ndarray) – Class labels aligned with X.

  • reset_state (bool, default=True) – If True, reset overlap-index bookkeeping and construct a fresh backend. False is supported only for ARTMAP continuation.

Returns:

The current overlap index value.

Return type:

float

class overlapindex.ContinuousOverlapIndex(rho=0.9, r_hat=np.inf, model_type='MiniBatchKMeans', match_tracking='MT+', kmeans_k=8, kmeans_kwargs=None, ballcover_k='auto', ballcover_radius=0.25, ballcover_kwargs=None, offline_chunk_size=10_000, target_cover='auto', n_target_cells='auto', target_cover_kwargs=None, target_distance='auto', adjacency_mode='soft_topk', top_k=5, feature_temperature=1.0, normalization='permutation', null_mode='auto', n_null_permutations=20, auto_null_work_threshold=100_000, aggregation='support_weighted', target_scaling='standard', n_projections=64, random_state=None)[source]

Bases: BaseEstimator

Compute an overlap index for continuous regression targets.

The estimator builds target-space cells, fits class-owned feature prototypes using those cells as pseudo-labels, and scores feature-space prototype overlap by empirical target-distribution disagreement. The score is normalized by a permutation null so that 1.0 indicates no observed overlap, values between 0.0 and 1.0 indicate partial separation, and 0.0 indicates complete or permutation-equivalent overlap. Worse-than-null loss remains at the 0.0 lower endpoint and is exposed through loss_ratio_.

Initialize the continuous-target overlap estimator.

Parameters:

  • rho (float, default=0.9) – Reserved ARTMAP vigilance parameter. Continuous-target ARTMAP backends are not supported in the current offline implementation.

  • r_hat (float, default=np.inf) – Reserved Hypersphere ARTMAP radius constraint.

  • model_type ({"KMeans", "MiniBatchKMeans", "BallCover"}, default="MiniBatchKMeans") – Offline backend used to build feature-space prototypes. "Fuzzy" and "Hypersphere" are accepted by the type signature for API consistency but raise NotImplementedError during fitting.

  • match_tracking (str, default="MT+") – Reserved ARTMAP match-tracking setting.

  • kmeans_k (int or dict, default=8) – Number of feature prototypes per target cell for KMeans backends, or a dictionary keyed by every target-cell id.

  • kmeans_kwargs (dict, optional) – Keyword arguments forwarded to the selected scikit-learn centroid backend. An explicit random_state here overrides the top-level seed for feature-prototype fitting.

  • ballcover_k (int, dict, or "auto", default="auto") – Number of balls per target cell, cell-specific counts, or "auto" for greedy fixed-radius covering.

  • ballcover_radius (float, dict, or "auto", default=0.25) – Ball radius, cell-specific radii, or "auto" when a fixed number of balls should determine the radius. Exactly one of ballcover_k and ballcover_radius may be "auto".

  • ballcover_kwargs (dict, optional) – Additional options forwarded to BallCover. An explicit random_state here overrides the top-level seed for the backend.

  • offline_chunk_size (int or None, default=10000) – Maximum row block used for feature-prototype adjacency scoring. None scores each available row block at once.

  • target_cover ({"auto", "quantile", "kmeans"}, default="auto") – Target-space cell construction. Auto selects quantiles for a univariate target and KMeans for multivariate targets.

  • n_target_cells (int or "auto", default="auto") – Requested number of target cells. Auto uses a sample-size-dependent value between 8 and 64, capped by the sample count.

  • target_cover_kwargs (dict, optional) – Extra keyword arguments forwarded to target-space KMeans.

  • target_distance ({"auto", "wasserstein", "sliced_wasserstein"}, default="auto") – Distance between empirical target distributions. Auto selects 1D Wasserstein distance for a univariate target and sliced Wasserstein distance for multivariate targets.

  • adjacency_mode ({"hard_top1", "soft_topk"}, default="soft_topk") – Rule used to connect each own feature prototype to competing prototypes.

  • top_k (int, default=5) – Maximum number of non-own competitors receiving adjacency mass in "soft_topk" mode.

  • feature_temperature (float, default=1.0) – Positive softmax temperature for soft top-k adjacency. Lower values concentrate mass on the strongest competitor.

  • normalization ({"permutation"}, default="permutation") – Continuous-index calibration method. Permutation is currently the only supported value.

  • null_mode ({"auto", "refit_permutation", "fixed_structure_permutation"}, default="auto") – Permutation-null strategy. Auto switches from refitting to the approximate fixed-structure mode at auto_null_work_threshold.

  • n_null_permutations (int, default=20) – Number of shuffled target assignments used to estimate null loss.

  • auto_null_work_threshold (int, default=100000) – Auto-mode cutoff applied to n_samples * n_null_permutations.

  • aggregation ({"support_weighted", "macro"}, default="support_weighted") – Aggregation used for the public index value.

  • target_scaling ({"standard", "none", "minmax", "robust"}, default="standard") – Scaling applied to target columns before cell construction and target-distribution distances.

  • n_projections (int, default=64) – Number of random directions used by sliced Wasserstein distance.

  • random_state (int, optional) – Seed for target-cell construction, sliced-Wasserstein projections, null permutations, and backend fitting when no backend-specific seed is provided.

property weighted_index: float

Return the support-weighted continuous overlap index.

set_params(**params)[source]

Update estimator parameters and clear fitted state.

Parameters:

params (Any)

Return type:

ContinuousOverlapIndex

fit(X, Y)[source]

Fit the estimator and store the current continuous overlap index.

Parameters:

  • X (ndarray)

  • Y (ndarray)

Return type:

ContinuousOverlapIndex

partial_fit(X, Y)[source]

Refit the continuous overlap index on the provided batch.

V1 supports the same refit semantics as offline OverlapIndex backends. True incremental continuous-target updates are intentionally deferred.

Parameters:

  • X (ndarray)

  • Y (ndarray)

Return type:

ContinuousOverlapIndex

add_batch(X, Y)[source]

Fit on a batch and return the current index.

Parameters:

  • X (ndarray)

  • Y (ndarray)

Return type:

float

score(X=None, Y=None)[source]

Return the current score, or refit and return a score.

Parameters:

  • X (ndarray | None)

  • Y (ndarray | None)

Return type:

float

predict(X)[source]

Return the highest-scoring global prototype id for each sample.

Parameters:

X (ndarray)

Return type:

ndarray

fit_predict(X, Y)[source]

Fit the estimator and return per-sample global prototype ids.

Parameters:

  • X (ndarray)

  • Y (ndarray)

Return type:

ndarray

fit_offline(X, Y, reset_state=True)[source]

Fit the backend on a complete regression dataset and compute COI.

Parameters:

  • X (ndarray)

  • Y (ndarray)

  • reset_state (bool)

Return type:

float

predict returns global prototype ids for both estimators; it is not a class-label or continuous-target prediction method. See Getting started for method return values and Diagnostics and troubleshooting for fitted attributes.

Ball-cover backend

class overlapindex.BallCover.BallCoverManyToOne(k='auto', radius=0.25, metric='auto', high_dim_threshold=128, cover_fraction=1.0, selection='greedy_uncovered', chunk_size=8192, max_balls=None, store_memberships=False, dtype=np.float32, random_state=None)[source]

Bases: object

Offline greedy ball-cover backend with many-to-one class ownership.

Parameters:

  • k (int, dict, or "auto", default="auto") – Number of balls per class, class-specific ball counts, or "auto". If k='auto', radius must be numeric.

  • radius (float, dict, or "auto", default=0.25) – Ball radius, class-specific radii, or "auto". If radius='auto', k must be an integer or class-specific integer dictionary.

  • metric ({"auto", "euclidean", "cosine"}, default="auto") – Distance geometry. "auto" resolves to cosine when the feature dimension is at least high_dim_threshold and Euclidean otherwise. Cosine mode internally L2-normalizes rows and uses Euclidean chord distance on the unit sphere.

  • high_dim_threshold (int, default=128) – Feature dimension at which metric='auto' switches to cosine.

  • cover_fraction (float, default=1.0) – Target fraction of each class to cover. Values must be in (0, 1]. For fixed-radius mode, greedy selection stops after this fraction is covered. For fixed-k mode, radius is chosen from the upper empirical order statistic that guarantees at least this observed coverage.

  • selection ({"greedy_uncovered", "farthest"}, default="greedy_uncovered") – Center-selection policy. "greedy_uncovered" chooses subsequent centers among currently uncovered samples. "farthest" chooses the farthest sample overall from the current landmark set.

  • chunk_size (int, default=8192) – Number of rows processed at a time in distance computations. The current implementation mainly uses matrix-vector distance updates, so this is a safeguard for very large arrays and query matrices.

  • max_balls (int, optional) – Maximum number of balls allowed per class in k='auto' mode.

  • store_memberships (bool, default=False) – If true, store training-set member indices for each ball. Memberships are temporary otherwise and discarded after fitting.

  • dtype (numpy floating dtype, default=np.float32) – Floating-point dtype used for stored centers and working arrays.

  • random_state (int, optional) – Seed used only for deterministic tie-breaking, if needed.

Notes

Scores follow the convention “higher is better”:

score_j(x) = 1 - d(x, center_j)^2 / radius_j^2.

Thus, for a given ball, positive scores indicate that x lies inside the ball, zero indicates the boundary, and negative scores indicate that x lies outside the ball.

fit_offline(X, Y)[source]

Fit one greedy ball cover per class and concatenate global balls.

Parameters:

  • X (ndarray)

  • Y (ndarray)

Return type:

None

partial_fit(X, Y, **kwargs)[source]

Raise because this backend is offline-only.

Parameters:

  • X (ndarray)

  • Y (ndarray)

  • kwargs (Any)

Return type:

None

bmu_for_class(x, y)[source]

Return the highest-scoring ball owned by class y.

Parameters:

  • x (ndarray)

  • y (Any)

Return type:

int

bmu_for_class_batch(X, Y)[source]

Return class-restricted BMUs for a batch.

Parameters:

  • X (ndarray)

  • Y (ndarray)

Return type:

ndarray

scores_all(x)[source]

Return one score per global ball for a sample.

Parameters:

x (ndarray)

Return type:

ndarray

topk(x, k, candidate_ids=None)[source]

Return top-k ball ids and scores, optionally restricted to candidates.

Parameters:

  • x (ndarray)

  • k (int)

  • candidate_ids (Sequence[int] | None)

Return type:

Tuple[ndarray, ndarray]

top2_for_class_pair(x, own_class, other_class)[source]

Return top-2 balls among the union of two class-owned ball sets.

Parameters:

  • x (ndarray)

  • own_class (Any)

  • other_class (Any)

Return type:

Tuple[ndarray, ndarray]

property centers: ndarray

Return global ball-center matrix.

property radii: ndarray

Return one radius per global ball.

property resolved_metric: str | None

Return the metric chosen during fitting.

property class_center_id_arrays: Dict[Any, ndarray]

Alias for class-to-ball id arrays, matching centroid backend naming.

property class_ball_id_arrays: Dict[Any, ndarray]

Return class-to-global-ball-id mappings as NumPy arrays.

property cluster_to_class: ndarray | None

Return array mapping global ball ids to class labels.

property class_to_clusters: Dict[Any, set]

Return class-to-global-ball-id mappings as sets.

property n_clusters_total: int

Return total number of global balls.

property ball_to_points: Dict[int, ndarray] | None

Return optional training memberships, if stored.

property diagnostics: Dict[str, Any]

Return fit-level diagnostics.

property class_diagnostics: Dict[Any, Dict[str, Any]]

Return class-level fit diagnostics.

The ball-cover class is primarily a backend integration surface. Most users should configure it through OverlapIndex(model_type="BallCover", ...) or ContinuousOverlapIndex(model_type="BallCover", ...); see BallCover.