neurostatx.clustering.viz

Functions

Name	Description
plot_clustering_results	Plot a clustering goodness-of-fit curve and write it to a file.
plot_dendrogram	Plot a hierarchical clustering dendrogram and write it to a file.
plot_fuzzy_cmeans_solutions	Plot a grid of Fuzzy C-Means solutions for a range of k.
plot_parallel_plot	Plot parallel coordinates for clustered features and write a PNG file.
radar_plot	Plot a radar chart of feature means by cluster and write a PNG file.
sort_int_labels_legend	Reorder legend labels numerically and keep matching handles.

plot_clustering_resultsfunction#

View source

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

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

Examples

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

plot_dendrogramfunction#

View source

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

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

Parameters

Name	Type	Default	Description
X	DataFrame	required	Data used to compute Ward linkage.
output	str	required	Output filename and path.
title	str	'Dendrograms'	Title for the plot. Defaults to "Dendrograms".
annotation	str	None	Text annotation drawn on the plot. Defaults to None.

Examples

>>> 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")

plot_fuzzy_cmeans_solutionsfunction#

View source

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

Name	Type	Default	Description
results	list of tuple	required	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	required	Output folder. The figure is saved as viz_multiple_cluster_nb.png.
min_clusters	int	2	Smallest k that was fitted. Defaults to 2.
max_clusters	int	None	Largest k requested, used only for subplot grid size. Defaults to the number of results plus min_clusters - 1.

Examples

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

plot_parallel_plotfunction#

View source

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

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

Examples

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

radar_plotfunction#

View source

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

Name	Type	Default	Description
X	DataFrame	required	Input dataset of shape (n_samples, n_features).
labels	np.array	required	Hard cluster labels of shape (n_samples,).
output	str	required	Output PNG filename.
frame	str	'circle'	Radar frame shape, "circle" or "polygon". Defaults to "circle".
title	str	'Radar plot'	Title of the plot. Defaults to "Radar plot".
cmap	str	'magma'	Colormap name. Defaults to "magma".

Examples

>>> 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")

sort_int_labels_legendfunction#

View source

def sort_int_labels_legend(ax, title=None)

Reorder legend labels numerically and keep matching handles.

Parameters

Name	Type	Default	Description
ax	Matplotlib Axes	required	Axes whose legend labels should be sorted.
title	str	None	Title of the legend. Defaults to None.

Returns

legendmatplotlib.legend.Legend

Legend with numerically sorted labels.

Examples

>>> 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']