neurostatx.cli.CompareClustering

Attributes

Name	Description
app	Cyclopts application for the CompareClustering command-line tool.

Functions

Name	Description
CompareClustering	Compare clustering solutions with an Adjusted Rand Index (ARI) heatmap.

appattributemodule attribute#

View source

app = App(default_parameter=Parameter(negative=()))

Cyclopts application for the CompareClustering command-line tool.

CompareClusteringfunction#

View source

def CompareClustering(in_dataset: Annotated[List[str], Parameter(show_default=False, group='Essential Files Options')], id_column: Annotated[str, Parameter(show_default=False, group='Essential Files Options')], desc_columns: Annotated[int, Parameter(show_default=False, group='Essential Files Options')], out_folder: Annotated[str, Parameter(show_default=False, group='Essential Files Options')], columns_name: Annotated[List[str], Parameter(group='Visualization Options', show_default=True)] = [], cmap: Annotated[str, Parameter(show_default=True, group='Visualization Options')] = 'magma', title: Annotated[str, Parameter(show_default=True, group='Visualization Options')] = 'Adjusted Rand Index Heatmap', verbose: Annotated[bool, Parameter(-v, --verbose, group='Optional parameters')] = False, save_parameters: Annotated[bool, Parameter(-s, --save_parameters, group='Optional parameters')] = False, overwrite: Annotated[bool, Parameter(-f, --overwrite, group='Optional parameters')] = False)

Compare clustering solutions with an Adjusted Rand Index (ARI) heatmap.

CompareClustering compares clustering results from multiple solutions using ARI and writes a heatmap of the pairwise scores.

Notes

Adjusted Rand Index

The Adjusted Rand Index (ARI) measures similarity between two clustering results by comparing predicted labels to ground-truth labels [1]. ARI ranges from -1 to 1, where 1 means the two clusterings are identical, 0 means they are independent (as good as random labelling), and -1 means they are completely different. ARI extends the Rand Index (RI) [2] by accounting for the fact that RI is expected to be higher for a large number of clusters. See also [3] and the scikit-learn documentation [4].

References

[1] Hubert, L., & Arabie, P. (1985). Comparing partitions

[2] Rand, W. M. (1971). Objective criteria for the evaluation of clustering methods

[3] Steinley, D. (2004). Properties of the Hubert-Arabie adjusted Rand index

[4] scikit-learn Adjusted Rand Index

Parameters

Name	Type	Default	Description
in_dataset	List[str]	required	Input dataset(s) (at least 2 are expected to produce a comparison).
id_column	str	required	Name of the column containing the subject’s ID tag. Required for proper handling of IDs and merging multiple datasets.
desc_columns	int	required	Number of descriptive columns at the beginning of the dataset to exclude in statistics and descriptive tables.
out_folder	str	required	Output folder containing the results.
columns_name	List[str]	[]	Name given to each input dataset (needs to be in the same order as the input datasets). Defaults to [].
cmap	str	'magma'	Name of the colormap to use. Defaults to magma. See https://matplotlib.org/stable/tutorials/colors/colormaps.html.
title	str	'Adjusted Rand Index Heatmap'	Heatmap title. Defaults to Adjusted Rand Index Heatmap.
verbose	bool	False	If true, produce verbose output. Defaults to False.
save_parameters	bool	False	If true, will save input parameters to .txt file. Defaults to False.
overwrite	bool	False	If true, force overwriting of existing output files. Defaults to False.

Examples

CompareClustering --in_dataset dataset1.csv --in_dataset dataset2.csv
--in_dataset dataset3.csv --id_column ID --desc_columns 1 --out_folder
./ --columns_name dataset1 dataset2 dataset3 --title "ARI Heatmap"
--verbose