BallCover

BallCover is the package’s offline greedy geometric backend. It fits a separate set of landmark balls for each label and treats every ball as a class-owned prototype. Unlike the centroid backends, it explicitly represents a support radius around each landmark.

When to use it

Choose BallCover when preserving the shape or extent of class support matters, such as non-convex distributions or embedding spaces where a centroid-only summary is too coarse. It supports multi-label targets but requires dense feature arrays.

metric="auto" selects Euclidean geometry below the configured high-dimensional threshold and cosine geometry for higher-dimensional inputs. Cosine mode normalizes rows internally and uses chord distance on the unit sphere.

Invocation

BallCover permits one automatic structural parameter at a time.

Use a fixed radius and automatically add balls until the requested coverage is reached:

oi = OverlapIndex(
    model_type="BallCover",
    ballcover_k="auto",
    ballcover_radius=0.25,
    ballcover_kwargs={
        "metric": "auto",
        "cover_fraction": 1.0,
        "random_state": 0,
    },
)

Or select a fixed number of landmarks and infer the radius:

oi = OverlapIndex(
    model_type="BallCover",
    ballcover_k=40,
    ballcover_radius="auto",
    ballcover_kwargs={"metric": "euclidean", "random_state": 0},
)
oi.fit(X, y)

Tuning guidance

  • Smaller fixed radii usually produce more balls and finer support detail.

  • Larger ballcover_k provides more landmarks when radius is automatic.

  • cover_fraction below 1.0 allows the cover to ignore a tail of samples and can reduce sensitivity to outliers.

  • Set max_balls to cap work in automatic-count mode.

  • Override metric="auto" when domain knowledge favors Euclidean or cosine geometry.

  • Use chunk_size to bound distance-computation batches.

BallCover is offline-only: partial_fit refits on the provided batch and add_sample is unsupported. See examples/wine_ballcover.py and the API reference reference for the backend’s complete parameter documentation.