sphncs 0.3.1__py3-none-any.whl

sphncs/__init__.py

@@ -0,0 +1,8 @@
+"""Similarity-Preserving Hierarchical Nonparametric Clustering System."""
+
+from .estimator import SphncsClusterer
+from .logs import LogSPHNCS
+from .persistence import ModelPersistenceError
+from .preprocessing import LogPreprocessor
+
+__all__ = ["LogPreprocessor", "LogSPHNCS", "ModelPersistenceError", "SphncsClusterer"]

sphncs/density.py

@@ -0,0 +1,81 @@
+"""One-dimensional KDE evaluation, extrema, labels, and representatives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.signal import find_peaks
+
+
+@dataclass
+class DensityModel:
+    grid: np.ndarray
+    density: np.ndarray
+    boundaries: np.ndarray
+    modes: np.ndarray
+    labels: np.ndarray
+    representative_indices: np.ndarray
+
+    def predict(self, values: np.ndarray) -> np.ndarray:
+        return np.searchsorted(self.boundaries, values, side="right").astype(int)
+
+
+def fit_density(
+    values: np.ndarray,
+    *,
+    bandwidth: str | float = "ISJ",
+    grid_points: int = 1024,
+    prominence: float | None = None,
+    prominence_fraction: float = 0.05,
+    min_samples: int = 3,
+) -> DensityModel:
+    """Fit FFTKDE and turn meaningful minima into interval labels."""
+    values = np.asarray(values, dtype=float).reshape(-1)
+    if values.size == 0:
+        raise ValueError("KDE requires at least one value")
+    lower, upper = float(values.min()), float(values.max())
+    if values.size < min_samples or np.isclose(lower, upper):
+        grid = np.linspace(lower - 0.5, upper + 0.5 if upper >= lower else lower + 0.5, max(2, grid_points))
+        density = np.zeros_like(grid)
+        mode = np.array([float(values.mean())])
+        labels = np.zeros(values.size, dtype=int)
+        return DensityModel(grid, density, np.array([], dtype=float), mode, labels, np.array([int(np.argmin(abs(values - mode[0])))]) )
+
+    padding = max((upper - lower) * 0.1, np.finfo(float).eps * 100)
+    grid = np.linspace(lower - padding, upper + padding, grid_points)
+    try:
+        from KDEpy import FFTKDE
+    except ImportError as exc:  # pragma: no cover - dependency declaration is authoritative
+        raise ImportError("KDEpy is required; install sphncs with its runtime dependencies.") from exc
+    try:
+        density = np.asarray(FFTKDE(kernel="gaussian", bw=bandwidth).fit(values).evaluate(grid), dtype=float)
+    except ValueError:
+        # ISJ can fail to find a root for small, highly discrete partitions.
+        # Keep an explicit user-selected bandwidth strict, but make the default
+        # automatic choice robust by falling back to another KDEpy rule.
+        if not isinstance(bandwidth, str) or bandwidth.upper() != "ISJ":
+            raise
+        density = np.asarray(FFTKDE(kernel="gaussian", bw="silverman").fit(values).evaluate(grid), dtype=float)
+    scale = float(np.ptp(density))
+    effective_prominence = (
+        prominence
+        if prominence is not None
+        else max(scale * prominence_fraction, np.finfo(float).eps)
+    )
+    minima, _ = find_peaks(-density, prominence=effective_prominence)
+    boundaries = grid[minima]
+    labels = np.searchsorted(boundaries, values, side="right").astype(int)
+
+    modes: list[float] = []
+    representatives: list[int] = []
+    for label in range(len(boundaries) + 1):
+        left = -np.inf if label == 0 else boundaries[label - 1]
+        right = np.inf if label == len(boundaries) else boundaries[label]
+        mask = (grid > left) & (grid <= right)
+        mode = float(grid[mask][np.argmax(density[mask])])
+        members = np.flatnonzero(labels == label)
+        if members.size:
+            modes.append(mode)
+            representatives.append(int(members[np.argmin(abs(values[members] - mode))]))
+    return DensityModel(grid, density, boundaries, np.asarray(modes), labels, np.asarray(representatives, dtype=int))

sphncs/distances.py

@@ -0,0 +1,99 @@
+"""Reusable distance metrics for SPHNCS object spaces."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Callable, Iterable
+from functools import lru_cache
+from math import inf, isfinite
+from numbers import Real
+
+Metric = Callable[[object, object], float]
+StringMetric = Callable[[str, str], float]
+
+
+def lp_distance(left: Iterable[Real], right: Iterable[Real], p: Real = 2) -> float:
+    """Return Minkowski Lp distance between two equally sized numeric vectors.
+
+    ``p`` must be at least one. ``p=float('inf')`` returns the Chebyshev
+    (L-infinity) distance. Inputs are materialized once so any finite iterable
+    of real values is accepted.
+    """
+    if isinstance(p, bool) or not isinstance(p, Real) or p < 1:
+        raise ValueError("p must be a real number greater than or equal to 1")
+    left_values = tuple(left)
+    right_values = tuple(right)
+    if len(left_values) != len(right_values):
+        raise ValueError("vectors must have equal lengths")
+    try:
+        differences = [abs(float(a) - float(b)) for a, b in zip(left_values, right_values)]
+    except (TypeError, ValueError) as exc:
+        raise TypeError("vectors must contain real numeric values") from exc
+    if not all(isfinite(value) for value in differences):
+        raise ValueError("vectors must contain finite numeric values")
+    if p == inf:
+        return max(differences, default=0.0)
+    return float(sum(value**p for value in differences) ** (1 / p))
+
+
+def l1_distance(left: Iterable[Real], right: Iterable[Real]) -> float:
+    """Return Manhattan (L1) distance between numeric vectors."""
+    return lp_distance(left, right, p=1)
+
+
+def l2_distance(left: Iterable[Real], right: Iterable[Real]) -> float:
+    """Return Euclidean (L2) distance between numeric vectors."""
+    return lp_distance(left, right, p=2)
+
+
+@lru_cache(maxsize=32_768)
+def _char_ngram_counts(value: str, ngram_size: int) -> Counter[str]:
+    """Build a multiset of character shingles once per immutable input string."""
+    return Counter(value[i : i + ngram_size] for i in range(max(1, len(value) - ngram_size + 1)))
+
+
+def normalized_levenshtein(left: str, right: str) -> float:
+    """Levenshtein edit distance normalized to the interval [0, 1]."""
+    if left == right:
+        return 0.0
+    if not left or not right:
+        return 1.0
+    if len(left) < len(right):
+        left, right = right, left
+    previous = list(range(len(right) + 1))
+    for i, char_left in enumerate(left, start=1):
+        current = [i]
+        for j, char_right in enumerate(right, start=1):
+            current.append(min(current[-1] + 1, previous[j] + 1, previous[j - 1] + (char_left != char_right)))
+        previous = current
+    return previous[-1] / len(left)
+
+
+def char_ngram_jaccard(left: str, right: str, ngram_size: int = 3) -> float:
+    """Multiset character n-gram Jaccard distance."""
+    if ngram_size < 1:
+        raise ValueError("ngram_size must be positive")
+    if left == right:
+        return 0.0
+    grams_left = _char_ngram_counts(left, ngram_size)
+    grams_right = _char_ngram_counts(right, ngram_size)
+    union = sum((grams_left | grams_right).values())
+    return 1.0 - sum((grams_left & grams_right).values()) / union if union else 0.0
+
+
+METRICS: dict[str, Metric] = {
+    "l1": l1_distance,
+    "l2": l2_distance,
+    "normalized_levenshtein": normalized_levenshtein,
+    "char_ngram_jaccard": char_ngram_jaccard,
+}
+
+
+def resolve_metric(metric: str | Metric) -> Metric:
+    if callable(metric):
+        return metric
+    try:
+        return METRICS[metric]
+    except KeyError as exc:
+        choices = ", ".join(sorted(METRICS))
+        raise ValueError(f"Unknown metric {metric!r}; choose one of {choices}, or pass a callable.") from exc

