# neurostatx.cli.FuzzyClustering *module* [View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/FuzzyClustering.py#L1-L1) ## neurostatx.cli.FuzzyClustering.app *attribute* · *module attribute* ```python app = App(default_parameter=Parameter(negative=())) ``` Cyclopts application for the FuzzyClustering command-line tool. [View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/FuzzyClustering.py#L32-L32) ## neurostatx.cli.FuzzyClustering.FuzzyClustering *function* ```python def FuzzyClustering(in_dataset: Annotated[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')], k: Annotated[int, Parameter(show_default=True, group='Clustering Options')] = 10, m: Annotated[float, Parameter(show_default=True, group='Clustering Options')] = 2, error: Annotated[float, Parameter(show_default=True, group='Clustering Options')] = 1e-06, maxiter: Annotated[int, Parameter(show_default=True, group='Clustering Options')] = 1000, init: Annotated[str, Parameter(show_default=True, group='Clustering Options')] = None, metric: Annotated[DistanceMetrics, Parameter(show_default=True, group='Clustering Options')] = DistanceMetrics.euclidean, pca: Annotated[bool, Parameter(--pca, show_default=True, group='Clustering Options')] = False, out_folder: Annotated[str, Parameter(group='Essential Files Options')] = './fuzzy_results/', processes: Annotated[int, Parameter(show_default=True, group='Computational Options')] = 1, parallelplot: Annotated[bool, Parameter(show_default=True, group='Visualization Options')] = False, radarplot: Annotated[bool, Parameter(show_default=True, group='Visualization Options')] = True, cmap: Annotated[str, Parameter(show_default=True, group='Visualization Options')] = 'magma', 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) ``` Wrap Fuzzy C-Means clustering over k=2 to k. FuzzyClustering runs the analysis for each cluster count up to --k and writes evaluation metrics plus summary barplots and parallel plots. > **Notes** > > **Evaluation metrics** > > The fuzzy partition coefficient (FPC) is defined between 0 and 1, with 1 > the better score. It represents how well the data are described by the > clustering model, so a higher FPC is a better fit. On real-world data, > local maxima can also be interpreted as an optimal solution [1], [5]. > > The Silhouette Coefficient evaluates cluster definition. The score is > bounded from -1 to 1, with 1 the perfect score. A higher Silhouette > Coefficient relates to better-defined clusters. It tends to be higher for > clusters generated from density-based methods [2]. > > The Calinski-Harabasz Index (Variance Ratio Criterion) can be used when no > known labels are available. It represents the density and separation of > clusters, and also tends to be higher for density-based methods. A higher > index relates to better-defined clusters. > > The Davies-Bouldin Index is reported for all cluster models. A lower DBI > relates to better cluster separation. It measures similarity between > clusters from quantities and features of the dataset, tends to be higher > for convex clusters, and uses centroid distance, so the distance metric > is limited to Euclidean space. > > Within-cluster sum of squared error (WSS) is the average distance from > each point to its cluster centroid. Combined with the elbow method, WSS > helps determine the optimal k [3], [4]. > > GAP statistics are based on WSS. They compute the difference in cluster > compactness between the actual data and simulated data with a null > distribution. The optimal k is identified by a maximized GAP statistic > (local maxima can also suggest possible solutions). > > **Fuzziness and initialization** > > The --m parameter defines the degree of fuzziness of the resulting > membership matrix. Using --m 1 returns crisp clusters, whereas --m > 1 > returns increasingly fuzzy clusters. The c-partitioned matrix can be > pre-initialized from previous membership matrices. Specify a folder > containing a membership matrix for each k (if clustering up to k=10, a > matrix is needed for each of them) using this name convention: > > ```text > [init_folder] > |-- cluster_membership_1.npy > |-- cluster_membership_2.npy > |-- [...] > └-- cluster_membership_{k}.npy > ``` > > **Output folder structure** > > The script creates a default output structure in the destination specified > by --out-folder: > > ```text > [out_folder] > |-- CENTROIDS > | |-- clusters_centroids_2.xlsx > | |-- [...] > | └-- clusters_centroids_{k}.xlsx > |-- MEMBERSHIP_DF > | |-- clusters_membership_2.xlsx > | |-- [...] > | └-- clusters_membership_{k}.xlsx > |-- MEMBERSHIP_MAT (in .npy format) > |-- METRICS > | |-- chi.png > | |-- [...] > | └-- wss.png > |-- PARALLEL_PLOTS (optional) > | |-- parallel_plot_2clusters.png > | |-- [...] > | |-- parallel_plot_{k}clusters.png > |-- PCA (optional) > | |-- transformed_data.xlsx > | |-- variance_explained.xlsx > | └-- pca_model.joblib > |-- RADAR_PLOTS (optional) > | |-- radar_plot_2clusters.png > | |-- [...] > | |-- radar_plot_{k}clusters.png > |-- validation_indices.xlsx > └-- viz_multiple_cluster_nb.png > ``` > **References** > > [1] [scikit-fuzzy c-means > example](https://pythonhosted.org/scikit-fuzzy/auto_examples/plot_cmeans.html) > > [2] [scikit-learn clustering performance > evaluation](https://scikit-learn.org/stable/modules/clustering.html#clustering-performance-evaluation) > > [3] [Selecting the optimal number of > clusters](https://towardsdatascience.com/cheat-sheet-to-implementing-7-methods-for-selecting-optimal-number-of-clusters-in-python-898241e1d6ad) > > [4] [How to determine the right number of > clusters](https://towardsdatascience.com/how-to-determine-the-right-number-of-clusters-with-code-d58de36368b1) > > [5] [scikit-fuzzy GitHub > repository](https://github.com/scikit-fuzzy/scikit-fuzzy) **Parameters** - `in_dataset` (`str`) — Input dataset. - `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. - `k` (`int`) (default: `10`) — Maximum k number of clusters to fit a model for. The script iterates until k is met. Defaults to 10. - `m` (`float`) (default: `2`) — Exponentiation value to apply on the membership function. Determines the degree of fuzziness of the membership matrix. Defaults to 2. - `error` (`float`) (default: `1e-06`) — Error threshold for convergence stopping criterion. Defaults to 1e-6. - `maxiter` (`int`) (default: `1000`) — Maximum number of iterations to perform. Defaults to 1000. - `init` (`str`) (default: `None`) — Initial fuzzy c-partitioned matrix. Defaults to None. - `metric` (`DistanceMetrics`) (default: `DistanceMetrics.euclidean`) — Metric to use to compute distance between original points and cluster centroids. Defaults to euclidean. - `pca` (`bool`) (default: `False`) — If set, will perform PCA decomposition to 2 components before clustering. Defaults to False. - `out_folder` (`str`) (default: `'./fuzzy_results/'`) — Path of the folder in which the results will be written. If not specified, current folder and default name will be used. Defaults to ``./fuzzy_results/``. - `processes` (`int`) (default: `1`) — Number of processes to launch in parallel. Defaults to 1. - `parallelplot` (`bool`) (default: `False`) — If true, will output a parallel plot for each cluster solution. Defaults to False. - `radarplot` (`bool`) (default: `True`) — If true, will output a radar plot for each cluster solution. Defaults to True. - `cmap` (`str`) (default: `'magma'`) — Colormap to use for plotting. Defaults to ``magma``. See https://matplotlib.org/stable/tutorials/colors/colormaps.html. - `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 FuzzyClustering --in-dataset dataset.csv --id-column ID --desc-columns 1 --k 10 --m 2 --error 1e-6 --maxiter 1000 --init init_folder --metric euclidean --pca --out-folder ./fuzzy_results/ --processes 4 --verbose ``` [View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/cli/FuzzyClustering.py#L36-L586)