neurostatx.clustering.fuzzy

Classes

Name	Description
FuzzyCMeans	Fuzzy C-Means clustering.

Functions

Name	Description
fuzzyCmeans	Deprecated wrapper around
search_fuzzy_cmeans	Fit Fuzzy C-Means for each k in [min_clusters, max_clusters].

FuzzyCMeansclass#

View source

class FuzzyCMeans(n_clusters=2, m=2.0, max_iter=1000, tol=1e-06, metric='euclidean', init=None, random_state=None)

Bases: ClusterMixin, BaseEstimator

Fuzzy C-Means clustering.

Soft clustering estimator with a sklearn-compatible API. Fits a single number of clusters; use search_fuzzy_cmeans to evaluate a range of k. Based on scikit-fuzzy cmeans / cmeans_predict.

Parameters

Name	Type	Default	Description
n_clusters	int	2	Number of clusters to form. Defaults to 2.
m	float	2.0	Fuzziness exponent applied to the membership function. m=1 yields crisp clusters; larger values increase fuzziness. Defaults to 2.
max_iter	int	1000	Maximum number of iterations. Defaults to 1000.
tol	float	1e-06	Convergence tolerance (stopping criterion). Defaults to 1e-6.
metric	str	'euclidean'	Distance metric passed to scikit-fuzzy. Defaults to "euclidean".
init	array-like of shape (n_clusters, n_samples)	None	Initial fuzzy c-partitioned matrix. Defaults to None (random init).
random_state	int, numpy.RandomState instance or None	None	Seed used for centroid initialization. Defaults to None.

Attributes

Name	Type	Description
cluster_centers_	ndarray of shape (n_clusters, n_features)	Coordinates of cluster centroids.
u_	ndarray of shape (n_clusters, n_samples)	Fuzzy membership matrix (scikit-fuzzy layout).
labels_	ndarray of shape (n_samples,)	Hard cluster labels (argmax of membership).
fpc_	float	Fuzzy partition coefficient.
n_iter_	int	Number of iterations run until convergence.
inertia_	float	Within-cluster sum of squared errors (WSS).
n_features_in_	int	Number of features seen during fit.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.fuzzy import FuzzyCMeans
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.0]])
>>> fcm = FuzzyCMeans(n_clusters=2, random_state=0).fit(X)
>>> fcm.labels_.shape
(4,)

initattributeinstance attribute#

View source

init = init

mattributeinstance attribute#

View source

m = m

max_iterattributeinstance attribute#

View source

max_iter = max_iter

metricattributeinstance attribute#

View source

metric = metric

n_clustersattributeinstance attribute#

View source

n_clusters = n_clusters

random_stateattributeinstance attribute#

View source

random_state = random_state

tolattributeinstance attribute#

View source

tol = tol

fitmethod#

View source

def fit(X, y=None)

Fit the fuzzy C-Means model.

Parameters

Name	Type	Default	Description
X	array-like of shape (n_samples, n_features)	required	Training data.
y	Ignored	None	Not used, present for sklearn API compatibility.

Returns

selfFuzzyCMeans

Fitted estimator.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.fuzzy import FuzzyCMeans
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.0]])
>>> fcm = FuzzyCMeans(n_clusters=2, random_state=0).fit(X)
>>> fcm.n_features_in_
2

predictmethod#

View source

def predict(X)

Predict hard cluster labels for X.

Parameters

Name	Type	Description
X	array-like of shape (n_samples, n_features)	New data to predict.

Returns

labelsndarray of shape (n_samples,)

Hard cluster labels.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.fuzzy import FuzzyCMeans
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.0]])
>>> fcm = FuzzyCMeans(n_clusters=2, random_state=0).fit(X)
>>> fcm.predict(X).shape
(4,)

predict_probamethod#

View source

def predict_proba(X)

Predict fuzzy membership for X.

Parameters

Name	Type	Description
X	array-like of shape (n_samples, n_features)	New data to predict.

Returns

membershipndarray of shape (n_samples, n_clusters)

Membership degree of each sample to each cluster. Rows sum to 1.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.fuzzy import FuzzyCMeans
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.0]])
>>> fcm = FuzzyCMeans(n_clusters=2, random_state=0).fit(X)
>>> proba = fcm.predict_proba(X)
>>> proba.shape
(4, 2)

fuzzyCmeansfunction#

View source

