forest-clustering 0.1.0__tar.gz

forest_clustering-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Kozlov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forest_clustering-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: forest-clustering
+Version: 0.1.0
+Summary: Random-partition similarity clustering for mixed-type tabular data
+Author-email: Vladislav Kozlov <vlad.kneu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/4eshireCat/forest_clustering
+Project-URL: Repository, https://github.com/4eshireCat/forest_clustering
+Project-URL: Documentation, https://github.com/4eshireCat/forest_clustering/blob/main/ALGORITHM.md
+Project-URL: Issues, https://github.com/4eshireCat/forest_clustering/issues
+Project-URL: Changelog, https://github.com/4eshireCat/forest_clustering/blob/main/CHANGELOG.md
+Keywords: clustering,unsupervised learning,random forests,tabular data,mixed data,similarity embedding
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: pandas>=2.0
+Requires-Dist: joblib>=1.3
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# forest-clustering
+
+**Random-partition similarity clustering for mixed-type tabular data.**
+
+`forest-clustering` builds a compact binary embedding from random feature partitions and then applies any sklearn-compatible clustering algorithm to that embedding. It handles numerical, categorical, and mixed data natively, with built-in correlation-based feature weighting and outlier-robust cut-point generation.
+
+## How it works
+
+Each of the *L* iterations:
+1. Samples *m* features (weighted by inverse correlation-group size).
+2. Draws *K−1* random cut-points per numerical feature (uniform or quantile-based).
+3. Assigns each sample a mixed-radix *cell ID* based on which bin it falls in for each selected feature.
+
+The result is an *n × L* integer embedding. Two samples that consistently land in the same cell are similar; Hamming distance on this embedding approximates the true similarity.
+
+```
+Hamming(i, j) = (1/L) · Σ_l [ E[i,l] ≠ E[j,l] ]  ∈ [0, 1]
+```
+
+See [ALGORITHM.md](ALGORITHM.md) for a detailed description with diagrams.
+
+## Installation
+
+```bash
+pip install forest-clustering
+```
+
+Python ≥ 3.10 required.
+
+## Quick start
+
+```python
+from forest_clustering import ForestClusterer
+from sklearn.cluster import KMeans
+
+fc = ForestClusterer(
+    n_iterations=200,
+    n_bins=3,
+    quantile_cuts=True,       # robust to outliers
+    corr_threshold=0.9,       # down-weight correlated features
+    clusterer=KMeans(n_clusters=5, n_init="auto", random_state=0),
+    random_state=42,
+)
+
+labels = fc.fit_predict(df)   # works with DataFrame or ndarray
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `n_iterations` | 200 | Number of random partitioning iterations *L*. More → more stable. |
+| `n_bins` | 3 | Number of bins per feature per iteration *K*. |
+| `n_features` | `"sqrt"` | Features selected per iteration: int, float fraction, `"sqrt"`, `"log2"`. |
+| `quantile_cuts` | `False` | Sample cut-points from empirical quantiles (robust to outliers). |
+| `corr_threshold` | 0.7 | Spearman \|r\| threshold for grouping correlated features. `None` disables. |
+| `corr_sample_size` | 10 000 | Rows used to estimate feature correlations. |
+| `clusterer` | `DBSCAN(metric="hamming")` | Any sklearn-compatible `fit_predict` estimator. |
+| `feature_types` | `None` | Override type detection: `{col: "numerical"\|"categorical"}`. |
+| `cat_threshold` | 10 | Numerical columns with ≤ this many unique values → treated as categorical. |
+| `n_jobs` | −1 | Parallelism for embedding computation (joblib). |
+| `random_state` | `None` | Seed for reproducibility. |
+
+## Downstream clustering algorithms
+
+| Algorithm | When to use |
+|---|---|
+| `KMeans(n_clusters=K)` on embedding | Known K, any n — fast and stable |
+| `AgglomerativeClustering(metric="precomputed")` | n ≤ 50 K, non-spherical clusters |
+| `DBSCAN(metric="hamming")` on embedding | Unknown K, need outlier detection |
+| `HDBSCAN(metric="precomputed")` | Variable-density clusters (pass `.astype(float64)`) |
+| `MiniBatchKMeans` on embedding | n > 100 K |
+
+```python
+from sklearn.cluster import AgglomerativeClustering
+
+fc = ForestClusterer(
+    n_iterations=300,
+    clusterer=AgglomerativeClustering(n_clusters=3, metric="precomputed", linkage="average"),
+)
+labels = fc.fit_predict(X)
+```
+
+## Utilities
+
+```python
+# Get the raw n×L embedding
+E = fc.get_embedding()
+
+# Pairwise Hamming distance matrix (chunked for large n)
+D = fc.pairwise_distance()
+
+# Transform new data using fitted partition specs
+E_new = fc.transform(X_new)
+```
+
+## Hyperparameter guidelines
+
+| Goal | Recommendation |
+|---|---|
+| Fast prototype | `n_iterations=50`, `n_bins=3` |
+| Balanced quality/speed | `n_iterations=200`, `n_bins=3` (default) |
+| High stability | `n_iterations=500`, `n_bins=4` |
+| Outlier-heavy data | `quantile_cuts=True` |
+| Many correlated features | `corr_threshold=0.8–0.9` |
+
+## License
+
+MIT

forest_clustering-0.1.0/README.md

@@ -0,0 +1,109 @@
+# forest-clustering
+
+**Random-partition similarity clustering for mixed-type tabular data.**
+
+`forest-clustering` builds a compact binary embedding from random feature partitions and then applies any sklearn-compatible clustering algorithm to that embedding. It handles numerical, categorical, and mixed data natively, with built-in correlation-based feature weighting and outlier-robust cut-point generation.
+
+## How it works
+
+Each of the *L* iterations:
+1. Samples *m* features (weighted by inverse correlation-group size).
+2. Draws *K−1* random cut-points per numerical feature (uniform or quantile-based).
+3. Assigns each sample a mixed-radix *cell ID* based on which bin it falls in for each selected feature.
+
+The result is an *n × L* integer embedding. Two samples that consistently land in the same cell are similar; Hamming distance on this embedding approximates the true similarity.
+
+```
+Hamming(i, j) = (1/L) · Σ_l [ E[i,l] ≠ E[j,l] ]  ∈ [0, 1]
+```
+
+See [ALGORITHM.md](ALGORITHM.md) for a detailed description with diagrams.
+
+## Installation
+
+```bash
+pip install forest-clustering
+```
+
+Python ≥ 3.10 required.
+
+## Quick start
+
+```python
+from forest_clustering import ForestClusterer
+from sklearn.cluster import KMeans
+
+fc = ForestClusterer(
+    n_iterations=200,
+    n_bins=3,
+    quantile_cuts=True,       # robust to outliers
+    corr_threshold=0.9,       # down-weight correlated features
+    clusterer=KMeans(n_clusters=5, n_init="auto", random_state=0),
+    random_state=42,
+)
+
+labels = fc.fit_predict(df)   # works with DataFrame or ndarray
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `n_iterations` | 200 | Number of random partitioning iterations *L*. More → more stable. |
+| `n_bins` | 3 | Number of bins per feature per iteration *K*. |
+| `n_features` | `"sqrt"` | Features selected per iteration: int, float fraction, `"sqrt"`, `"log2"`. |
+| `quantile_cuts` | `False` | Sample cut-points from empirical quantiles (robust to outliers). |
+| `corr_threshold` | 0.7 | Spearman \|r\| threshold for grouping correlated features. `None` disables. |
+| `corr_sample_size` | 10 000 | Rows used to estimate feature correlations. |
+| `clusterer` | `DBSCAN(metric="hamming")` | Any sklearn-compatible `fit_predict` estimator. |
+| `feature_types` | `None` | Override type detection: `{col: "numerical"\|"categorical"}`. |
+| `cat_threshold` | 10 | Numerical columns with ≤ this many unique values → treated as categorical. |
+| `n_jobs` | −1 | Parallelism for embedding computation (joblib). |
+| `random_state` | `None` | Seed for reproducibility. |
+
+## Downstream clustering algorithms
+
+| Algorithm | When to use |
+|---|---|
+| `KMeans(n_clusters=K)` on embedding | Known K, any n — fast and stable |
+| `AgglomerativeClustering(metric="precomputed")` | n ≤ 50 K, non-spherical clusters |
+| `DBSCAN(metric="hamming")` on embedding | Unknown K, need outlier detection |
+| `HDBSCAN(metric="precomputed")` | Variable-density clusters (pass `.astype(float64)`) |
+| `MiniBatchKMeans` on embedding | n > 100 K |
+
+```python
+from sklearn.cluster import AgglomerativeClustering
+
+fc = ForestClusterer(
+    n_iterations=300,
+    clusterer=AgglomerativeClustering(n_clusters=3, metric="precomputed", linkage="average"),
+)
+labels = fc.fit_predict(X)
+```
+
+## Utilities
+
+```python
+# Get the raw n×L embedding
+E = fc.get_embedding()
+
+# Pairwise Hamming distance matrix (chunked for large n)
+D = fc.pairwise_distance()
+
+# Transform new data using fitted partition specs
+E_new = fc.transform(X_new)
+```
+
+## Hyperparameter guidelines
+
+| Goal | Recommendation |
+|---|---|
+| Fast prototype | `n_iterations=50`, `n_bins=3` |
+| Balanced quality/speed | `n_iterations=200`, `n_bins=3` (default) |
+| High stability | `n_iterations=500`, `n_bins=4` |
+| Outlier-heavy data | `quantile_cuts=True` |
+| Many correlated features | `corr_threshold=0.8–0.9` |
+
+## License
+
+MIT

