# neurostatx.network.utils

*module*

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

## neurostatx.network.utils.construct_attributes_dict

*function*

```python
def construct_attributes_dict(df, labels, id_column)
```

Build a node-attribute dictionary from selected DataFrame columns.

**Parameters**

- `df` (`DataFrame`) — Table of node attributes.
- `labels` (`list`) — Column names to store as node attributes.
- `id_column` (`str`) — Column used as the node identifier.

**Returns**

- `attributes_dict` (`dict`) — Mapping of node ID to attribute dictionary.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.network.utils import construct_attributes_dict
>>> df = pd.DataFrame({"id": ["s1", "s2"], "age": [20, 30]})
>>> construct_attributes_dict(df, ["age"], "id")["s1"]["age"]
20
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/network/utils.py#L101-L140)

## neurostatx.network.utils.extract_subject_percentile

*function*

```python
def extract_subject_percentile(mat, percentile)
```

Label subjects whose membership delta exceeds a percentile.

**Parameters**

- `mat` (`array`) — Fuzzy membership matrix of shape (n_clusters, n_samples).
- `percentile` (`float`) — Percentile of the first-minus-second membership gap.

**Returns**

- `label_dict` (`dict`) — Mapping of cluster keys to arrays of cluster index or 0.

**Examples**

```pycon
>>> import numpy as np
>>> from neurostatx.network.utils import extract_subject_percentile
>>> mat = np.array([[0.9, 0.2], [0.1, 0.8]])
>>> labels = extract_subject_percentile(mat, 50)
>>> sorted(labels)
['c1', 'c2']
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/network/utils.py#L60-L98)

## neurostatx.network.utils.get_nodes_and_edges

*function*

```python
def get_nodes_and_edges(df, edge_attr='membership')
```

Build an edgelist from a subject-by-cluster membership table.

**Parameters**

- `df` (`DataFrame`) — Table whose first column is subject IDs and remaining columns are cluster memberships.
- `edge_attr` (`str`) (default: `'membership'`) — Name of the weight column in the returned edgelist. Defaults to ``"membership"``.

**Returns**

- `edges` (`DataFrame`) — Edgelist with ``node1``, ``node2``, and ``edge_attr``.
- `subject_list` (`Series`) — Subject identifiers from the first column.
- `center_list` (`list`) — Cluster-centroid labels (``c1``, ``c2``, ...).

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.network.utils import get_nodes_and_edges
>>> df = pd.DataFrame({"id": ["s1", "s2"], "c1": [0.8, 0.2],
...                    "c2": [0.2, 0.8]})
>>> edges, subjects, centers = get_nodes_and_edges(df)
>>> list(centers)
['c1', 'c2']
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/network/utils.py#L7-L57)