compsil 0.1.0__py3-none-any.whl

compsil/__init__.py

@@ -0,0 +1 @@
+from .compsil import CompSil

compsil/compsil.py

@@ -0,0 +1,377 @@
+import numpy as np
+import pandas as pd
+from sklearn.cluster import KMeans
+from sklearn.metrics import silhouette_score, silhouette_samples
+from sklearn.utils import resample
+import matplotlib.pyplot as plt
+from joblib import Parallel, delayed
+
+
+class CompSil:
+    """
+    Composite Silhouette (CompSil)
+
+    Per subsample b=1..B for each k:
+      - compute S_micro^(b), S_macro^(b)
+      - Δ_b = S_micro^(b) - S_macro^(b)
+      - D = max_b |Δ_b|
+      - r_raw_b = Δ_b/(D+eps) in [-1,1]
+      - r_b = tanh(r_raw_b)
+      - w_b = (1+r_b)/2
+      - S_mM^(b) = w_b*S_micro^(b) + (1-w_b)*S_macro^(b)
+
+    Aggregate for each k:
+      - mean score:   S_mM(k)  = mean_b S_mM^(b)
+      - std score:    std_S_mM(k) = std_b  S_mM^(b)
+      - standard error: se_S_mM(k) = std_S_mM(k) / sqrt(B_eff)
+      - lower conf bound: LCB_S_mM(k) = S_mM(k) - se_S_mM(k)
+
+    Selection:
+      - k* = argmax_k S_mM(k) (or argmax_k LCB_S_mM(k))
+
+    Sampling size mechanism:
+      - explicit `sample_size` (int), or
+      - sample_size=None or sample_size="auto", the class chooses a subsample size automatically
+        based on dataset size N and the maximum k in `k_values`.
+
+    Parameters:
+    - data: ndarray or DataFrame, shape (n_samples, n_features)
+    - ground_truth: int, optional
+    - k_values: iterable or int, default=range(2, 11)
+    - num_samples: int, default=100  (B)
+    - sample_size: int | float | None | "auto", default=1000
+        * int: absolute subsample size m
+        * float in (0,1]: treated as fraction f, m = floor(f*N)
+        * None or "auto": compute m automatically (see _auto_sample_size)
+    - random_state: int, default=42
+    - n_jobs: int, default=-1
+    - eps: float, default=1e-12
+    """
+
+    def __init__(self,
+                 data,
+                 ground_truth=None,
+                 k_values=range(2, 11),
+                 num_samples=10,
+                 sample_size="auto",
+                 random_state=42,
+                 n_jobs=-1,
+                 eps=1e-12):
+        self.data = data
+        self.ground_truth = ground_truth
+        self.k_values = [k_values] if isinstance(k_values, int) else list(k_values)
+        self.num_samples = int(num_samples)
+        self.random_state = int(random_state)
+        self.n_jobs = int(n_jobs)
+        self.eps = float(eps)
+
+        self._results = []
+        self.results_df = pd.DataFrame()
+        self.score_ = None  # set only if one k is evaluated
+
+        self.n_samples_ = int(len(self.data))
+        if self.n_samples_ <= 0:
+            raise ValueError("Empty dataset.")
+
+        self.sample_size = self._resolve_sample_size(sample_size)
+        self.sample_fraction_ = self.sample_size / self.n_samples_
+
+        if self.sample_size < 2:
+            raise ValueError(f"Resolved sample_size={self.sample_size} is too small.")
+        if self.sample_size > self.n_samples_:
+            raise ValueError(
+                f"Resolved sample_size={self.sample_size} is larger than n_samples={self.n_samples_}."
+            )
+
+    def _resolve_sample_size(self, sample_size):
+        n = self.n_samples_
+
+        # Auto
+        if sample_size is None or (isinstance(sample_size, str) and sample_size.lower() == "auto"):
+            return self._auto_sample_size()
+
+        # Fraction mode (float in (0,1])
+        if isinstance(sample_size, float):
+            if not (0.0 < sample_size <= 1.0):
+                raise ValueError("If sample_size is a float, it must be in (0, 1].")
+            m = int(np.floor(sample_size * n))
+            return max(2, min(m, n))
+
+        # Int mode
+        m = int(sample_size)
+        return m
+
+    def _auto_sample_size(self):
+        """
+        Automatic subsample size selection (no user-facing hyperparameters).
+
+        Heuristic:
+          1) Ensure a minimum average points-per-cluster at k_max: m >= 30 * k_max
+          2) Use a baseline fraction depending on dataset size:
+             - small N: 0.8N
+             - medium N: 0.6N
+             - large N: 0.4N
+          3) Take the maximum of (1) and (2), then cap at N.
+        """
+        n = self.n_samples_
+        k_max = int(max(self.k_values)) if len(self.k_values) > 0 else 2
+
+        m_min = 30 * k_max
+
+        if n <= 2000:
+            m_base = int(np.floor(0.80 * n))
+        elif n <= 20000:
+            m_base = int(np.floor(0.60 * n))
+        else:
+            m_base = int(np.floor(0.40 * n))
+
+        m = max(m_min, m_base)
+        m = min(max(2, m), n)
+        return m
+
+    def evaluate_sample(self, k, i):
+        """
+        One subsampling iteration for fixed k.
+        Returns: (smicro, smacro, diff, s_mm_b)
+        """
+        seed = self.random_state + i
+
+        sampled_data = resample(
+            self.data,
+            n_samples=self.sample_size,
+            replace=False,
+            random_state=seed
+        )
+
+        kmeans = KMeans(n_clusters=k, random_state=seed, n_init=1)
+        labels = kmeans.fit_predict(sampled_data)
+
+        try:
+            s = silhouette_samples(sampled_data, labels)  # compute once
+
+            # micro silhouette
+            smicro = float(np.mean(s))
+
+            labs = np.asarray(labels)
+            uniq = np.unique(labs)
+            cluster_means = [float(np.mean(s[labs == u])) for u in uniq]
+
+            # macro silhouette
+            smacro = float(np.mean(cluster_means)) if len(cluster_means) > 0 else np.nan
+        except Exception:
+            return np.nan, np.nan, np.nan, np.nan
+
+        diff = smicro - smacro
+        return smicro, smacro, diff, np.nan
+
+    @staticmethod
+    def _tanh_rb_weights_from_differences(differences, eps=1e-12):
+        """
+        Given Δ_b over b=1..B, compute:
+          D       = max |Δ_b|
+          r_raw_b = Δ_b/(D+eps) in [-1, 1]
+          r_b     = tanh(r_raw_b)
+          w_b     = (1+r_b)/2 in (0,1)
+        """
+        d = np.asarray(differences, dtype=float)
+        finite = np.isfinite(d)
+
+        if not np.any(finite):
+            return d * np.nan, d * np.nan, np.nan
+
+        D = float(np.max(np.abs(d[finite])))
+        denom = D + float(eps)
+
+        if D == 0.0:
+            r = np.zeros_like(d)
+            r[~finite] = np.nan
+            w = 0.5 * np.ones_like(d)
+            w[~finite] = np.nan
+            return w, r, D
+
+        r_raw = d / denom
+        r_raw = np.clip(r_raw, -1.0, 1.0)
+        r_raw[~finite] = np.nan
+
+        r = np.tanh(r_raw)
+        r[~finite] = np.nan
+
+        w = 0.5 * (1.0 + r)
+        w[~finite] = np.nan
+
+        return w, r, D
+
+    def evaluate(self):
+        """
+        Evaluate over k_values using subsampled clustering.
+        Stores results in self.results_df.
+
+        Output columns (per k):
+        - avg S_micro
+        - avg S_macro
+        - w_micro (mean of per-subsample weights; descriptive)
+        - S_mM (mean of per-subsample composites)
+        - std S_mM
+        - se S_mM
+        - LCB S_mM  (S_mM - se)
+        """
+        self._results = []
+
+        for k in self.k_values:
+            results = Parallel(n_jobs=self.n_jobs)(
+                delayed(self.evaluate_sample)(k, i) for i in range(self.num_samples)
+            )
+
+            smicro_list, smacro_list, differences, _ = zip(*results)
+
+            smicro_arr = np.asarray(smicro_list, dtype=float)
+            smacro_arr = np.asarray(smacro_list, dtype=float)
+            diff_arr = np.asarray(differences, dtype=float)
+
+            avg_smicro = float(np.nanmean(smicro_arr)) if np.any(np.isfinite(smicro_arr)) else np.nan
+            avg_smacro = float(np.nanmean(smacro_arr)) if np.any(np.isfinite(smacro_arr)) else np.nan
+
+            # weights
+            w_b, r_b, D = self._tanh_rb_weights_from_differences(diff_arr, eps=self.eps)
+
+            # per-subsample composite
+            S_b = w_b * smicro_arr + (1.0 - w_b) * smacro_arr
+
+            # mean composite
+            S_mM = float(np.nanmean(S_b)) if np.any(np.isfinite(S_b)) else np.nan
+
+            # descriptive mean weight
+            w_micro_mean = float(np.nanmean(w_b)) if np.any(np.isfinite(w_b)) else np.nan
+
+            # LCB components computed from S_b across valid subsamples
+            finite_sb = np.isfinite(S_b)
+            B_eff = int(np.sum(finite_sb))
+            if B_eff >= 2:
+                std_smm = float(np.nanstd(S_b, ddof=1))
+                se_smm = std_smm / np.sqrt(B_eff)
+            elif B_eff == 1:
+                std_smm = 0.0
+                se_smm = 0.0
+            else:
+                std_smm = np.nan
+                se_smm = np.nan
+
+            lcb_smm = (S_mM - se_smm) if (np.isfinite(S_mM) and np.isfinite(se_smm)) else np.nan
+
+            if len(self.k_values) == 1:
+                self.score_ = S_mM
+
+            result = {
+                'k': int(k),
+                'avg S_micro': avg_smicro,
+                'avg S_macro': avg_smacro,
+                'w_micro': w_micro_mean,
+                'S_mM': S_mM,
+                'std S_mM': std_smm,
+                'se S_mM': se_smm,
+                'LCB S_mM': lcb_smm,
+                'B_eff': B_eff,
+                'sample_size': int(self.sample_size),
+                'sample_fraction': float(self.sample_fraction_),
+            }
+            self._results.append(result)
+
+        self.results_df = pd.DataFrame(self._results)
+
+    def plot_results(self):
+        """
+        Plot S_mM and individual averages vs k.
+        """
+        if self.results_df.empty:
+            raise ValueError("No results available. Run evaluate() first.")
+        if len(self.results_df) == 1:
+            raise ValueError("Cannot plot with only one k. Evaluate multiple k values.")
+
+        max_smicro = self.results_df['avg S_micro'].max()
+        max_smicro_k = self.results_df.loc[self.results_df['avg S_micro'].idxmax(), 'k']
+
+        max_smacro = self.results_df['avg S_macro'].max()
+        max_smacro_k = self.results_df.loc[self.results_df['avg S_macro'].idxmax(), 'k']
+
+        max_smm = self.results_df['S_mM'].max()
+        max_smm_k = self.results_df.loc[self.results_df['S_mM'].idxmax(), 'k']
+
+        plt.figure(figsize=(10, 4))
+
+        if self.ground_truth is not None:
+            plt.axvline(
+                x=self.ground_truth, color='red', linestyle='--', linewidth=2.5,
+                label='Ground Truth'
+            )
+
+        plt.plot(
+            self.results_df['k'], self.results_df['avg S_micro'],
+            marker='o', linestyle='-', color='orange', linewidth=4, markersize=8, label='avg S_micro'
+        )
+        plt.plot(max_smicro_k, max_smicro, marker='*', color='orange', markersize=18)
+
+        plt.plot(
+            self.results_df['k'], self.results_df['avg S_macro'],
+            marker='o', linestyle='-', color='blue', linewidth=4, markersize=8, label='avg S_macro'
+        )
+        plt.plot(max_smacro_k, max_smacro, marker='*', color='blue', markersize=18)
+
+        plt.plot(
+            self.results_df['k'], self.results_df['S_mM'],
+            marker='o', linestyle='--', color='green', linewidth=4, markersize=8, label='S_mM'
+        )
+        plt.plot(max_smm_k, max_smm, marker='*', color='green', markersize=18)
+
+        plt.xlabel('k', fontsize=15)
+        plt.xticks(self.k_values, fontsize=14)
+        plt.yticks(fontsize=14)
+        plt.tick_params(axis='y', which='both', length=0)
+        plt.grid(axis='y', linestyle='--')
+
+        ax = plt.gca()
+        ax.spines['right'].set_visible(False)
+        ax.spines['left'].set_visible(False)
+        ax.spines['top'].set_visible(False)
+
+        handles, labels = ax.get_legend_handles_labels()
+        ax.legend(
+            handles, labels,
+            loc="lower left",
+            bbox_to_anchor=(0, 1.02, 1, 0.2),
+            mode="expand",
+            ncol=len(labels),
+            frameon=False,
+            fontsize=12
+        )
+
+        plt.tight_layout()
+        plt.show()
+
+    def get_optimal_k(self, use_lcb=False):
+        """
+        Return optimal k.
+
+        By default, uses max selection:
+          k* = argmax_k (S_mM) (use_lcb for argmax_k (LCB S_mM) selection)
+
+        """
+        if self.results_df.empty:
+            raise ValueError("No results available. Run evaluate() first.")
+
+        if len(self.results_df) == 1:
+            return int(self.results_df['k'].iloc[0])
+
+        col = 'LCB S_mM' if use_lcb else 'S_mM'
+        if col not in self.results_df.columns:
+            raise ValueError(f"Missing column '{col}'. Run evaluate() first.")
+
+        optimal_row = self.results_df.loc[self.results_df[col].idxmax()]
+        return int(optimal_row['k'])
+
+    def get_results_dataframe(self):
+        """
+        Return results DataFrame indexed by k.
+        """
+        if self.results_df.empty:
+            raise ValueError("No results available. Run evaluate() first.")
+        return self.results_df.set_index('k', inplace=False)

