neurostatx.cli.ComputeGraphNetwork

Attributes

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

Functions

Name	Description
ComputeGraphNetwork	Build an undirected weighted graph from a fuzzy membership matrix.

appattributemodule attribute#

View source

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

Cyclopts application for the ComputeGraphNetwork command-line tool.

ComputeGraphNetworkfunction#

View source

def ComputeGraphNetwork(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')], out_folder: Annotated[str, Parameter(show_default=True, group='Essential Files Options')] = './graph_results/', verbose: Annotated[bool, Parameter(-v, --verbose, group='Optional parameters')] = False, overwrite: Annotated[bool, Parameter(-f, --overwrite, group='Optional parameters')] = False, save_parameters: Annotated[bool, Parameter(-s, --save_parameters, group='Optional parameters')] = False, plot_distribution: Annotated[bool, Parameter(show_default=True, group='Plotting Options')] = False, import_data: Annotated[bool, Parameter(show_default=True, group='Essential Files Options')] = False, layout: Annotated[NetworkLayout, Parameter(show_default=True, show_choices=True, group='Layout Options')] = NetworkLayout.Spring, method: Annotated[str, Parameter(show_default=True, group='Layout Options')] = 'force', seed: Annotated[int, Parameter(show_default=True, group='Layout Options')] = 42, weight: Annotated[str, Parameter(show_default=True, group='Layout Options')] = 'membership')

Build an undirected weighted graph from a fuzzy membership matrix.

ComputeGraphNetwork is designed to work seamlessly with FuzzyClustering. Mapping membership matrices to a graph allows later use of graph-theory statistics such as shortest path and betweenness centrality.

Notes

Layout algorithms

Node positions are determined from their connections to other nodes (and the weight of those connections). Those connections are also called edges and carry a weight in a weighted graph. Available layout algorithms are:

• Kamada-Kawai uses the Kamada-Kawai path-length cost function. It is not optimal for large networks because it is computationally intensive.
• Spectral layout determines position using the eigenvectors of the graph Laplacian.
• Spring layout uses the Fruchterman-Reingold force-directed algorithm. It is suitable for large networks with a high number of nodes and is the default method.

For large graphs (~10 000 nodes), a spring layout run can take about 5 minutes depending on hardware. Layout details are documented in the NetworkX drawing reference [2].

Importing data

If –import-data is set, descriptive data are stored as node attributes in the .gml file. This is useful for later visualization or statistical analysis (see AverageWeightedPath or PartialLeastSquareRegression) and reduces the chance of subject mismatch.

The concept of this script was initially proposed in [1].

References

[1] Ariza-Jiménez, L., Villa, L. F., & Quintero, O. L. (2019). Memberships Networks forHigh-Dimensional Fuzzy Clustering Visualization

[2] NetworkX drawing documentation

Parameters

Name	Type	Default	Description
in_dataset	str	required	Input dataset containing membership values for each cluster.
id_column	str	required	Name of the column containing the subject’s ID tag. Required for proper handling of IDs.
desc_columns	int	required	Number of descriptive columns at the beginning of the dataset.
out_folder	str	'./graph_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 ./graph_results/.
verbose	bool	False	If true, produce verbose output. Defaults to False.
overwrite	bool	False	If true, force overwriting of existing output files. Defaults to False.
save_parameters	bool	False	If true, save the parameters used in a .txt file. Defaults to False.
plot_distribution	bool	False	If true, will plot the membership distribution and delta. Defaults to False.
import_data	bool	False	If true, will import the data from the input dataset within the graph network file. Defaults to False.
layout	NetworkLayout	NetworkLayout.Spring	Layout algorithm to determine the nodes position. Defaults to Spring.
method	str	'force'	Layout method passed to the NetworkX layout algorithm. Defaults to force.
seed	int	42	Random seed used when computing node positions. Defaults to 42.
weight	str	'membership'	Name of the column containing the edge weight. Defaults to membership.

Examples

ComputeGraphNetwork --in-dataset cluster_membership.xlsx
--id-column subjectkey --desc-columns 1 --out-folder output/