forest_clustering-0.1.0/forest_clustering/__init__.py

@@ -0,0 +1,12 @@
+from .clusterer import ForestClusterer
+from .distance import pairwise_hamming, pairwise_hamming_chunked, cross_hamming
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ForestClusterer",
+    "pairwise_hamming",
+    "pairwise_hamming_chunked",
+    "cross_hamming",
+    "__version__",
+]

forest_clustering-0.1.0/forest_clustering/clusterer.py

@@ -0,0 +1,191 @@
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator, ClusterMixin
+from sklearn.cluster import DBSCAN
+from sklearn.utils.validation import check_is_fitted
+
+from .feature_encoder import DataEncoder
+from .correlation import compute_feature_weights
+from .partitioner import build_col_stats, build_iteration_specs, compute_embedding
+from .distance import pairwise_hamming, pairwise_hamming_chunked, cross_hamming
+
+
+def _resolve_n_features(n_features, d: int) -> int:
+    if n_features == "sqrt":
+        return max(1, int(np.ceil(np.sqrt(d))))
+    if n_features == "log2":
+        return max(1, int(np.ceil(np.log2(max(d, 2)))))
+    if isinstance(n_features, float) and 0 < n_features <= 1.0:
+        return max(1, int(np.ceil(n_features * d)))
+    return max(1, int(n_features))
+
+
+class ForestClusterer(BaseEstimator, ClusterMixin):
+    """Clustering via random-partition similarity embeddings.
+
+    Parameters
+    ----------
+    n_iterations : int
+        Number of random partitioning iterations (L). More → more stable embeddings.
+    n_features : int | float | "sqrt" | "log2"
+        Features selected per iteration. Float = fraction, "sqrt" = ceil(sqrt(d)).
+    n_bins : int
+        Number of bins per feature per iteration (K).
+    clusterer : sklearn-compatible estimator or None
+        Downstream clustering algorithm. Must support fit_predict().
+        If metric="precomputed", receives the pairwise distance matrix.
+        If metric="hamming" or not set, receives the (n, L) embedding directly.
+        Default: DBSCAN(metric="hamming").
+    corr_threshold : float or None
+        Spearman |corr| threshold for grouping correlated features (1/G weighting).
+        None disables correlation-based weighting.
+    corr_sample_size : int
+        Number of rows to sample when computing feature correlations.
+    feature_types : dict or None
+        Override detected feature types: {col_name_or_idx: "numerical"|"categorical"}.
+    cat_threshold : int
+        Numerical columns with ≤ this many unique values are treated as categorical.
+    quantile_cuts : bool
+        If True, cut-points for numerical features are sampled from empirical quantiles
+        instead of uniform [min, max].
+    n_jobs : int
+        Parallelism for embedding computation (passed to joblib).
+    random_state : int or None
+        Seed for reproducibility.
+    """
+
+    def __init__(
+        self,
+        n_iterations: int = 200,
+        n_features="sqrt",
+        n_bins: int = 3,
+        clusterer=None,
+        corr_threshold: float | None = 0.7,
+        corr_sample_size: int = 10_000,
+        feature_types: dict | None = None,
+        cat_threshold: int = 10,
+        quantile_cuts: bool = False,
+        n_jobs: int = -1,
+        random_state: int | None = None,
+    ):
+        self.n_iterations = n_iterations
+        self.n_features = n_features
+        self.n_bins = n_bins
+        self.clusterer = clusterer
+        self.corr_threshold = corr_threshold
+        self.corr_sample_size = corr_sample_size
+        self.feature_types = feature_types
+        self.cat_threshold = cat_threshold
+        self.quantile_cuts = quantile_cuts
+        self.n_jobs = n_jobs
+        self.random_state = random_state
+
+    # ------------------------------------------------------------------
+    # Core sklearn interface
+    # ------------------------------------------------------------------
+
+    def fit(self, X, y=None):
+        rng = np.random.default_rng(self.random_state)
+
+        self.encoder_ = DataEncoder(
+            feature_types_override=self.feature_types,
+            cat_threshold=self.cat_threshold,
+        )
+        X_enc = self.encoder_.fit_transform(X)
+        n, d = X_enc.shape
+
+        n_feat = _resolve_n_features(self.n_features, d)
+
+        # Feature weights from correlation
+        if self.corr_threshold is not None and d > 1:
+            self.feature_weights_ = compute_feature_weights(
+                X_enc,
+                threshold=self.corr_threshold,
+                sample_size=self.corr_sample_size,
+                rng=rng,
+            )
+        else:
+            self.feature_weights_ = np.ones(d)
+
+        # Column statistics for cut-point generation
+        self.col_stats_ = build_col_stats(
+            X_enc,
+            self.encoder_.feature_types_,
+            quantile_cuts=self.quantile_cuts,
+            rng=rng,
+        )
+
+        # Build all iteration specs
+        self.specs_ = build_iteration_specs(
+            n_iterations=self.n_iterations,
+            col_stats=self.col_stats_,
+            n_features_per_iter=n_feat,
+            n_bins=self.n_bins,
+            feature_weights=self.feature_weights_,
+            rng=rng,
+        )
+
+        # Compute training embedding
+        self.embedding_ = compute_embedding(X_enc, self.specs_, n_jobs=self.n_jobs)
+        return self
+
+    def fit_predict(self, X, y=None) -> np.ndarray:
+        self.fit(X)
+        return self._run_clusterer(self.embedding_)
+
+    # ------------------------------------------------------------------
+    # Transform / distance
+    # ------------------------------------------------------------------
+
+    def transform(self, X) -> np.ndarray:
+        """Apply fitted partition specs to new data. Returns (n, L) embedding."""
+        check_is_fitted(self, "specs_")
+        X_enc = self.encoder_.transform(X)
+        return compute_embedding(X_enc, self.specs_, n_jobs=self.n_jobs)
+
+    def get_embedding(self) -> np.ndarray:
+        check_is_fitted(self, "embedding_")
+        return self.embedding_
+
+    def pairwise_distance(
+        self,
+        X=None,
+        Y=None,
+        chunk_size: int = 2_000,
+    ) -> np.ndarray:
+        """Hamming distance matrix from embeddings.
+
+        X=None → use training embedding.
+        Y=None → square matrix D[i,j] = d(X[i], X[j]).
+        X,Y provided → rectangular matrix D[i,j] = d(X[i], Y[j]).
+        """
+        check_is_fitted(self, "embedding_")
+
+        E_X = self.embedding_ if X is None else self.transform(X)
+
+        if Y is not None:
+            E_Y = self.transform(Y)
+            return cross_hamming(E_X, E_Y)
+
+        n = E_X.shape[0]
+        if n <= chunk_size:
+            return pairwise_hamming(E_X)
+        return pairwise_hamming_chunked(E_X, chunk_size=chunk_size)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _run_clusterer(self, E: np.ndarray) -> np.ndarray:
+        clf = self.clusterer
+        if clf is None:
+            clf = DBSCAN(metric="hamming", n_jobs=self.n_jobs)
+
+        metric = getattr(clf, "metric", None)
+        if metric == "precomputed":
+            D = self.pairwise_distance().astype(np.float64)
+            return clf.fit_predict(D)
+
+        # Pass embedding directly; works for DBSCAN(metric='hamming'),
+        # HDBSCAN, KMeans, Agglomerative, etc.
+        return clf.fit_predict(E)