def fuzzyCmeans(X, max_cluster=10, m=2, error=1e-06, maxiter=1000, init=None, metric='euclidean', output='./', processes=1, verbose=False)

Deprecated wrapper around search_fuzzy_cmeans.

Notes

Deprecated. Use FuzzyCMeans for a single number of clusters, or search_fuzzy_cmeans to evaluate a range of k.

Parameters

Name	Type	Default	Description
X	np.array	required	Array of data to cluster (subjects x features).
max_cluster	int	10	Maximum number of clusters to fit a model for. Defaults to 10.
m	float	2	Exponentiation value to apply on the membership function. Defaults to 2.
error	float	1e-06	Stopping criterion. Defaults to 1e-6.
maxiter	int	1000	Maximum number of iterations. Defaults to 1000.
init	2d array	None	Initial fuzzy c-partitioned matrix. Defaults to None.
metric	str	'euclidean'	Distance metric used for intra/inter subject and cluster distance. Defaults to "euclidean".
output	str	'./'	Output folder for the visualization. Defaults to "./".
processes	int	1	Number of processes to use. Defaults to 1.
verbose	bool	False	If True, produce verbose output. Defaults to False.

Returns

cntrlist

Cluster centroids for each k.

ulist

Membership matrices for each k.

wsslist

Within-cluster sum of squared errors.

fpclist

Fuzzy partition coefficients.

sslist

Silhouette scores.

chilist

Calinski-Harabasz indices.

dbilist

Davies-Bouldin indices.

gaplist

GAP statistics.

sklist

GAP standard errors.

Examples

>>> import numpy as np
>>> from neurostatx.clustering.fuzzy import fuzzyCmeans
>>> X = np.random.RandomState(0).rand(20, 3)
>>> cntr, u, wss, fpc, ss, chi, dbi, gap, sk = fuzzyCmeans(
...     X, max_cluster=3, processes=1, output=None
... )
>>> len(cntr)
2

search_fuzzy_cmeansfunction#

View source

def search_fuzzy_cmeans(X, min_clusters=2, max_clusters=10, n_jobs=1, compute_gap=True, output=None, verbose=False, m=2.0, max_iter=1000, tol=1e-06, metric='euclidean', init=None, random_state=None)

Fit Fuzzy C-Means for each k in [min_clusters, max_clusters].

Parallelizes over k and optionally writes a multi-panel visualization of all solutions.

Parameters

Name	Type	Default	Description
X	array-like of shape (n_samples, n_features)	required	Data to cluster.
min_clusters	int	2	Smallest number of clusters to fit. Defaults to 2.
max_clusters	int	10	Largest number of clusters to fit. Defaults to 10.
n_jobs	int	1	Number of parallel jobs. Defaults to 1.
compute_gap	bool	True	If True, compute GAP statistics (expensive). Defaults to True.
output	str	None	Folder in which to save viz_multiple_cluster_nb.png. If None, no figure is written. Defaults to None.
verbose	bool	False	Verbosity flag forwarded to sklearn Parallel. Defaults to False.
m	float	2.0	Fuzziness exponent. Defaults to 2.
max_iter	int	1000	Maximum iterations per model. Defaults to 1000.
tol	float	1e-06	Convergence tolerance. Defaults to 1e-6.
metric	str	'euclidean'	Distance metric. Defaults to "euclidean".
init	list of array-like	None	Initial membership matrices, one per k from min_clusters to max_clusters. Defaults to None.
random_state	int, numpy.RandomState instance or None	None	Seed forwarded to each FuzzyCMeans fit. Defaults to None.

Returns

cntrtuple of ndarray

Cluster centroids for each k.

utuple of ndarray

Membership matrices for each k.

wsstuple of float

Within-cluster sum of squared errors.

fpctuple of float

Fuzzy partition coefficients.

sstuple of float

Silhouette scores.

chituple of float

Calinski-Harabasz indices.

dbituple of float

Davies-Bouldin indices.

gaptuple of float

GAP statistics (or None if compute_gap is False).

sktuple of float

GAP standard errors (or None if compute_gap is False).

Examples

>>> import numpy as np
>>> from neurostatx.clustering.fuzzy import search_fuzzy_cmeans
>>> X = np.random.RandomState(0).rand(30, 4)
>>> cntr, u, wss, fpc, ss, chi, dbi, gap, sk = search_fuzzy_cmeans(
...     X, min_clusters=2, max_clusters=3, compute_gap=False, n_jobs=1
... )
>>> len(cntr)
2