fast-ballmapper 0.0.1__py3-none-any.whl

fast_ballmapper/__init__.py

@@ -0,0 +1,37 @@
+"""Fast construction and analysis of Ball Mapper graphs."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from fast_ballmapper.coloring import (
+    color_by_density,
+    color_by_entropy,
+    color_by_function,
+    color_by_mode,
+    color_by_size,
+)
+from fast_ballmapper.faiss import FaissConfig
+from fast_ballmapper.graph import build_mapper, compute_edge_overlaps
+from fast_ballmapper.landmarks import (
+    build_cover,
+    compute_landmarks,
+    compute_landmarks_fps,
+)
+
+try:
+    __version__ = version("fast-ballmapper")
+except PackageNotFoundError:  # pragma: no cover - source checkout fallback
+    __version__ = "0.1.0"
+
+__all__ = [
+    "FaissConfig",
+    "build_cover",
+    "build_mapper",
+    "color_by_density",
+    "color_by_entropy",
+    "color_by_function",
+    "color_by_mode",
+    "color_by_size",
+    "compute_edge_overlaps",
+    "compute_landmarks",
+    "compute_landmarks_fps",
+]

fast_ballmapper/_validation.py

@@ -0,0 +1,91 @@
+"""Validation helpers shared by Ball Mapper algorithms."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+
+
+def validate_point_cloud(x: np.ndarray, eps: float) -> np.ndarray:
+    """Validate and normalize point-cloud inputs."""
+    x = np.asarray(x)
+
+    if x.ndim != 2:
+        raise ValueError("x must be a 2D array with shape (n_samples, n_features).")
+    if x.shape[0] > 0 and x.shape[1] == 0:
+        raise ValueError("x must contain at least one feature.")
+    if not np.issubdtype(x.dtype, np.number):
+        raise TypeError("x must contain numeric values.")
+    if not np.all(np.isfinite(x)):
+        raise ValueError("x must contain only finite values.")
+    if not np.isscalar(eps) or not np.isfinite(eps) or eps < 0:
+        raise ValueError("eps must be a finite, non-negative scalar.")
+
+    return x
+
+
+def validate_leaf_size(leaf_size: int) -> None:
+    """Validate a BallTree leaf size."""
+    if not isinstance(leaf_size, (int, np.integer)) or leaf_size <= 0:
+        raise ValueError("leaf_size must be a positive integer.")
+
+
+def normalize_backend_options(
+    method: str,
+    metric: str,
+    leaf_size: int,
+    metric_kwargs: Mapping[str, Any] | None,
+) -> tuple[str, str, dict[str, Any]]:
+    """Normalize backend options and reject unsupported combinations."""
+    if not isinstance(method, str):
+        raise TypeError("method must be a string.")
+    if not isinstance(metric, str):
+        raise TypeError("metric must be a string.")
+
+    method_key = method.lower().replace("-", "_")
+    metric_key = metric.lower()
+    normalized_metric_kwargs = dict(metric_kwargs or {})
+
+    # ``balltree`` is accepted as a forgiving alias, while ``ball_tree`` is the
+    # documented snake_case spelling.
+    if method_key == "balltree":
+        method_key = "ball_tree"
+
+    if method_key not in {"ball_tree", "faiss"}:
+        raise ValueError("method must be 'ball_tree' or 'faiss'.")
+
+    if method_key == "ball_tree":
+        validate_leaf_size(leaf_size)
+    else:
+        if metric_key not in {"euclidean", "cosine"}:
+            raise ValueError(
+                "For method='faiss', metric must be 'euclidean' or 'cosine'."
+            )
+        if normalized_metric_kwargs:
+            raise ValueError("metric_kwargs is supported only with method='ball_tree'.")
+
+    return method_key, metric_key, normalized_metric_kwargs
+
+
+def validate_start_index(start_index: int | None, n_samples: int) -> None:
+    """Validate an optional farthest-point-sampling start index."""
+    if start_index is None:
+        return
+    if not isinstance(start_index, (int, np.integer)):
+        raise TypeError("start_index must be an integer or None.")
+    if not 0 <= int(start_index) < n_samples:
+        raise IndexError("start_index is out of bounds for x.")
+
+
+def lexicographically_smallest_index(x: np.ndarray) -> int:
+    """Return the row index ordered by feature 0, then feature 1, and so on."""
+    keys = tuple(x[:, column] for column in range(x.shape[1] - 1, -1, -1))
+    return int(np.lexsort(keys)[0])
+
+
+def validate_cosine_points(points: np.ndarray) -> None:
+    """Reject zero vectors, for which cosine distance is undefined."""
+    if np.any(np.linalg.norm(points, axis=1) == 0):
+        raise ValueError("Cosine distance is undefined for zero vectors.")

