# neurostatx.cli.CompareClustering

*module*

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

## neurostatx.cli.CompareClustering.app

*attribute* · *module attribute*

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

Cyclopts application for the CompareClustering command-line tool.

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/CompareClustering.py#L18-L18)

## neurostatx.cli.CompareClustering.CompareClustering

*function*

```python
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](https://doi.org/10.1007/BF01908075)
> 
> [2] [Rand, W. M. (1971). Objective criteria for the evaluation of
> clustering methods](https://doi.org/10.2307/2284239)
> 
> [3] [Steinley, D. (2004). Properties of the Hubert-Arabie adjusted Rand
> index](https://psycnet.apa.org/doi/10.1037/1082-989X.9.3.386)
> 
> [4] [scikit-learn Adjusted Rand
> Index](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.adjusted_rand_score.html)

**Parameters**

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

**Examples**

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

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/CompareClustering.py#L22-L217)