# neurostatx.cli.AverageWeightedPath

*module*

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

## neurostatx.cli.AverageWeightedPath.app

*attribute* · *module attribute*

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

Cyclopts application for the AverageWeightedPath command-line tool.

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

## neurostatx.cli.AverageWeightedPath.AverageWeightedPath

*function*

```python
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][neurostatx.cli.AddNodesAttributes.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](https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.shortest_paths.generic.average_shortest_path_length.html#networkx.algorithms.shortest_paths.generic.average_shortest_path_length)

**Parameters**

- `in_graph` (`str`) — Input graph file (.gml).
- `label_name` (`List[str]`) — Label(s) name(s) to select group(s) of nodes. Can be multiple.
- `out_folder` (`str`) (default: `None`) — Output folder where files will be exported. Defaults to None.
- `cohort` (`int`) (default: `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`) (default: `1000`) — Number of iterations to perform to generate the null distribution. Defaults to 1000.
- `weight` (`str`) (default: `'membership'`) — Name of the edge attributes to use during the weighted path computation. Defaults to ``membership``.
- `method` (`PathLengthsMethods`) (default: `PathLengthsMethods.Dijkstra`) — Method to use for the estimation of the weighted path. Defaults to Dijkstra.
- `distribution` (`str`) (default: `None`) — Pre-computed null distribution. Needs to be an .xlsx file containing label name as --label-name. Defaults to None.
- `processes` (`int`) (default: `1`) — Number of processes to use to compute the null distribution. Defaults to 1.
- `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
AverageWeightedPath --in-graph ./graph.gml --label-name Group1
--label-name Group2 --out-folder ./results --iterations 5000
--weight membership --method Dijkstra
```

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