# neurostatx.clustering.viz

*module*

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

## neurostatx.clustering.viz.plot_clustering_results

*function*

```python
def plot_clustering_results(lst, title, metric, output, errorbar=None, annotation=None)
```

Plot a clustering goodness-of-fit curve and write it to a file.

**Parameters**

- `lst` (`list`) — Metric values to plot, one per cluster count starting at ``k=2``.
- `title` (`str`) — Title of the plot.
- `metric` (`str`) — Y-axis label for the plotted metric.
- `output` (`str`) — Output filename.
- `errorbar` (`list`) (default: `None`) — Values to plot as error bars (CI, SD, etc.). Defaults to None.
- `annotation` (`str`) (default: `None`) — Text annotation drawn on the plot. Defaults to None.

**Examples**

```pycon
>>> from neurostatx.clustering.viz import plot_clustering_results
>>> plot_clustering_results([1.2, 0.8, 0.6], "WSS", "WSS", "wss.png")
```

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

## neurostatx.clustering.viz.plot_dendrogram

*function*

```python
def plot_dendrogram(X, output, title='Dendrograms', annotation=None)
```

Plot a hierarchical clustering dendrogram and write it to a file.

**Parameters**

- `X` (`DataFrame`) — Data used to compute Ward linkage.
- `output` (`str`) — Output filename and path.
- `title` (`str`) (default: `'Dendrograms'`) — Title for the plot. Defaults to ``"Dendrograms"``.
- `annotation` (`str`) (default: `None`) — Text annotation drawn on the plot. Defaults to None.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.clustering.viz import plot_dendrogram
>>> X = pd.DataFrame([[0.0, 0.1], [0.2, 0.0], [1.0, 1.1], [0.9, 1.0]])
>>> plot_dendrogram(X, "dendrogram.png")
```

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

## neurostatx.clustering.viz.plot_fuzzy_cmeans_solutions

*function*

```python
def plot_fuzzy_cmeans_solutions(results, output, min_clusters=2, max_clusters=None)
```

Plot a grid of Fuzzy C-Means solutions for a range of ``k``.

**Parameters**

- `results` (`list of tuple`) — Per-k worker results from [process_cluster][neurostatx.clustering.fuzzy.process_cluster]. Each tuple must contain ``n_cluster``, ``n_iter``, ``fpc``, centroids, visualization x/y points, and hard labels.
- `output` (`str`) — Output folder. The figure is saved as ``viz_multiple_cluster_nb.png``.
- `min_clusters` (`int`) (default: `2`) — Smallest ``k`` that was fitted. Defaults to 2.
- `max_clusters` (`int`) (default: `None`) — Largest ``k`` requested, used only for subplot grid size. Defaults to the number of results plus ``min_clusters - 1``.

**Examples**

```pycon
>>> from neurostatx.clustering.viz import plot_fuzzy_cmeans_solutions
>>> result = (2, 10, 0.8, [[0.0, 0.0], [1.0, 1.0]], None, None, None,
...           None, None, None, None, [0.0, 1.0], [0.0, 1.0], [0, 1])
>>> plot_fuzzy_cmeans_solutions([result], output=".", min_clusters=2)
```

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

## neurostatx.clustering.viz.plot_parallel_plot

*function*

```python
def plot_parallel_plot(X, labels, output, mean_values=False, cmap='magma', title='Parallel Coordinates plot.')
```

Plot parallel coordinates for clustered features and write a PNG file.

**Parameters**

- `X` (`DataFrame`) — Input dataset of shape (n_samples, n_features).
- `labels` (`np.array`) — Hard cluster labels of shape (n_samples,).
- `output` (`str`) — Output PNG filename.
- `mean_values` (`bool`) (default: `False`) — If True, plot the mean of each feature per cluster. Defaults to False.
- `cmap` (`str`) (default: `'magma'`) — Colormap name. Defaults to ``"magma"``.
- `title` (`str`) (default: `'Parallel Coordinates plot.'`) — Title of the plot. Defaults to ``"Parallel Coordinates plot."``.

**Examples**

```pycon
>>> import pandas as pd
>>> import numpy as np
>>> from neurostatx.clustering.viz import plot_parallel_plot
>>> X = pd.DataFrame({"a": [0.0, 0.1, 1.0, 0.9],
...                   "b": [0.2, 0.0, 1.1, 1.0]})
>>> plot_parallel_plot(X, np.array([0, 0, 1, 1]), "parallel.png",
...                    mean_values=True)
```

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

## neurostatx.clustering.viz.radar_plot

*function*

```python
def radar_plot(X, labels, output, frame='circle', title='Radar plot', cmap='magma')
```

Plot a radar chart of feature means by cluster and write a PNG file.

ANOVA p-values across clusters are annotated on each axis. Dense
annotations can appear when many clusters are plotted.

**Parameters**

- `X` (`DataFrame`) — Input dataset of shape (n_samples, n_features).
- `labels` (`np.array`) — Hard cluster labels of shape (n_samples,).
- `output` (`str`) — Output PNG filename.
- `frame` (`str`) (default: `'circle'`) — Radar frame shape, ``"circle"`` or ``"polygon"``. Defaults to ``"circle"``.
- `title` (`str`) (default: `'Radar plot'`) — Title of the plot. Defaults to ``"Radar plot"``.
- `cmap` (`str`) (default: `'magma'`) — Colormap name. Defaults to ``"magma"``.

**Examples**

```pycon
>>> import pandas as pd
>>> import numpy as np
>>> from neurostatx.clustering.viz import radar_plot
>>> X = pd.DataFrame({"a": [0.0, 0.1, 1.0, 0.9], "b": [0.2, 0.0, 1.1, 1.0],
...                   "c": [0.1, 0.2, 0.9, 1.0]})
>>> radar_plot(X, np.array([0, 0, 1, 1]), "radar.png")
```

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

## neurostatx.clustering.viz.sort_int_labels_legend

*function*

```python
def sort_int_labels_legend(ax, title=None)
```

Reorder legend labels numerically and keep matching handles.

**Parameters**

- `ax` (`Matplotlib Axes`) — Axes whose legend labels should be sorted.
- `title` (`str`) (default: `None`) — Title of the legend. Defaults to None.

**Returns**

- `legend` (`matplotlib.legend.Legend`) — Legend with numerically sorted labels.

**Examples**

```pycon
>>> import matplotlib.pyplot as plt
>>> from neurostatx.clustering.viz import sort_int_labels_legend
>>> fig, ax = plt.subplots()
>>> ax.plot([0, 1], [0, 1], label="2")
>>> ax.plot([0, 1], [1, 0], label="1")
>>> legend = sort_int_labels_legend(ax, title="Cluster #")
>>> [t.get_text() for t in legend.get_texts()]
['1', '2']
```

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