sphncs/embedding.py

@@ -0,0 +1,136 @@
+"""Adapter around fastmapy's batched, on-demand FastMap implementation."""
+
+from __future__ import annotations
+
+import random
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+
+
+def _load_fastmap():
+    """Import the installed package or the checked-out project submodule."""
+    try:
+        from fastmap import FastMap
+        return FastMap
+    except ImportError:
+        submodule = Path(__file__).resolve().parent.parent / "vendor" / "fastmapy"
+        if submodule.is_dir():
+            sys.path.insert(0, str(submodule))
+            try:
+                from fastmap import FastMap
+                return FastMap
+            except ImportError:
+                pass
+    raise ImportError(
+        "fastmapy is required. Install FastMapy or initialize and install the "
+        "project submodule with `git submodule update --init --recursive` and "
+        "`python -m pip install -e vendor/fastmapy`."
+    )
+
+
+class _CallableDistance:
+    """FastMapy-compatible, pickleable wrapper for an SPHNCS metric callable."""
+
+    def __init__(self, metric: Callable[[object, object], float]):
+        self.metric = metric
+
+    @staticmethod
+    def get_name() -> str:
+        return "sphncs_metric"
+
+    def calculate(self, left: object, right: object) -> float:
+        value = float(self.metric(left, right))
+        if value < 0:
+            raise ValueError("Metrics must return non-negative distances")
+        return value
+
+
+class FastMapyEmbeddings:
+    """A batch of independent one-dimensional fastmapy models.
+
+    Each model gets a distinct pivot pair through ``FastMap.fit_many``. This
+    intentionally differs from a single multi-dimensional FastMap embedding:
+    sphncs uses every independent 1-D density partition as consensus evidence.
+    """
+
+    def __init__(
+        self, n_embeddings: int, metric: Callable[[object, object], float], *,
+        random_state: int | None = None, cores: int = 1, iters: int = 3,
+        cache_distances: bool = True,
+    ):
+        if n_embeddings < 1:
+            raise ValueError("n_embeddings must be at least 1")
+        self.n_embeddings = n_embeddings
+        self.metric = metric
+        self.random_state = random_state
+        self.cores = cores
+        self.iters = iters
+        self.cache_distances = cache_distances
+
+    def fit(self, X: list[object]):
+        if not X:
+            raise ValueError("FastMap requires at least one string")
+        self.X_ = list(X)
+        if len(X) == 1:
+            self.models_ = []
+            self.coordinates_ = np.zeros((1, self.n_embeddings), dtype=float)
+            return self
+        FastMap = _load_fastmap()
+
+        count = min(self.n_embeddings, len(X))
+        # fastmapy currently draws its pivot starts from Python's module-level
+        # RNG. Restore it afterwards so fitting sphncs does not perturb callers.
+        rng_state = random.getstate()
+        try:
+            if self.random_state is not None:
+                random.seed(self.random_state)
+            self.models_ = FastMap.fit_many(
+                X,
+                count=count,
+                dim=1,
+                distance=_CallableDistance,
+                dist_args={"metric": self.metric},
+                cores=self.cores,
+                iters=self.iters,
+            )
+        finally:
+            random.setstate(rng_state)
+        coordinates = np.column_stack([np.asarray(model.transform(X), dtype=float).reshape(-1) for model in self.models_])
+        if count < self.n_embeddings:
+            coordinates = np.pad(coordinates, ((0, 0), (0, self.n_embeddings - count)))
+        self.coordinates_ = coordinates
+        return self
+
+    def fit_transform(self, X: list[object]) -> np.ndarray:
+        return self.fit(X).coordinates_.copy()
+
+    def transform(self, X: list[object]) -> np.ndarray:
+        if not hasattr(self, "models_"):
+            raise RuntimeError("FastMap must be fitted before transform")
+        if not self.models_:
+            return np.zeros((len(X), self.n_embeddings), dtype=float)
+        coordinates = np.column_stack([np.asarray(model.transform(X), dtype=float).reshape(-1) for model in self.models_])
+        if coordinates.shape[1] < self.n_embeddings:
+            coordinates = np.pad(coordinates, ((0, 0), (0, self.n_embeddings - coordinates.shape[1])))
+        return coordinates
+
+
+    def save_models(self, directory: Path) -> list[Path]:
+        """Persist each fitted projection through FastMapy's native format."""
+        if not hasattr(self, "models_"):
+            raise RuntimeError("FastMap must be fitted before it can be saved")
+        directory.mkdir(parents=True, exist_ok=True)
+        paths: list[Path] = []
+        for index, model in enumerate(self.models_):
+            path = directory / f"{index}.fastmap"
+            model.save(path)
+            paths.append(path)
+        return paths
+
+    def load_models(self, paths: list[Path]) -> None:
+        """Restore fitted projections through FastMapy's native loader."""
+        FastMap = _load_fastmap()
+        self.models_ = [FastMap.load(path) for path in paths]