neurostatx.cli.FuzzyClustering

Attributes

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

Functions

Name	Description
FuzzyClustering	Wrap Fuzzy C-Means clustering over k=2 to k.

appattributemodule attribute#

View source

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

Cyclopts application for the FuzzyClustering command-line tool.

FuzzyClusteringfunction#

View source

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:

            [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:

            [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

[2] scikit-learn clustering performance evaluation

[3] Selecting the optimal number of clusters

[4] How to determine the right number of clusters

[5] scikit-fuzzy GitHub repository

Parameters

Name	Type	Default	Description
in_dataset	str	required	Input dataset.
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.
k	int	10	Maximum k number of clusters to fit a model for. The script iterates until k is met. Defaults to 10.
m	float	2	Exponentiation value to apply on the membership function. Determines the degree of fuzziness of the membership matrix. Defaults to 2.
error	float	1e-06	Error threshold for convergence stopping criterion. Defaults to 1e-6.
maxiter	int	1000	Maximum number of iterations to perform. Defaults to 1000.
init	str	None	Initial fuzzy c-partitioned matrix. Defaults to None.
metric	DistanceMetrics	DistanceMetrics.euclidean	Metric to use to compute distance between original points and cluster centroids. Defaults to euclidean.
pca	bool	False	If set, will perform PCA decomposition to 2 components before clustering. Defaults to False.
out_folder	str	'./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	1	Number of processes to launch in parallel. Defaults to 1.
parallelplot	bool	False	If true, will output a parallel plot for each cluster solution. Defaults to False.
radarplot	bool	True	If true, will output a radar plot for each cluster solution. Defaults to True.
cmap	str	'magma'	Colormap to use for plotting. Defaults to magma. See https://matplotlib.org/stable/tutorials/colors/colormaps.html.
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

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