# neurostatx.clustering.fuzzy

*module*

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L1-L1)

## neurostatx.clustering.fuzzy.FuzzyCMeans

*class*

```python
class FuzzyCMeans(ClusterMixin, BaseEstimator)
```

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][neurostatx.clustering.fuzzy.search_fuzzy_cmeans]
to evaluate a range
of ``k``. Based on scikit-fuzzy ``cmeans`` /
``cmeans_predict``.

**Parameters**

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

**Attributes**

- `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][neurostatx.clustering.fuzzy.FuzzyCMeans.fit].

**Examples**

```pycon
>>> 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,)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L20-L231)

### neurostatx.clustering.fuzzy.FuzzyCMeans.init

*attribute* · *instance attribute*

```python
init = init
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L92-L92)

### neurostatx.clustering.fuzzy.FuzzyCMeans.m

*attribute* · *instance attribute*

```python
m = m
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L88-L88)

### neurostatx.clustering.fuzzy.FuzzyCMeans.max_iter

*attribute* · *instance attribute*

```python
max_iter = max_iter
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L89-L89)

### neurostatx.clustering.fuzzy.FuzzyCMeans.metric

*attribute* · *instance attribute*

```python
metric = metric
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L91-L91)

### neurostatx.clustering.fuzzy.FuzzyCMeans.n_clusters

*attribute* · *instance attribute*

```python
n_clusters = n_clusters
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L87-L87)

### neurostatx.clustering.fuzzy.FuzzyCMeans.random_state

*attribute* · *instance attribute*

```python
random_state = random_state
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L93-L93)

### neurostatx.clustering.fuzzy.FuzzyCMeans.tol

*attribute* · *instance attribute*

```python
tol = tol
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L90-L90)

### neurostatx.clustering.fuzzy.FuzzyCMeans.fit

*method*

```python
def fit(X, y=None)
```

Fit the fuzzy C-Means model.

**Parameters**

- `X` (`array-like of shape (n_samples, n_features)`) — Training data.
- `y` (`Ignored`) (default: `None`) — Not used, present for sklearn API compatibility.

**Returns**

- `self` (`FuzzyCMeans`) — Fitted estimator.

**Examples**

```pycon
>>> 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
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L128-L170)

### neurostatx.clustering.fuzzy.FuzzyCMeans.predict

*method*

```python
def predict(X)
```

Predict hard cluster labels for ``X``.

**Parameters**

- `X` (`array-like of shape (n_samples, n_features)`) — New data to predict.

**Returns**

- `labels` (`ndarray of shape (n_samples,)`) — Hard cluster labels.

**Examples**

```pycon
>>> 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,)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L172-L196)

### neurostatx.clustering.fuzzy.FuzzyCMeans.predict_proba

*method*

```python
def predict_proba(X)
```

Predict fuzzy membership for ``X``.

**Parameters**

- `X` (`array-like of shape (n_samples, n_features)`) — New data to predict.

**Returns**

- `membership` (`ndarray of shape (n_samples, n_clusters)`) — Membership degree of each sample to each cluster. Rows sum to 1.

**Examples**

```pycon
>>> 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)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L198-L223)

## neurostatx.clustering.fuzzy.fuzzyCmeans

*function*

```python
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][neurostatx.clustering.fuzzy.search_fuzzy_cmeans].

> **Notes**
>
> Deprecated. Use [FuzzyCMeans][neurostatx.clustering.fuzzy.FuzzyCMeans]
> for a single number of clusters, or
> [search_fuzzy_cmeans][neurostatx.clustering.fuzzy.search_fuzzy_cmeans]
> to evaluate a range of ``k``.

**Parameters**

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

**Returns**

- `cntr` (`list`) — Cluster centroids for each ``k``.
- `u` (`list`) — Membership matrices for each ``k``.
- `wss` (`list`) — Within-cluster sum of squared errors.
- `fpc` (`list`) — Fuzzy partition coefficients.
- `ss` (`list`) — Silhouette scores.
- `chi` (`list`) — Calinski-Harabasz indices.
- `dbi` (`list`) — Davies-Bouldin indices.
- `gap` (`list`) — GAP statistics.
- `sk` (`list`) — GAP standard errors.

**Examples**

```pycon
>>> 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
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L443-L543)

## neurostatx.clustering.fuzzy.search_fuzzy_cmeans

*function*

```python
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**

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

**Returns**

- `cntr` (`tuple of ndarray`) — Cluster centroids for each ``k``.
- `u` (`tuple of ndarray`) — Membership matrices for each ``k``.
- `wss` (`tuple of float`) — Within-cluster sum of squared errors.
- `fpc` (`tuple of float`) — Fuzzy partition coefficients.
- `ss` (`tuple of float`) — Silhouette scores.
- `chi` (`tuple of float`) — Calinski-Harabasz indices.
- `dbi` (`tuple of float`) — Davies-Bouldin indices.
- `gap` (`tuple of float`) — GAP statistics (or None if ``compute_gap`` is False).
- `sk` (`tuple of float`) — GAP standard errors (or None if ``compute_gap`` is False).

**Examples**

```pycon
>>> 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
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/clustering/fuzzy.py#L322-L440)