sil-score 0.1.4__tar.gz

sil_score-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aggelos Semoglou
+
+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.

sil_score-0.1.4/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: sil-score
+Version: 0.1.4
+Summary: Exact and approximate silhouette scoring with micro, macro, and weighted cluster averages.
+Home-page: https://github.com/semoglou/sil_score
+Author: Aggelos Semoglou
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scikit-learn>=1.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# sil_score
+
+[![PyPI](https://img.shields.io/pypi/v/sil-score.svg)](https://pypi.org/project/sil-score/)
+[![Python](https://img.shields.io/pypi/pyversions/sil-score.svg)](https://pypi.org/project/sil-score/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`sil-score` is a small Python package for exact and fast approximate silhouette scoring.
+
+It extends the usual silhouette workflow with:
+
+- per-sample silhouette scores
+- micro-averaged silhouette score
+- macro-averaged silhouette score
+- cluster-weighted macro silhouette score
+- exact vs approximate comparison report
+
+The exact mode uses scikit-learn's `silhouette_samples`.  
+The approximate mode uses Euclidean distances to cluster centroids, making it faster but not identical to the classical silhouette definition.
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install sil-score
+```
+
+## Quick example
+
+```python
+import numpy as np
+from sil_score import (
+    sil_samples,
+    micro_sil_score,
+    macro_sil_score,
+    weighted_macro_sil_score,
+    sil_approximation_report,
+)
+
+X = np.array([
+    [0.0],
+    [2.0],
+    [10.0],
+    [12.0],
+])
+
+labels = np.array([0, 0, 1, 1])
+
+samples = sil_samples(X, labels)
+micro = micro_sil_score(X, labels)
+macro = macro_sil_score(X, labels)
+
+print(samples)
+print(micro)
+print(macro)
+```
+
+Output:
+
+    [0.81818182 0.77777778 0.77777778 0.81818182]
+    0.797979797979798
+    0.797979797979798
+
+## Functions
+
+### `sil_samples` 
+
+```python
+sil_samples(X, labels, approximation=False, centers=None)
+```
+
+Computes the silhouette score for each sample.
+
+By default, it computes the exact silhouette values using scikit-learn.
+
+```python
+scores = sil_samples(X, labels)
+```
+
+For a faster centroid-based approximation:
+
+```python
+scores = sil_samples(X, labels, approximation=True)
+```
+
+You can also pass precomputed cluster centers:
+
+```python
+scores = sil_samples(
+    X,
+    labels,
+    approximation=True,
+    centers=centers,
+)
+```
+
+---
+
+### `micro_sil_score`
+
+```python
+micro_sil_score(X, labels, approximation=False, centers=None)
+```
+
+Computes the mean of all sample-level silhouette scores. This is the usual average silhouette score. Larger clusters naturally have more influence because they contain more samples.
+
+```python
+# Standard usage
+score = micro_sil_score(X, labels)
+
+# Approximate version
+score = micro_sil_score(X, labels, approximation=True)
+```
+
+---
+
+### `macro_sil_score`
+
+```python
+macro_sil_score(X, labels, approximation=False, centers=None)
+```
+
+Computes the mean silhouette score inside each cluster, then averages the cluster means equally. This gives every cluster the same importance, regardless of its size.
+
+```python
+# Standard usage
+score = macro_sil_score(X, labels)
+
+# Approximate version
+score = macro_sil_score(X, labels, approximation=True)
+```
+
+---
+
+### `weighted_macro_sil_score`
+
+```python
+weighted_macro_sil_score(X, labels, cluster_weights, approximation=False, centers=None)
+```
+
+Computes a cluster-weighted macro silhouette score. First, it computes the mean silhouette score for each cluster, then combines those cluster means using custom cluster weights.
+
+Using a dictionary:
+```python
+weights = {
+    0: 0.2,
+    1: 0.3,
+    2: 0.5,
+}
+
+score = weighted_macro_sil_score(X, labels, cluster_weights=weights)
+```
+
+Using an array:
+
+```python
+weights = [0.2, 0.3, 0.5]
+
+score = weighted_macro_sil_score(X, labels, cluster_weights=weights)
+```
+
+--- 
+
+### `sil_approximation_report`
+
+```python
+sil_approximation_report(X, labels, centers=None, return_samples=False)
+```
+
+Compares exact silhouette scores with centroid-based approximate scores. It returns(Pearson) correlation and error metrics:
+
+```python
+report = sil_approximation_report(X, labels)
+print(report)
+```
+
+Example output:
+
+```
+{
+    "correlation": 0.96,
+    "mean_absolute_error": 0.03,
+    "mean_squared_error": 0.002,
+    "root_mean_squared_error": 0.045,
+    "max_absolute_error": 0.12,
+    "mean_error": 0.01,
+    "mean_exact_score": 0.52,
+    "mean_approximate_score": 0.53,
+    "n_samples": 300,
+}
+```
+
+Use `return_samples=True` to also include the exact scores, approximate scores, and per-sample errors.
+
+---
+
+### Exact vs Approximate mode
+
+- **Exact mode**: `sil_samples(X, labels, approximation=False)`. Uses the classical silhouette definition based on distances between samples.
+- **Approximate mode**: `sil_samples(X, labels, approximation=True)`. Uses distances from each sample to cluster centroids. This can be significantly faster for larger datasets.
+
+## Requirements 
+`sil-score` depends on:
+- NumPy
+- scikit-learn
+
+## License 
+This project is licensed under the MIT License.

sil_score-0.1.4/README.md

@@ -0,0 +1,210 @@
+# sil_score
+
+[![PyPI](https://img.shields.io/pypi/v/sil-score.svg)](https://pypi.org/project/sil-score/)
+[![Python](https://img.shields.io/pypi/pyversions/sil-score.svg)](https://pypi.org/project/sil-score/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`sil-score` is a small Python package for exact and fast approximate silhouette scoring.
+
+It extends the usual silhouette workflow with:
+
+- per-sample silhouette scores
+- micro-averaged silhouette score
+- macro-averaged silhouette score
+- cluster-weighted macro silhouette score
+- exact vs approximate comparison report
+
+The exact mode uses scikit-learn's `silhouette_samples`.  
+The approximate mode uses Euclidean distances to cluster centroids, making it faster but not identical to the classical silhouette definition.
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install sil-score
+```
+
+## Quick example
+
+```python
+import numpy as np
+from sil_score import (
+    sil_samples,
+    micro_sil_score,
+    macro_sil_score,
+    weighted_macro_sil_score,
+    sil_approximation_report,
+)
+
+X = np.array([
+    [0.0],
+    [2.0],
+    [10.0],
+    [12.0],
+])
+
+labels = np.array([0, 0, 1, 1])
+
+samples = sil_samples(X, labels)
+micro = micro_sil_score(X, labels)
+macro = macro_sil_score(X, labels)
+
+print(samples)
+print(micro)
+print(macro)
+```
+
+Output:
+
+    [0.81818182 0.77777778 0.77777778 0.81818182]
+    0.797979797979798
+    0.797979797979798
+
+## Functions
+
+### `sil_samples` 
+
+```python
+sil_samples(X, labels, approximation=False, centers=None)
+```
+
+Computes the silhouette score for each sample.
+
+By default, it computes the exact silhouette values using scikit-learn.
+
+```python
+scores = sil_samples(X, labels)
+```
+
+For a faster centroid-based approximation:
+
+```python
+scores = sil_samples(X, labels, approximation=True)
+```
+
+You can also pass precomputed cluster centers:
+
+```python
+scores = sil_samples(
+    X,
+    labels,
+    approximation=True,
+    centers=centers,
+)
+```
+
+---
+
+### `micro_sil_score`
+
+```python
+micro_sil_score(X, labels, approximation=False, centers=None)
+```
+
+Computes the mean of all sample-level silhouette scores. This is the usual average silhouette score. Larger clusters naturally have more influence because they contain more samples.
+
+```python
+# Standard usage
+score = micro_sil_score(X, labels)
+
+# Approximate version
+score = micro_sil_score(X, labels, approximation=True)
+```
+
+---
+
+### `macro_sil_score`
+
+```python
+macro_sil_score(X, labels, approximation=False, centers=None)
+```
+
+Computes the mean silhouette score inside each cluster, then averages the cluster means equally. This gives every cluster the same importance, regardless of its size.
+
+```python
+# Standard usage
+score = macro_sil_score(X, labels)
+
+# Approximate version
+score = macro_sil_score(X, labels, approximation=True)
+```
+
+---
+
+### `weighted_macro_sil_score`
+
+```python
+weighted_macro_sil_score(X, labels, cluster_weights, approximation=False, centers=None)
+```
+
+Computes a cluster-weighted macro silhouette score. First, it computes the mean silhouette score for each cluster, then combines those cluster means using custom cluster weights.
+
+Using a dictionary:
+```python
+weights = {
+    0: 0.2,
+    1: 0.3,
+    2: 0.5,
+}
+
+score = weighted_macro_sil_score(X, labels, cluster_weights=weights)
+```
+
+Using an array:
+
+```python
+weights = [0.2, 0.3, 0.5]
+
+score = weighted_macro_sil_score(X, labels, cluster_weights=weights)
+```
+
+--- 
+
+### `sil_approximation_report`
+
+```python
+sil_approximation_report(X, labels, centers=None, return_samples=False)
+```
+
+Compares exact silhouette scores with centroid-based approximate scores. It returns(Pearson) correlation and error metrics:
+
+```python
+report = sil_approximation_report(X, labels)
+print(report)
+```
+
+Example output:
+
+```
+{
+    "correlation": 0.96,
+    "mean_absolute_error": 0.03,
+    "mean_squared_error": 0.002,
+    "root_mean_squared_error": 0.045,
+    "max_absolute_error": 0.12,
+    "mean_error": 0.01,
+    "mean_exact_score": 0.52,
+    "mean_approximate_score": 0.53,
+    "n_samples": 300,
+}
+```
+
+Use `return_samples=True` to also include the exact scores, approximate scores, and per-sample errors.
+
+---
+
+### Exact vs Approximate mode
+
+- **Exact mode**: `sil_samples(X, labels, approximation=False)`. Uses the classical silhouette definition based on distances between samples.
+- **Approximate mode**: `sil_samples(X, labels, approximation=True)`. Uses distances from each sample to cluster centroids. This can be significantly faster for larger datasets.
+
+## Requirements 
+`sil-score` depends on:
+- NumPy
+- scikit-learn
+
+## License 
+This project is licensed under the MIT License.

sil_score-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sil_score-0.1.4/setup.py

@@ -0,0 +1,31 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="sil-score",
+    version="0.1.4",
+    description="Exact and approximate silhouette scoring with micro, macro, and weighted cluster averages.",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="Aggelos Semoglou",
+    license="MIT",
+    url="https://github.com/semoglou/sil_score",
+    packages=find_packages(),
+    python_requires=">=3.8",
+    install_requires=[
+        "numpy>=1.21",
+        "scikit-learn>=1.0",
+    ],
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Science/Research",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+)

sil_score-0.1.4/sil_score/__init__.py

@@ -0,0 +1,15 @@
+from .sil_score import (
+    sil_samples,
+    micro_sil_score,
+    macro_sil_score,
+    weighted_macro_sil_score,
+    sil_approximation_report,
+)
+
+__all__ = [
+    "sil_samples",
+    "micro_sil_score",
+    "macro_sil_score",
+    "weighted_macro_sil_score",
+    "sil_approximation_report",
+]

sil_score-0.1.4/sil_score/sil_score.py

@@ -0,0 +1,253 @@
+"""
+sil_score.metrics
+
+Utilities for exact and approximate silhouette scoring.
+
+The exact mode delegates to scikit-learn's silhouette_samples.
+The approximate mode uses Euclidean distances to cluster centroids, so it is
+faster but not identical to the classical silhouette definition.
+"""
+import numpy as np
+from sklearn.metrics import silhouette_samples
+from sklearn.metrics.pairwise import euclidean_distances
+
+
+def sil_samples(X, labels, approximation: bool = False, centers=None) -> np.ndarray:
+    """
+    Compute silhouette scores for each point in the dataset,
+    with approximate fast centroid-based computation option.
+    """
+    # Ensure arrays
+    X = np.asarray(X)
+    labels = np.asarray(labels)
+    if X.ndim != 2:
+        raise ValueError("X must be a 2D array of shape (n_samples, n_features).")
+    if labels.ndim != 1 or labels.shape[0] != X.shape[0]:
+        raise ValueError("labels must be a 1D array of length n_samples.")
+
+    unique_labels, inv = np.unique(labels, return_inverse=True)
+    k = unique_labels.size
+    if k < 2:
+        raise ValueError("Silhouette computation requires at least 2 clusters.")
+
+    # Exact silhouette scores
+    if approximation == False:
+        silhouette_scores = silhouette_samples(X, labels=labels)
+        return silhouette_scores
+
+    # Centroid-based approximate silhouette scores
+    n_samples, n_features = X.shape
+
+    if centers is None:
+        centers = np.array([X[inv == i].mean(axis=0) for i in range(k)], dtype=float)
+    else:
+        centers = np.asarray(centers, dtype=float)
+        if centers.ndim != 2 or centers.shape[1] != n_features:
+            raise ValueError(f"centers must have shape (k, d) with d={n_features}.")
+        if centers.shape[0] != k:
+            raise ValueError(f"centers.shape[0] must equal number of clusters k={k}.")
+        if not np.array_equal(unique_labels, np.arange(k)):
+            raise ValueError("When passing ndarray centers, labels must be dense 0..k-1.")
+
+    # Squared distances to all centroids
+    D_sq = euclidean_distances(X, centers, squared=True)
+
+    # a(i): distance to own centroid
+    a = np.sqrt(np.maximum(D_sq[np.arange(n_samples), inv], 0.0))
+
+    # b(i): distance to nearest other centroid
+    D_sq[np.arange(n_samples), inv] = np.inf
+    b = np.sqrt(np.min(D_sq, axis=1))
+
+    # Silhouette per point
+    denom = np.maximum(np.maximum(a, b), 1e-12)
+    s_point = (b - a) / denom
+
+    # Singleton clusters -> silhouette = 0
+    counts = np.bincount(inv, minlength=k).astype(int)
+    s_point[counts[inv] < 2] = 0.0
+
+    silhouette_scores = np.clip(s_point, -1.0, 1.0)
+
+    return silhouette_scores
+
+def micro_sil_score(X, labels, approximation: bool = False, centers=None) -> float:
+    """
+    Compute the micro-averaged silhouette score.
+
+    This is the mean of all sample-level silhouette scores.
+    Larger clusters have more influence because they contain more samples.
+    """
+    silhouette_scores = sil_samples(
+        X,
+        labels,
+        approximation=approximation,
+        centers=centers,
+    )
+    return float(np.mean(silhouette_scores))
+
+
+def macro_sil_score(X, labels, approximation: bool = False, centers=None) -> float:
+    """
+    Compute the macro-averaged silhouette score.
+
+    This first computes the mean silhouette score inside each cluster,
+    then averages those cluster means equally.
+    Each cluster contributes the same weight regardless of size.
+    """
+    labels = np.asarray(labels)
+    silhouette_scores = sil_samples(
+        X,
+        labels,
+        approximation=approximation,
+        centers=centers,
+    )
+
+    unique_labels = np.unique(labels)
+    cluster_scores = [
+        np.mean(silhouette_scores[labels == label])
+        for label in unique_labels
+    ]
+
+    return float(np.mean(cluster_scores))
+
+def sil_approximation_report(X, labels, centers=None, return_samples=False):
+    """
+    Compare exact silhouette scores with centroid-based approximate scores.
+
+    Parameters
+    ----------
+    X : array-like of shape (n_samples, n_features)
+        Input data.
+
+    labels : array-like of shape (n_samples,)
+        Cluster labels for each sample.
+
+    centers : array-like of shape (n_clusters, n_features), optional
+        Cluster centers used for the approximate silhouette computation.
+        If None, centers are computed from X and labels.
+
+    return_samples : bool, default=False
+        If True, include exact scores, approximate scores, and errors
+        in the returned dictionary.
+
+    Returns
+    -------
+    report : dict
+        Dictionary with correlation and error metrics.
+    """
+    exact_scores = sil_samples(X, labels, approximation=False)
+    approximate_scores = sil_samples(
+        X,
+        labels,
+        approximation=True,
+        centers=centers,
+    )
+
+    errors = approximate_scores - exact_scores
+    absolute_errors = np.abs(errors)
+    squared_errors = errors ** 2
+
+    if np.std(exact_scores) == 0 or np.std(approximate_scores) == 0:
+        correlation = np.nan
+    else:
+        correlation = float(np.corrcoef(exact_scores, approximate_scores)[0, 1])
+
+    report = {
+        "correlation": correlation,
+        "mean_absolute_error": float(np.mean(absolute_errors)),
+        "mean_squared_error": float(np.mean(squared_errors)),
+        "root_mean_squared_error": float(np.sqrt(np.mean(squared_errors))),
+        "max_absolute_error": float(np.max(absolute_errors)),
+        "mean_error": float(np.mean(errors)),
+        "mean_exact_score": float(np.mean(exact_scores)),
+        "mean_approximate_score": float(np.mean(approximate_scores)),
+        "n_samples": int(len(exact_scores)),
+    }
+
+    if return_samples:
+        report["exact_scores"] = exact_scores
+        report["approximate_scores"] = approximate_scores
+        report["errors"] = errors
+        report["absolute_errors"] = absolute_errors
+
+    return report
+  
+def weighted_macro_sil_score(X, labels, cluster_weights, approximation: bool = False, centers=None) -> float:
+    """
+    Compute a cluster-weighted macro silhouette score.
+
+    First computes the mean silhouette score inside each cluster.
+    Then averages those cluster means using user-provided cluster weights.
+
+    Parameters
+    ----------
+    X : array-like of shape (n_samples, n_features)
+        Input data.
+
+    labels : array-like of shape (n_samples,)
+        Cluster labels.
+
+    cluster_weights : dict or array-like
+        Weights for each cluster.
+
+        If dict:
+            keys must be cluster labels, values must be weights.
+            Example: {0: 0.2, 1: 0.3, 2: 0.5}
+
+        If array-like:
+            labels must be dense integers 0, 1, ..., k-1.
+            Example: [0.2, 0.3, 0.5]
+
+    approximation : bool, default=False
+        If False, use exact silhouette scores.
+        If True, use centroid-based approximate silhouette scores.
+
+    centers : array-like of shape (n_clusters, n_features), optional
+        Cluster centers for approximate mode.
+
+    Returns
+    -------
+    score : float
+        Cluster-weighted macro silhouette score.
+    """
+    labels = np.asarray(labels)
+
+    silhouette_scores = sil_samples(
+        X,
+        labels,
+        approximation=approximation,
+        centers=centers,
+    )
+
+    unique_labels = np.unique(labels)
+
+    cluster_scores = np.array([
+        np.mean(silhouette_scores[labels == label])
+        for label in unique_labels
+    ])
+
+    if isinstance(cluster_weights, dict):
+        weights = np.array([
+            cluster_weights[label]
+            for label in unique_labels
+        ], dtype=float)
+    else:
+        weights = np.asarray(cluster_weights, dtype=float)
+
+        if weights.ndim != 1 or weights.shape[0] != unique_labels.size:
+            raise ValueError("cluster_weights must have one weight per cluster.")
+
+        if not np.array_equal(unique_labels, np.arange(unique_labels.size)):
+            raise ValueError(
+                "When cluster_weights is array-like, labels must be dense integers 0..k-1. "
+                "Use a dict for non-dense labels."
+            )
+
+    if np.any(weights < 0):
+        raise ValueError("cluster_weights must be non-negative.")
+
+    if np.sum(weights) == 0:
+        raise ValueError("cluster_weights must sum to a positive value.")
+
+    return float(np.average(cluster_scores, weights=weights))

sil_score-0.1.4/sil_score.egg-info/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: sil-score
+Version: 0.1.4
+Summary: Exact and approximate silhouette scoring with micro, macro, and weighted cluster averages.
+Home-page: https://github.com/semoglou/sil_score
+Author: Aggelos Semoglou
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scikit-learn>=1.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# sil_score
+
+[![PyPI](https://img.shields.io/pypi/v/sil-score.svg)](https://pypi.org/project/sil-score/)
+[![Python](https://img.shields.io/pypi/pyversions/sil-score.svg)](https://pypi.org/project/sil-score/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`sil-score` is a small Python package for exact and fast approximate silhouette scoring.
+
+It extends the usual silhouette workflow with:
+
+- per-sample silhouette scores
+- micro-averaged silhouette score
+- macro-averaged silhouette score
+- cluster-weighted macro silhouette score
+- exact vs approximate comparison report
+
+The exact mode uses scikit-learn's `silhouette_samples`.  
+The approximate mode uses Euclidean distances to cluster centroids, making it faster but not identical to the classical silhouette definition.
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install sil-score
+```
+
+## Quick example
+
+```python
+import numpy as np
+from sil_score import (
+    sil_samples,
+    micro_sil_score,
+    macro_sil_score,
+    weighted_macro_sil_score,
+    sil_approximation_report,
+)
+
+X = np.array([
+    [0.0],
+    [2.0],
+    [10.0],
+    [12.0],
+])
+
+labels = np.array([0, 0, 1, 1])
+
+samples = sil_samples(X, labels)
+micro = micro_sil_score(X, labels)
+macro = macro_sil_score(X, labels)
+
+print(samples)
+print(micro)
+print(macro)
+```
+
+Output:
+
+    [0.81818182 0.77777778 0.77777778 0.81818182]
+    0.797979797979798
+    0.797979797979798
+
+## Functions
+
+### `sil_samples` 
+
+```python
+sil_samples(X, labels, approximation=False, centers=None)
+```
+
+Computes the silhouette score for each sample.
+
+By default, it computes the exact silhouette values using scikit-learn.
+
+```python
+scores = sil_samples(X, labels)
+```
+
+For a faster centroid-based approximation:
+
+```python
+scores = sil_samples(X, labels, approximation=True)
+```
+
+You can also pass precomputed cluster centers:
+
+```python
+scores = sil_samples(
+    X,
+    labels,
+    approximation=True,
+    centers=centers,
+)
+```
+
+---
+
+### `micro_sil_score`
+
+```python
+micro_sil_score(X, labels, approximation=False, centers=None)
+```
+
+Computes the mean of all sample-level silhouette scores. This is the usual average silhouette score. Larger clusters naturally have more influence because they contain more samples.
+
+```python
+# Standard usage
+score = micro_sil_score(X, labels)
+
+# Approximate version
+score = micro_sil_score(X, labels, approximation=True)
+```
+
+---
+
+### `macro_sil_score`
+
+```python
+macro_sil_score(X, labels, approximation=False, centers=None)
+```
+
+Computes the mean silhouette score inside each cluster, then averages the cluster means equally. This gives every cluster the same importance, regardless of its size.
+
+```python
+# Standard usage
+score = macro_sil_score(X, labels)
+
+# Approximate version
+score = macro_sil_score(X, labels, approximation=True)
+```
+
+---
+
+### `weighted_macro_sil_score`
+
+```python
+weighted_macro_sil_score(X, labels, cluster_weights, approximation=False, centers=None)
+```
+
+Computes a cluster-weighted macro silhouette score. First, it computes the mean silhouette score for each cluster, then combines those cluster means using custom cluster weights.
+
+Using a dictionary:
+```python
+weights = {
+    0: 0.2,
+    1: 0.3,
+    2: 0.5,
+}
+
+score = weighted_macro_sil_score(X, labels, cluster_weights=weights)
+```
+
+Using an array:
+
+```python
+weights = [0.2, 0.3, 0.5]
+
+score = weighted_macro_sil_score(X, labels, cluster_weights=weights)
+```
+
+--- 
+
+### `sil_approximation_report`
+
+```python
+sil_approximation_report(X, labels, centers=None, return_samples=False)
+```
+
+Compares exact silhouette scores with centroid-based approximate scores. It returns(Pearson) correlation and error metrics:
+
+```python
+report = sil_approximation_report(X, labels)
+print(report)
+```
+
+Example output:
+
+```
+{
+    "correlation": 0.96,
+    "mean_absolute_error": 0.03,
+    "mean_squared_error": 0.002,
+    "root_mean_squared_error": 0.045,
+    "max_absolute_error": 0.12,
+    "mean_error": 0.01,
+    "mean_exact_score": 0.52,
+    "mean_approximate_score": 0.53,
+    "n_samples": 300,
+}
+```
+
+Use `return_samples=True` to also include the exact scores, approximate scores, and per-sample errors.
+
+---
+
+### Exact vs Approximate mode
+
+- **Exact mode**: `sil_samples(X, labels, approximation=False)`. Uses the classical silhouette definition based on distances between samples.
+- **Approximate mode**: `sil_samples(X, labels, approximation=True)`. Uses distances from each sample to cluster centroids. This can be significantly faster for larger datasets.
+
+## Requirements 
+`sil-score` depends on:
+- NumPy
+- scikit-learn
+
+## License 
+This project is licensed under the MIT License.

sil_score-0.1.4/sil_score.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+setup.py
+sil_score/__init__.py
+sil_score/sil_score.py
+sil_score.egg-info/PKG-INFO
+sil_score.egg-info/SOURCES.txt
+sil_score.egg-info/dependency_links.txt
+sil_score.egg-info/requires.txt
+sil_score.egg-info/top_level.txt

sil_score-0.1.4/sil_score.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sil_score-0.1.4/sil_score.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy>=1.21
+scikit-learn>=1.0

sil_score-0.1.4/sil_score.egg-info/top_level.txt

@@ -0,0 +1 @@
+sil_score