compsil-0.1.0.dist-info/METADATA

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: compsil
+Version: 0.1.0
+Summary: CompSil: Composite Silhouette for Cluster-Count Selection
+Home-page: https://github.com/semoglou/compsil
+Author: Aggelos Semoglou
+Author-email: a.semoglou@outlook.gr
+License: MIT
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: joblib>=1.2
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# CompSil
+
+<p align="center">
+  <a href="https://pypi.org/project/compsil/"><img src="https://img.shields.io/pypi/v/compsil.svg?color=blue" alt="PyPI version"></a>&nbsp;&nbsp;
+  <a href="https://pypi.org/project/compsil/"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License: MIT"></a>&nbsp;&nbsp;
+  <a href="https://pepy.tech/project/compsil"><img src="https://pepy.tech/badge/compsil" alt="Downloads"></a>&nbsp;&nbsp;
+  <a href="#"><img src="https://img.shields.io/badge/ECML%20PKDD-2026-green" alt="ECML PKDD 2026"></a>
+</p>
+
+<table>
+<tr>
+<td>
+
+📄 **Accepted at _ECML PKDD 2026_**  
+
+**Composite Silhouette**  
+
+</td>
+</tr>
+</table>
+
+**CompSil** is an open-source Python package for selecting the number of clusters in unlabeled data using **Composite Silhouette**, an internal validation criterion that adaptively combines micro- and macro-averaged Silhouette scores across repeated subsampled clusterings.
+
+### Composite Silhouette: A Subsampling-based Aggregation Strategy
+
+Selecting the number of clusters is a central challenge in unsupervised learning, where ground-truth labels are usually unavailable.
+
+The standard Silhouette coefficient is one of the most widely used internal validation metrics for this task. However, its usual **micro-averaged** form aggregates Silhouette values over all data points, which can make the score strongly influenced by large clusters. In imbalanced datasets, this may mask poor separation or instability in smaller but meaningful groups.
+
+A natural alternative is **macro-averaging**, where Silhouette values are first averaged within each cluster and then averaged across clusters. This gives every cluster equal influence, reducing the dominance of majority groups. However, macro-averaging can also overemphasize small, noisy, or under-represented clusters.
+
+The distinction between micro- and macro-averaged Silhouette aggregation is discussed in detail in [**Revisiting Silhouette Aggregation**](https://arxiv.org/abs/2401.05831) by Pavlopoulos, Vardakas, and Likas. The corresponding repository is available here: [https://github.com/ipavlopoulos/revisiting-silhouette-aggregation](https://github.com/ipavlopoulos/revisiting-silhouette-aggregation).
+
+For users who only need direct Silhouette computation, including sample-level, micro-averaged, and macro-averaged Silhouette scores with or without approximation, see the companion Silhouette package: [https://github.com/semoglou/sil_score](https://github.com/semoglou/sil_score).
+
+<img src="https://raw.githubusercontent.com/semoglou/compsil/main/figs/aggr.png" alt="Micro vs Macro Silhouette Aggregation" width="700">
+
+These complementary failure modes create a practical dilemma:
+
+- **Micro-averaging** reflects global, point-wise clustering quality but can favor majority clusters.
+
+- **Macro-averaging** reflects cluster-wise balance but can overemphasize small or noisy groups.
+
+In many applications, it is unclear in advance which view should be trusted.
+
+**CompSil** addresses this issue by using the disagreement between micro- and macro-averaged Silhouette scores as a local signal for adaptive aggregation.
+
+Composite Silhouette evaluates candidate numbers of clusters through repeated subsampled clusterings. For each candidate value of `k`, the method:
+
+1. Draws multiple subsamples of the dataset.
+
+2. Clusters each subsample.
+
+3. Computes both micro- and macro-averaged Silhouette scores.
+
+4. Measures their discrepancy.
+
+5. Converts this discrepancy into a smooth convex weight.
+
+6. Combines the two Silhouette views into a subsample-level composite score.
+
+7. Averages the composite scores across subsamples.
+
+<img src="https://raw.githubusercontent.com/semoglou/compsil/main/figs/smmp.png" alt="Composite Silhouette pipeline" width="700">
+
+For each subsample, Composite Silhouette combines the two views as:
+
+```text
+
+S_mM = w * S_micro + (1 - w) * S_macro
+
+```
+
+where the weight `w` is determined adaptively from the normalized discrepancy between `S_micro` and `S_macro`.
+
+This produces a single internal validation score that can be maximized over candidate values of `k`.
+
+CompSil enables:
+
+- Selection of the number of clusters without labels.
+
+- Adaptive balancing of micro- and macro-averaged Silhouette.
+
+- More robust cluster-count selection under size imbalance.
+
+- Repeated subsampling for stable internal validation.
+
+- Optional lower-confidence-bound selection using subsampling variability.
+
+# 
+
+## Citation
+
+If you find this work useful, please consider citing:
+
+Semoglou, A., Likas, A., & Pavlopoulos, J. (2026). Composite Silhouette.  
+
+Accepted at *ECML PKDD 2026*.
+
+```bibtex
+@inproceedings{semoglou2026composite,
+  title     = {Composite Silhouette},
+  author    = {Semoglou, Aggelos and Likas, Aristidis and Pavlopoulos, John},
+  booktitle = {Proceedings of the European Conference on Machine Learning and Principles and Practice of Knowledge Discovery in Databases},
+  year      = {2026}
+}
+```
+
+The preprint is also available on arXiv: [https://arxiv.org/abs/2604.13816](https://arxiv.org/abs/2604.13816)
+
+## Installation
+
+Install **CompSil** from [PyPI](https://pypi.org/project/compsil/):
+
+```python
+pip install compsil
+```
+
+Import the main class in Python as:
+
+```python
+from compsil import CompSil
+```
+
+## API Reference
+
+CompSil provides a simple class-based interface for evaluating Composite Silhouette over one or more candidate numbers of clusters.
+
+---
+
+#### `CompSil`
+
+Computes Composite Silhouette for candidate cluster counts using repeated subsampled clusterings.
+
+```python
+CompSil(
+    data,
+    ground_truth=None,
+    k_values=range(2, 11),
+    num_samples=10,
+    sample_size="auto",
+    random_state=42,
+    n_jobs=-1,
+    eps=1e-12,
+)
+```
+
+**Inputs**
+
+- `data`: array-like of shape `(n_samples, n_features)`  
+  Input data matrix.
+
+- `ground_truth`: int or None, default `None`  
+  Optional reference number of clusters.  
+  Used only for visualization.
+
+- `k_values`: iterable of int or int, default `range(2, 11)`  
+  Candidate number or candidate numbers of clusters to evaluate.
+
+- `num_samples`: int, default `10`  
+  Number of subsamples used for each candidate value of `k`.
+
+- `sample_size`: int, float, None, or `"auto"`, default `"auto"`  
+  Subsample size used in each repeated clustering.
+  - If `int`, it is interpreted as the absolute subsample size.
+  - If `float` in `(0, 1]`, it is interpreted as a fraction of the dataset size.
+  - If `None` or `"auto"`, the subsample size is selected automatically from the dataset size and the largest candidate value of `k`.
+
+- `random_state`: int, default `42`  
+  Base random seed used for reproducible subsampling and clustering.
+
+- `n_jobs`: int, default `-1`  
+  Number of parallel jobs used during evaluation.
+
+- `eps`: float, default `1e-12`  
+  Numerical stability constant used when normalizing micro–macro discrepancies.
+
+---
+
+#### `evaluate`
+
+Evaluates Composite Silhouette over all candidate values of `k`.
+
+```python
+model.evaluate()
+```
+
+After calling `evaluate`, the results are stored in:
+
+```python
+model.results_df
+```
+
+The results table contains:
+
+- `k`: candidate number of clusters.
+- `avg S_micro`: average micro-averaged Silhouette across subsamples.
+- `avg S_macro`: average macro-averaged Silhouette across subsamples.
+- `w_micro`: average adaptive weight assigned to the micro view.
+- `S_mM`: Composite Silhouette score.
+- `std S_mM`: standard deviation of subsample-level composite scores.
+- `se S_mM`: standard error of the Composite Silhouette estimate.
+- `LCB S_mM`: lower-confidence-bound score, computed as `S_mM - se S_mM`.
+- `B_eff`: number of valid subsampling trials.
+- `sample_size`: resolved subsample size.
+- `sample_fraction`: resolved subsample fraction.
+
+---
+
+#### `get_optimal_k`
+
+Returns the selected number of clusters.
+
+```python
+model.get_optimal_k(use_lcb=False)
+```
+
+**Inputs**
+
+- `use_lcb`: bool, default `False`  
+  If `False`, selects the `k` that maximizes `S_mM`.  
+  If `True`, selects the `k` that maximizes `LCB S_mM`.
+
+**Returns**
+
+- `optimal_k`: int  
+  Selected number of clusters.
+
+---
+
+#### `get_results_dataframe`
+
+Returns the results as a pandas DataFrame indexed by `k`.
+
+```python
+results = model.get_results_dataframe()
+```
+
+**Returns**
+
+- `results`: pandas DataFrame  
+  Table containing the Composite Silhouette results for all candidate values of `k`.
+
+---
+
+#### `plot_results`
+
+Plots the Composite Silhouette curve together with the subsample-averaged micro- and macro-averaged Silhouette curves.
+
+```python
+model.plot_results()
+```
+
+If `ground_truth` was provided, it is shown as a vertical reference line.
+
+## Quick Start
+
+This example creates a simple synthetic dataset with five Gaussian clusters, evaluates candidate values of `k`, and selects the number of clusters using Composite Silhouette.
+
+```python
+from sklearn.datasets import make_blobs
+from sklearn.preprocessing import StandardScaler
+from compsil import CompSil
+
+# Create a simple synthetic dataset
+X, y = make_blobs(
+    n_samples=1000,
+    centers=5,
+    n_features=10,
+    cluster_std=1.5,
+    random_state=42,
+)
+
+# Standardize the data
+X = StandardScaler().fit_transform(X)
+
+# Initialize Composite Silhouette
+model = CompSil(
+    data=X,
+    ground_truth=5,
+    k_values=range(2, 11),
+    num_samples=10,
+    sample_size="auto",
+    random_state=0,
+    n_jobs=-1,
+)
+
+# Evaluate all candidate k values
+model.evaluate()
+
+# Select the number of clusters
+best_k = model.get_optimal_k()
+
+print("Selected k:", best_k)
+
+# Inspect the full results table
+results = model.get_results_dataframe()
+print(results)
+
+# Plot the Composite Silhouette curve
+model.plot_results()
+```
+
+The `S_mM` column in the results table contains the Composite Silhouette score for each candidate number of clusters. The selected number of clusters is the value of `k` that maximizes `S_mM`.
+
+CompSil can also be used to evaluate a single candidate number of clusters. In this case, pass an integer to `k_values`.
+
+```python
+# Evaluate a single candidate k
+model = CompSil(
+    data=X,
+    k_values=5
+)
+
+model.evaluate()
+
+# Composite Silhouette score for k=5
+print("Composite Silhouette score:", model.score_)
+
+# Full results table
+results = model.get_results_dataframe()
+print(results)
+```
+
+When a single value of `k` is evaluated, `model.score_` stores the corresponding Composite Silhouette score.
+
+## Acknowledgments
+This work was supported by [_Archimedes Research Unit_](https://archimedesai.gr/), [_Athena Research Center_](https://www.athenarc.gr/en).
+
+## License
+This project is licensed under the [MIT License](https://github.com/semoglou/compsil/blob/main/LICENSE).
+
+## Links
+- Package: [PyPI](https://pypi.org/project/compsil/)
+- Paper: Accepted at ECML PKDD 2026
+- DOI: Coming soon
+- Preprint: [arXiv:2604.13816](https://arxiv.org/abs/2604.13816)

compsil-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+compsil/__init__.py,sha256=ZxBnwgnAisd0YC5shzSWTNhQsWiTbfRxBW4340kj8p4,29
+compsil/compsil.py,sha256=KKx6da1QVDJa04hrMDPeqz18zurwvhwfdUa3pexjPVk,13133
+compsil-0.1.0.dist-info/licenses/LICENSE,sha256=kWn4HCOo2H6AuCu5oBQd2VJYyCuWyILiElYZKNZh5JM,1073
+compsil-0.1.0.dist-info/METADATA,sha256=3NISXriDBCYYUwsNVRmUDkBMP2vJclnmajbgTm8GMyg,12238
+compsil-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+compsil-0.1.0.dist-info/top_level.txt,sha256=yQVXj3-Zb3n52XwCIlLsvomfByXMcXa2Lm1ShGsD7BE,8
+compsil-0.1.0.dist-info/RECORD,,

compsil-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

compsil-0.1.0.dist-info/licenses/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.

compsil-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+compsil