forest_clustering-0.1.0/forest_clustering/correlation.py

@@ -0,0 +1,63 @@
+import numpy as np
+from scipy import stats
+from scipy.sparse import csr_matrix
+from scipy.sparse.csgraph import connected_components
+
+
+def compute_feature_weights(
+    X: np.ndarray,
+    threshold: float = 0.7,
+    sample_size: int = 10_000,
+    rng: np.random.Generator | None = None,
+) -> np.ndarray:
+    """Return per-feature weight array of shape (d,).
+
+    Features belonging to a strongly-correlated group of size G get weight 1/G.
+    Correlation is estimated on a random sample via Spearman rank correlation.
+    """
+    if rng is None:
+        rng = np.random.default_rng()
+
+    n, d = X.shape
+    if d < 2:
+        return np.ones(d)
+
+    # Sample rows
+    idx = rng.choice(n, size=min(sample_size, n), replace=False)
+    X_s = X[idx].astype(np.float64)
+
+    # Drop columns that are constant in the sample (Spearman undefined)
+    stds = X_s.std(axis=0)
+    variable_mask = stds > 0
+    if variable_mask.sum() < 2:
+        return np.ones(d)
+
+    X_var = X_s[:, variable_mask]
+    var_indices = np.where(variable_mask)[0]
+
+    # Spearman correlation matrix on variable columns
+    result = stats.spearmanr(X_var, nan_policy="omit")
+    if X_var.shape[1] == 2:
+        corr_val = float(result.statistic) if np.isscalar(result.statistic) else float(result.statistic[0, 1])
+        corr = np.array([[1.0, corr_val], [corr_val, 1.0]])
+    else:
+        corr = np.array(result.statistic)
+
+    corr = np.abs(np.nan_to_num(corr))
+
+    # Adjacency: connected if |corr| > threshold (no self-loops)
+    adj = (corr > threshold).astype(np.uint8)
+    np.fill_diagonal(adj, 0)
+
+    # Connected components on variable features
+    _, labels = connected_components(csr_matrix(adj), directed=False)
+
+    weights = np.ones(d)
+    for comp_id in np.unique(labels):
+        members_local = np.where(labels == comp_id)[0]
+        if len(members_local) < 2:
+            continue
+        members_global = var_indices[members_local]
+        weights[members_global] = 1.0 / len(members_local)
+
+    return weights

forest_clustering-0.1.0/forest_clustering/distance.py

@@ -0,0 +1,26 @@
+import numpy as np
+from scipy.spatial.distance import cdist
+
+
+def pairwise_hamming(E: np.ndarray) -> np.ndarray:
+    """Full pairwise Hamming distance matrix from embedding.
+
+    E: (n, L) int64 — embedding returned by compute_embedding
+    Returns: (n, n) float32
+    """
+    return cdist(E, E, metric="hamming").astype(np.float32)
+
+
+def pairwise_hamming_chunked(E: np.ndarray, chunk_size: int = 2_000) -> np.ndarray:
+    """Memory-efficient version for larger n (builds full matrix row-by-row)."""
+    n = E.shape[0]
+    D = np.empty((n, n), dtype=np.float32)
+    for start in range(0, n, chunk_size):
+        end = min(start + chunk_size, n)
+        D[start:end] = cdist(E[start:end], E, metric="hamming").astype(np.float32)
+    return D
+
+
+def cross_hamming(E_X: np.ndarray, E_Y: np.ndarray) -> np.ndarray:
+    """Pairwise Hamming between two embedding matrices. Returns (n_X, n_Y) float32."""
+    return cdist(E_X, E_Y, metric="hamming").astype(np.float32)