fast_ballmapper/backends/__init__.py

@@ -0,0 +1 @@
+"""Internal nearest-neighbor backends for fast_ballmapper."""

fast_ballmapper/backends/_ball_tree.py

@@ -0,0 +1,88 @@
+"""scikit-learn BallTree backend."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import numpy as np
+
+try:
+    from sklearn.neighbors import BallTree
+except ImportError:  # pragma: no cover - dependency is required by project metadata
+    BallTree = None  # type: ignore[assignment,misc]
+
+
+def create_ball_tree(
+    x: np.ndarray,
+    metric: str,
+    leaf_size: int,
+    metric_kwargs: Mapping[str, Any],
+):
+    """Create a BallTree with one shared metric configuration."""
+    if BallTree is None:
+        raise ImportError("scikit-learn is required for method='ball_tree'.")
+    return BallTree(
+        x,
+        metric=metric,
+        leaf_size=leaf_size,
+        **metric_kwargs,
+    )
+
+
+def compute_landmarks_ball_tree(
+    x: np.ndarray,
+    eps: float,
+    metric: str,
+    leaf_size: int,
+    metric_kwargs: Mapping[str, Any] | None = None,
+) -> tuple[list[int], list[np.ndarray]]:
+    """Compute greedy landmarks and covers with BallTree radius queries."""
+    tree = create_ball_tree(x, metric, leaf_size, dict(metric_kwargs or {}))
+    uncovered = np.ones(x.shape[0], dtype=bool)
+    landmarks: list[int] = []
+    cover: list[np.ndarray] = []
+
+    while np.any(uncovered):
+        landmark_index = int(np.argmax(uncovered))
+        landmarks.append(landmark_index)
+        point_indices = tree.query_radius(x[landmark_index : landmark_index + 1], eps)[
+            0
+        ]
+        cover.append(point_indices)
+        uncovered[point_indices] = False
+
+    return landmarks, cover
+
+
+def distances_to_all(
+    x: np.ndarray,
+    tree,
+    point_index: int,
+) -> np.ndarray:
+    """Return distances from one point to every row of ``x`` in row order."""
+    distances, indices = tree.query(
+        x[point_index : point_index + 1],
+        k=x.shape[0],
+        return_distance=True,
+    )
+    result = np.empty(x.shape[0], dtype=float)
+    result[indices[0]] = distances[0]
+    return result
+
+
+def build_cover_ball_tree(
+    x: np.ndarray,
+    landmarks: Sequence[int],
+    eps: float,
+    metric: str = "euclidean",
+    leaf_size: int = 40,
+    metric_kwargs: Mapping[str, Any] | None = None,
+    *,
+    tree=None,
+) -> list[np.ndarray]:
+    """Build epsilon-ball covers for fixed landmarks using BallTree."""
+    if tree is None:
+        tree = create_ball_tree(x, metric, leaf_size, dict(metric_kwargs or {}))
+
+    return [tree.query_radius(x[index : index + 1], eps)[0] for index in landmarks]