SoftKSC (Soft Kernel Spectral Clustering) Documentation

🔍 Overview

SoftKSC is a semi-supervised kernel spectral clustering algorithm that separates data using two non-parallel hyperplanes. It combines kernel learning with soft clustering logic by modeling confidence scores for both classes.

---

⚙️ Class Definition

Class Name: SoftKSC This class implements the Soft Kernel Spectral Clustering using a dual-space solution and RBF kernel similarity.

class SoftKSC:
    def __init__(self, gamma: float = 1.0, C: float = 1.0):
        ...

---

📋 Parameters

Parameter	Type	Default	Description
gamma	float	1.0	RBF kernel coefficient
C	float	1.0	Regularization term in the dual formulation

---

🚀 Usage Examples

from soft_clustering._soft_ksc._soft_ksc import SoftKSC
from sklearn.datasets import make_moons
import numpy as np

X, y = make_moons(n_samples=200, noise=0.1, random_state=42)
y = np.where(y == 0, -1, 1)

# Use 20% labeled, 80% unlabeled
X_labeled = X[:40]
y_labeled = y[:40]
X_unlabeled = X[40:]

model = SoftKSC(gamma=2.0, C=1.0)
model.fit(X_labeled, y_labeled, X_unlabeled)

print("Predicted Labels:", model.predict(X))
print("Soft Probabilities:", model.predict_proba(X))

---

📥 Input / 📤 Output

• Input to fit(X_labeled, y_labeled, X_unlabeled):

  • X_labeled (np.ndarray): Labeled training data (N_l x D)

  • y_labeled (np.ndarray): Class labels in {-1, 1} (N_l,)

  • X_unlabeled (np.ndarray): Unlabeled data (N_u x D)

• Returns:

  • Soft membership probabilities: predict_proba(X) → (N x 2)

  • Hard cluster predictions: predict(X) → (N,)

---

🛠️ Methods

• fit(X_labeled, y_labeled, X_unlabeled): Fits the model using both labeled and unlabeled data

• predict_proba(X): Returns soft membership scores to both classes

• predict(X): Returns predicted class labels {-1, 1}

---

📝 Implementation Notes

• Uses RBF kernel similarity matrix for dual formulation

• Solves two linear systems for class-specific projections

• Uses relative distance to compute soft assignments

• Designed for semi-supervised clustering with partial labels

---

📚 Reference

1. Faraki, M., et al. (2013). Soft Kernel Spectral Clustering.