SFCMEP (Semi-supervised Fuzzy Clustering with Membership Prior)

🔍 Overview

SFCMEP is a semi-supervised fuzzy clustering algorithm. Alongside the feature matrix it consumes a partially labelled target vector, converts those labels into a prior membership matrix, and lets that prior steer the iterative fuzzy partition. An expert-preference parameter rho controls how strongly the prior pulls the solution towards the supplied labels, and an exponential distance weighting governed by lam determines how quickly influence decays with distance from a centroid.

Cluster i is initialised from the samples labelled i, so cluster indices correspond to class indices — unlike a purely unsupervised method, the returned partition is aligned with the label space you provided.

⚙️ Class Definition

Class Name: SFCMEP

SFCMEP(
    K: int,
    random_state: int | None = None,
    max_iter: int = 200,
    rho: float = 0.5,
    lam: float = 1.0,
    tol: float = 1e-6,
)

📋 Parameters

Parameter	Type	Default	Description
`K`	`int`	required	Number of clusters. Also accepted as `n_clusters`.
`random_state`	`int` or `None`	`None`	Seed used to initialise centroids for unlabelled classes.
`max_iter`	`int`	`200`	Maximum number of iterations.
`rho`	`float`	`0.5`	Expert preference: how strongly the prior membership constrains the partition.
`lam`	`float`	`1.0`	Scaling parameter of the exponential distance weighting.
`tol`	`float`	`1e-6`	Convergence tolerance on the change in memberships and centroids.

📥 Input / 📤 Output

fit_predict(X, y) takes:

X — ndarray of shape (n_samples, n_features).
y — label vector of length n_samples, with None for unlabelled samples. Use dtype=object so that None can sit alongside integer class labels.

It returns a dictionary with:

membership_matrix — ndarray of shape (n_samples, n_clusters).
centroids — ndarray of shape (n_clusters, n_features).

As with every SCPP estimator, the canonical attributes are populated after fitting: memberships_, labels_, centers_ and n_clusters.

🚀 Usage Examples

import numpy as np
from soft_clustering import SFCMEP

rng = np.random.default_rng(0)
X = np.vstack([
    rng.normal(loc=0, scale=0.5, size=(50, 2)),
    rng.normal(loc=5, scale=0.5, size=(50, 2)),
])

# Semi-supervised: only a handful of samples carry a label.
y = np.array([0] * 5 + [None] * 45 + [1] * 5 + [None] * 45, dtype=object)

model = SFCMEP(K=2, random_state=0, max_iter=50)
result = model.fit_predict(X, y)

U = result["membership_matrix"]   # (100, 2)
V = result["centroids"]           # (2, 2)

print("Membership matrix shape:", U.shape)
print("Cluster centers:\n", V)

# The canonical protocol attributes are available too.
print("Hard labels:", model.labels_[:10])

🛠️ Methods

`fit_predict(X, y)`

Runs the semi-supervised optimisation and returns the membership matrix and centroids. The prior membership matrix is built once from y and the initial centroids, then memberships and centroids alternate until either tol or max_iter is reached.

📝 Implementation Notes

Samples labelled None contribute no prior and are clustered on the strength of the data alone; a fully None vector reduces the method to an unsupervised fuzzy partition with random centroid initialisation.
If a class appears in K but no sample carries that label, its centroid falls back to a randomly chosen sample.
The internal membership matrix is maintained as (n_clusters, n_samples) and transposed on return, so membership_matrix and memberships_ are both (n_samples, n_clusters).