silhouetteclassifier

Unsupervised instance classification via an improved silhouette score, with an optional ensemble-metric refinement stage.

Instead of training on labels, SilhouetteClassifier ranks every instance by a weighted combination of local cohesion (closeness to nearest neighbors) and global separation (distance to the rest of the data), then partitions the ranked list according to the desired class ratios. This makes it useful for quick, label-light baselines on tabular data — including imbalanced binary problems — and for studying how internal geometry alone separates classes.

Import name is silclass (the distribution name on PyPI is silhouetteclassifier).

Installation

pip install silhouetteclassifier

For the benchmark comparison script (KMeans / UMAP / DBSCAN / MeanShift / OPTICS):

pip install "silhouetteclassifier[benchmark]"

Quick start

import pandas as pd
from silclass import SilhouetteClassifier

df = pd.read_csv("reduced.csv")
y = df["vital.status"]
X = df.drop(columns=["vital.status"])

clf = SilhouetteClassifier(n_neighbors=7)

# Supervised ratios: pass y so the class proportions are derived from labels
y_pred = clf.fit_predict(X, y=y)

# Or specify the major-class ratio directly (no labels needed)
# y_pred = clf.fit_predict(X, major_ratio=0.7, major_class=0)

print(clf.calculate_f1_scores(y))

Multi-class

y_pred = clf.fit_predict(
    X,
    class_ratios=[0.5, 0.3, 0.2],   # must sum to 1.0
    class_labels=[0, 1, 2],
)

Optional refinement

EnsembleRefinement takes initial binary labels and iteratively flips points to improve an ensemble of internal metrics (silhouette, Davies–Bouldin, Calinski–Harabasz, connectivity, density ratio). It is fully unsupervised; any true labels passed in are used only for reporting.

from silclass import EnsembleRefinement

initial = clf.fit_predict(X, y=y)
refiner = EnsembleRefinement(max_iterations=30, early_stopping=5)
refined = refiner.fit_refine(X, initial_labels=initial, y_true=y)  # y_true optional

API summary

SilhouetteClassifier(n_neighbors=15, scale_data=True)

• fit_predict(X, y=None, major_ratio=0.5, major_class=0, class_ratios=None, class_labels=None) → labels
• calculate_scores(X) → (cohesion, separation, silhouette)
• calculate_f1_scores(true_labels) → dict with per-class F1, F1_major, F1_minor, accuracy
• get_instance_data() / get_sorted_instances() → per-instance scores and labels

EnsembleRefinement(...)

• fit_refine(X, initial_labels=None, y_true=None, major_ratio=0.5) → refined labels
• get_history() → DataFrame of per-iteration metrics

License

MIT — see LICENSE.