neurostatx.cli.AverageWeightedPath

Attributes

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

Functions

Name	Description
AverageWeightedPath	Compare a group's average weighted path (AWP) against a null

appattributemodule attribute#

View source

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

Cyclopts application for the AverageWeightedPath command-line tool.

AverageWeightedPathfunction#

View source

def AverageWeightedPath(in_graph: Annotated[str, Parameter(show_default=False, group='Essential Files Options')], label_name: Annotated[List[str], Parameter(show_default=False, group='Essential Files Options')], out_folder: Annotated[str, Parameter(show_default=False, group='Essential Files Options')] = None, cohort: Annotated[int, Parameter(show_default=False, group='Essential Files Options')] = None, iterations: Annotated[int, Parameter(show_default=True, group='Computational Options')] = 1000, weight: Annotated[str, Parameter(show_default=True, group='Computational Options')] = 'membership', method: Annotated[PathLengthsMethods, Parameter(show_choices=True, show_default=True, group='Computational Options')] = PathLengthsMethods.Dijkstra, distribution: Annotated[str, Parameter(show_choices=False, show_default=True, group='Computational Options')] = None, processes: Annotated[int, Parameter(show_default=True, group='Computational Options')] = 1, 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 a group’s average weighted path (AWP) against a null distribution.

AverageWeightedPath computes the average weighted shortest path length for a group of nodes, compares it to a null distribution generated by randomly selecting the same number of nodes, and reports a p-value for the comparison.

Notes

Null distribution

The null distribution is generated by randomly selecting the same number of nodes as the group of interest and computing the average weighted shortest path length. This process is repeated for a number of iterations and the resulting distribution is used to compute the p-value. For large graphs, the null distribution can take a long time to compute. Use –distribution to provide a pre-computed null distribution if this script has already been run for the same number of nodes. Reducing the number of iterations speeds up the process and yields a rough estimate of the p-value.

Cohort selection

When the graph contains data from multiple cohorts, –cohort fetches the specified cohort and filters –label-name. AWP is then computed only on subjects with that label in the specified cohort. The graph must contain a cohort attribute; add it with AddNodesAttributes if needed.

Parallel computation

Multiple CPUs can be used to compute the null distribution via –processes.

Weighted path estimation

Weighted paths can be estimated with Dijkstra (default), Bellman-Ford, or Floyd-Warshall. Floyd-Warshall is not recommended for large graphs. See the NetworkX average_shortest_path_length documentation [1].

References

[1] NetworkX average_shortest_path_length documentation

Parameters

Name	Type	Default	Description
in_graph	str	required	Input graph file (.gml).
label_name	List[str]	required	Label(s) name(s) to select group(s) of nodes. Can be multiple.
out_folder	str	None	Output folder where files will be exported. Defaults to None.
cohort	int	None	Cohort identifier. If your graph contains data from multiple cohorts, you can specify the cohort you want to compute the AWP for. Defaults to None.
iterations	int	1000	Number of iterations to perform to generate the null distribution. Defaults to 1000.
weight	str	'membership'	Name of the edge attributes to use during the weighted path computation. Defaults to membership.
method	PathLengthsMethods	PathLengthsMethods.Dijkstra	Method to use for the estimation of the weighted path. Defaults to Dijkstra.
distribution	str	None	Pre-computed null distribution. Needs to be an .xlsx file containing label name as –label-name. Defaults to None.
processes	int	1	Number of processes to use to compute the null distribution. Defaults to 1.
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

AverageWeightedPath --in-graph ./graph.gml --label-name Group1
--label-name Group2 --out-folder ./results --iterations 5000
--weight membership --method Dijkstra