# neurostatx.clustering.metrics

*module*

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

## neurostatx.clustering.metrics.compute_evaluation_metrics

*function*

```python
def compute_evaluation_metrics(X, labels, metric='euclidean')
```

Compute silhouette, Calinski-Harabasz, and Davies-Bouldin scores.

**Parameters**

- `X` (`array - like`) — Data used to evaluate the clustering solution.
- `labels` (`list`) — Cluster labels for each sample.
- `metric` (`str`) (default: `'euclidean'`) — Distance metric passed to the silhouette score. Defaults to ``"euclidean"``. Accepts options from ``sklearn.metrics.pairwise.pairwise_distances``.

**Returns**

- `ss` (`float`) — Silhouette score.
- `chi` (`float`) — Calinski-Harabasz index.
- `dbi` (`float`) — Davies-Bouldin index.

**Examples**

```pycon
>>> import numpy as np
>>> from neurostatx.clustering.metrics import compute_evaluation_metrics
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.1]])
>>> ss, chi, dbi = compute_evaluation_metrics(X, [0, 0, 1, 1])
>>> ss > 0
True
```

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

## neurostatx.clustering.metrics.compute_gap_stats

*function*

```python
def compute_gap_stats(X, wss, nrefs, n_cluster, m=2, error=1e-06, maxiter=1000, metric='euclidean', init=None)
```

Compute the GAP statistic against uniformly sampled reference data.

**Parameters**

- `X` (`np.array`) — Data array used to generate reference samples.
- `wss` (`float`) — Within-cluster sum of squared errors for the fitted model.
- `nrefs` (`int`) — Number of random reference datasets to average.
- `n_cluster` (`int`) — Number of clusters in the fitted model.
- `m` (`float`) (default: `2`) — Fuzziness exponent passed to Fuzzy C-Means. Defaults to 2.
- `error` (`float`) (default: `1e-06`) — Convergence tolerance. Defaults to 1e-6.
- `maxiter` (`int`) (default: `1000`) — Maximum iterations for each reference fit. Defaults to 1000.
- `metric` (`str`) (default: `'euclidean'`) — Distance metric. Defaults to ``"euclidean"``.
- `init` (`array`) (default: `None`) — Initial fuzzy c-partitioned matrix. Defaults to None.

**Returns**

- `gap` (`float`) — GAP statistic.
- `sk` (`float`) — Standard error of the GAP statistic.

**Examples**

```pycon
>>> import numpy as np
>>> from neurostatx.clustering.metrics import compute_gap_stats,
...                                           compute_sse
>>> X = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [0.9, 1.0]])
>>> cntr = np.array([[0.05, 0.0], [0.95, 1.0]])
>>> labels = np.array([0, 0, 1, 1])
>>> gap, sk = compute_gap_stats(X, compute_sse(X, cntr, labels),
...                             nrefs=2, n_cluster=2)
>>> gap > 0
True
```

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

## neurostatx.clustering.metrics.compute_knee_location

*function*

```python
def compute_knee_location(lst, direction='decreasing')
```

Return the elbow location of a clustering metric curve.

**Parameters**

- `lst` (`list`) — Metric values used to locate the elbow, typically one per ``k``.
- `direction` (`str`) (default: `'decreasing'`) — Curve direction passed to Kneed. Defaults to ``"decreasing"``.

**Returns**

- `elbow` (`int`) — Estimated elbow location (cluster count).

**Examples**

```pycon
>>> from neurostatx.clustering.metrics import compute_knee_location
>>> compute_knee_location([10.0, 4.0, 3.5, 3.2])
3
```

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

## neurostatx.clustering.metrics.compute_rand_index

*function*

```python
def compute_rand_index(dict)
```

Compute pairwise adjusted Rand indices from membership dataframes.

Hard labels are obtained with ``argmax`` before scoring, because the
adjusted Rand index applies only to crisp partitions.

**Parameters**

- `dict` (`dict`) — Mapping of labels to membership dataframes.

**Returns**

- `ari` (`np.array`) — Symmetric pairwise adjusted Rand index matrix.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.clustering.metrics import compute_rand_index
>>> a = pd.DataFrame([[0.9, 0.1], [0.2, 0.8]])
>>> b = pd.DataFrame([[0.8, 0.2], [0.1, 0.9]])
>>> compute_rand_index({"a": a, "b": b}).shape
(2, 2)
```

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

## neurostatx.clustering.metrics.compute_sse

*function*

```python
def compute_sse(X, cntr, labels)
```

Compute the within-cluster sum of squared errors (WSS).

**Parameters**

- `X` (`array`) — Original data of shape (n_samples, n_features).
- `cntr` (`array`) — Cluster centroids of shape (n_clusters, n_features).
- `labels` (`array`) — Hard cluster labels of shape (n_samples,).

**Returns**

- `WSS` (`float`) — Within-cluster sum of squared errors.

**Examples**

```pycon
>>> import numpy as np
>>> from neurostatx.clustering.metrics import compute_sse
>>> X = np.array([[0.0, 0.0], [1.0, 1.0]])
>>> cntr = np.array([[0.0, 0.0], [1.0, 1.0]])
>>> compute_sse(X, cntr, np.array([0, 1]))
0.0
```

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

## neurostatx.clustering.metrics.find_optimal_gap

*function*

```python
def find_optimal_gap(gap, sk)
```

Return the first k satisfying Tibshirani's GAP rule.

Selects the first index where ``GAP[k] >= GAP[k+1] - SD[k+1]``.

**Parameters**

- `gap` (`np.array`) — GAP statistic values for a range of cluster counts.
- `sk` (`np.array`) — Standard errors aligned with ``gap``.

**Returns**

- `optimal` (`int`) — Index of the selected solution.

**Examples**

```pycon
>>> import numpy as np
>>> from neurostatx.clustering.metrics import find_optimal_gap
>>> find_optimal_gap(np.array([0.2, 0.8, 0.7]), np.array([0.1, 0.1, 0.1]))
1
```

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