# neurostatx.io.loader

*module*

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

## neurostatx.io.loader.DatasetLoader

*class*

```python
class DatasetLoader
```

Load, reshape, and persist tabular datasets.

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L58-L434)

### neurostatx.io.loader.DatasetLoader.data

*attribute* · *instance attribute*

```python
data = None
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L62-L62)

### neurostatx.io.loader.DatasetLoader.nb_subjects

*attribute* · *instance attribute*

```python
nb_subjects = None
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L63-L63)

### neurostatx.io.loader.DatasetLoader.nb_variables

*attribute* · *instance attribute*

```python
nb_variables = None
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L64-L64)

### neurostatx.io.loader.DatasetLoader.custom_function

*method*

```python
def custom_function(func, **kwargs)
```

Apply ``func`` to the loaded DataFrame.

**Parameters**

- `func` (`callable`) — Function called as ``func(data, **kwargs)``.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to ``func``.

**Returns**

- (`result`) — Return value of ``func``.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2]], columns=["a", "b"])
>>> loader.custom_function(lambda df: df.shape)
(1, 2)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L407-L434)

### neurostatx.io.loader.DatasetLoader.drop_columns

*method*

```python
def drop_columns(columns)
```

Drop columns by integer index or name.

**Parameters**

- `columns` (`list`) — Column indices or names to drop.

**Returns**

- `self` (`DatasetLoader`) — Loader with the specified columns removed.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2], [3, 4]],
...                                      columns=["id", "x"])
>>> loader.drop_columns(["id"]).get_data().columns.tolist()
['x']
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L173-L206)

### neurostatx.io.loader.DatasetLoader.get_data

*method*

```python
def get_data()
```

Return the loaded DataFrame.

**Returns**

- `data` (`pandas.DataFrame`) — The loaded data.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> DatasetLoader().import_data([[1, 2]]).get_data().shape
(1, 2)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L356-L373)

### neurostatx.io.loader.DatasetLoader.get_descriptive_columns

*method*

```python
def get_descriptive_columns(columns)
```

Return selected descriptive columns by integer index.

**Parameters**

- `columns` (`list`) — Integer column indices to extract.

**Returns**

- `data` (`pandas.DataFrame`) — DataFrame containing the selected columns.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2], [3, 4]],
...                                      columns=["id", "x"])
>>> loader.get_descriptive_columns([0]).columns.tolist()
['id']
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L144-L171)

### neurostatx.io.loader.DatasetLoader.get_metadata

*method*

```python
def get_metadata()
```

Return the number of rows and columns.

**Returns**

- `metadata` (`dict`) — Mapping with ``nb_subjects`` and ``nb_variables``.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2], [3, 4]])
>>> loader.get_metadata()["nb_subjects"]
2
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L333-L354)

### neurostatx.io.loader.DatasetLoader.import_data

*method*

```python
def import_data(data, columns=None, index=None, **kwargs)
```

Import data from a DataFrame, mapping, or array-like object.

**Parameters**

- `data` (`pandas.DataFrame or array - like`) — Data to import.
- `columns` (`list`) (default: `None`) — Column names to use. If None, pandas default names are kept.
- `index` (`array - like`) (default: `None`) — Index used when constructing a DataFrame from array-like data.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to ``pandas.DataFrame.from_dict``.

**Returns**

- `self` (`DatasetLoader`) — Loader with the imported data.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2], [3, 4]],
...                                      columns=["a", "b"])
>>> loader.get_data().shape
(2, 2)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L105-L142)

### neurostatx.io.loader.DatasetLoader.join

*method*

```python
def join(df, left=True, **kwargs)
```

Concatenate ``df`` with the loaded table along columns.

**Parameters**

- `df` (`pandas.DataFrame`) — DataFrame or Series to concatenate.
- `left` (`bool`) (default: `True`) — If True, ``df`` is placed on the left. Defaults to True.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to ``pandas.concat``.

**Returns**

- `self` (`DatasetLoader`) — Loader with the concatenated table.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1], [2]], columns=["a"])
>>> extra = pd.DataFrame({"b": [3, 4]})
>>> loader.join(extra, left=False).get_data().columns.tolist()
['a', 'b']
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L208-L245)

### neurostatx.io.loader.DatasetLoader.load_data

*method*

```python
def load_data(file, **kwargs)
```

Load tabular data from ``.txt``, ``.csv``, ``.tsv``, or ``.xlsx``.

**Parameters**

- `file` (`str`) — Input file to load.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to pandas.

**Returns**

- `self` (`DatasetLoader`) — Loader with ``data`` populated.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> DatasetLoader().load_data("data.csv")
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L66-L103)

### neurostatx.io.loader.DatasetLoader.reset_index

*method*

```python
def reset_index(**kwargs)
```

Reset the DataFrame index in place.

**Parameters**

- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to ``pandas.DataFrame.reset_index``.

**Returns**

- `self` (`DatasetLoader`) — Loader with a reset index.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1], [2]], columns=["a"],
...                                      index=[10, 20])
>>> loader.reset_index().get_data().index.tolist()
[0, 1]
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L247-L273)

### neurostatx.io.loader.DatasetLoader.save_data

*method*

```python
def save_data(file, **kwargs)
```

Save the loaded table to ``.csv``, ``.tsv``, ``.txt``, or ``.xlsx``.

**Parameters**

- `file` (`str`) — Output file name.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to pandas.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2]], columns=["a", "b"])
>>> loader.save_data("out.csv", index=False)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L375-L405)

### neurostatx.io.loader.DatasetLoader.set_type

*method*

```python
def set_type(dtype, columns=None)
```

Cast selected columns, or the full table, to ``dtype``.

**Parameters**

- `dtype` (`str`) — Target dtype.
- `columns` (`list`) (default: `None`) — Integer column indices to convert. If None, all columns are converted.

**Returns**

- `self` (`DatasetLoader`) — Loader with updated dtypes.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2], [3, 4]],
...                                      columns=["a", "b"])
>>> loader.set_type("float").get_data()["a"].dtype.kind
'f'
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L275-L308)

### neurostatx.io.loader.DatasetLoader.transpose

*method*

```python
def transpose()
```

Transpose the loaded table.

**Returns**

- `self` (`DatasetLoader`) — Loader with transposed data.

**Examples**

```pycon
>>> from neurostatx.io.loader import DatasetLoader
>>> loader = DatasetLoader().import_data([[1, 2], [3, 4]],
...                                      columns=["a", "b"])
>>> loader.transpose().get_data().shape
(2, 2)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L310-L331)

## neurostatx.io.loader.GraphLoader

*class*

```python
class GraphLoader
```

Load, build, annotate, and visualize NetworkX graphs.

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L437-L966)

### neurostatx.io.loader.GraphLoader.graph

*attribute* · *instance attribute*

```python
graph = None
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L441-L441)

### neurostatx.io.loader.GraphLoader.nb_edges

*attribute* · *instance attribute*

```python
nb_edges = None
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L443-L443)

### neurostatx.io.loader.GraphLoader.nb_nodes

*attribute* · *instance attribute*

```python
nb_nodes = None
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L442-L442)

### neurostatx.io.loader.GraphLoader.add_edge_attribute

*method*

```python
def add_edge_attribute(attributes)
```

Set edge attributes from a nested dictionary.

**Parameters**

- `attributes` (`dict`) — Mapping of edge to attribute dictionary.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"]})
>>> g = GraphLoader().build_graph(edges)
>>> g.add_edge_attribute({("s1", "c1"): {"membership": 0.8}})
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L579-L598)

### neurostatx.io.loader.GraphLoader.add_node_attribute

*method*

```python
def add_node_attribute(attributes)
```

Set node attributes from a nested dictionary.

**Parameters**

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

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"]})
>>> g = GraphLoader().build_graph(edges)
>>> g.add_node_attribute({"s1": {"age": 20}})
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L558-L577)

### neurostatx.io.loader.GraphLoader.build_graph

*method*

```python
def build_graph(data, source='source', target='target', **kwargs)
```

Build a graph from an edgelist DataFrame.

**Parameters**

- `data` (`pandas.DataFrame`) — Edgelist used to construct the graph.
- `source` (`str`) (default: `'source'`) — Source-node column name. Defaults to ``"source"``.
- `target` (`str`) (default: `'target'`) — Target-node column name. Defaults to ``"target"``.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to ``networkx.from_pandas_edgelist``.

**Returns**

- `self` (`GraphLoader`) — Loader with the constructed graph.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"],
...                       "membership": [0.8]})
>>> GraphLoader().build_graph(edges, edge_attr="membership").nb_nodes
2
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L479-L517)

### neurostatx.io.loader.GraphLoader.custom_function

*method*

```python
def custom_function(func, **kwargs)
```

Apply ``func`` to the loaded graph.

**Parameters**

- `func` (`callable`) — Function called as ``func(graph, **kwargs)``.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to ``func``.

**Returns**

- (`result`) — Return value of ``func``.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"]})
>>> GraphLoader().build_graph(edges).custom_function(
...     lambda g: g.number_of_nodes())
2
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L937-L966)

### neurostatx.io.loader.GraphLoader.fetch_attributes_df

*method*

```python
def fetch_attributes_df(attributes=None)
```

Return subject-node attributes as a DatasetLoader.

**Parameters**

- `attributes` (`list`) (default: `None`) — Attribute names to fetch. If None, all attributes except ``label`` are returned.

**Returns**

- `data` (`DatasetLoader`) — Loader containing subject-node attributes.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"]})
>>> g = GraphLoader().build_graph(edges)
>>> g.add_node_attribute({"s1": {"age": 20}})
>>> g.fetch_attributes_df(["age"]).get_data().loc["s1", "age"]
20
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L600-L643)

### neurostatx.io.loader.GraphLoader.fetch_edge_data

*method*

```python
def fetch_edge_data(weight='membership')
```

Return subject-to-cluster edge weights as a DatasetLoader.

**Parameters**

- `weight` (`str`) (default: `'membership'`) — Edge attribute used as weights. Defaults to ``"membership"``.

**Returns**

- `data` (`DatasetLoader`) — Loader containing one column per cluster.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"],
...                       "membership": [0.8]})
>>> g = GraphLoader().build_graph(edges, edge_attr="membership")
>>> g.fetch_edge_data().get_data().shape[1]
1
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L645-L693)

### neurostatx.io.loader.GraphLoader.get_graph

*method*

```python
def get_graph()
```

Return the loaded NetworkX graph.

**Returns**

- `graph` (`networkx.Graph`) — The loaded graph.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"]})
>>> GraphLoader().build_graph(edges).get_graph().number_of_nodes()
2
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L886-L905)

### neurostatx.io.loader.GraphLoader.get_metadata

*method*

```python
def get_metadata()
```

Return the number of nodes and edges.

**Returns**

- `metadata` (`dict`) — Mapping with ``nb_nodes`` and ``nb_edges``.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"]})
>>> GraphLoader().build_graph(edges).get_metadata()["nb_nodes"]
2
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L862-L884)

### neurostatx.io.loader.GraphLoader.layout

*method*

```python
def layout(layout=NetworkLayout.Spring, weight='membership', **kwargs)
```

Compute node positions and store them as a ``pos`` attribute.

**Parameters**

- `layout` (`NetworkLayout`) (default: `NetworkLayout.Spring`) — Layout algorithm to use.
- `weight` (`str`) (default: `'membership'`) — Edge attribute used as layout weights. Defaults to ``"membership"``.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to the NetworkX layout function.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> from neurostatx.network.viz import NetworkLayout
>>> edges = pd.DataFrame({"source": ["s1", "s2"],
...                       "target": ["c1", "c1"],
...                       "membership": [0.8, 0.4]})
>>> g = GraphLoader().build_graph(edges, edge_attr="membership")
>>> g.layout(NetworkLayout.Spring)
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L519-L556)

### neurostatx.io.loader.GraphLoader.load_graph

*method*

```python
def load_graph(file, **kwargs)
```

Load a graph from ``.gml``, ``.graphml``, or ``.gexf``.

**Parameters**

- `file` (`str`) — Input file to load.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to NetworkX.

**Returns**

- `self` (`GraphLoader`) — Loader with ``graph`` populated.

**Examples**

```pycon
>>> from neurostatx.io.loader import GraphLoader
>>> GraphLoader().load_graph("network.gml")
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L445-L477)

### neurostatx.io.loader.GraphLoader.save_graph

*method*

```python
def save_graph(file, **kwargs)
```

Save the graph to ``.gml``, ``.graphml``, or ``.gexf``.

**Parameters**

- `file` (`str`) — Output file to save.
- `**kwargs` (default: `{}`) — Additional keyword arguments forwarded to NetworkX.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"]})
>>> GraphLoader().build_graph(edges).save_graph("network.gml")
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L907-L935)

### neurostatx.io.loader.GraphLoader.visualize

*method*

```python
def visualize(output, weight='weight', centroids_labelling=True, subjects_labelling=False, centroid_node_shape=500, centroid_alpha=1, centroid_node_color='white', centroid_edge_color='black', subject_node_shape=5, subject_alpha=0.3, subject_node_color='black', subject_edge_color=None, edge_width_multiplier=1, colormap='plasma', title='Graph Network', legend_title='Membership values')
```

Draw the graph network and write it to ``output``.

**Parameters**

- `output` (`str`) — Output file name.
- `weight` (`str`) (default: `'weight'`) — Edge attribute used as edge weights. Defaults to ``"weight"``.
- `centroids_labelling` (`bool`) (default: `True`) — If True, label centroid nodes. Defaults to True.
- `subjects_labelling` (`bool`) (default: `False`) — If True, label subject nodes. Defaults to False.
- `centroid_node_shape` (`int`) (default: `500`) — Size of centroid nodes. Defaults to 500.
- `centroid_alpha` (`float`) (default: `1`) — Alpha of centroid nodes. Defaults to 1.
- `centroid_node_color` (`str`) (default: `'white'`) — Face color of centroid nodes. Defaults to ``"white"``.
- `centroid_edge_color` (`str`) (default: `'black'`) — Edge color of centroid nodes. Defaults to ``"black"``.
- `subject_node_shape` (`int`) (default: `5`) — Size of subject nodes. Defaults to 5.
- `subject_alpha` (`float`) (default: `0.3`) — Alpha of subject nodes. Defaults to 0.3.
- `subject_node_color` (`str`) (default: `'black'`) — Face color of subject nodes. Defaults to ``"black"``.
- `subject_edge_color` (`str`) (default: `None`) — Edge color of subject nodes. Defaults to None.
- `edge_width_multiplier` (`float`) (default: `1`) — Scale factor applied to edge widths. Defaults to 1.
- `colormap` (`str`) (default: `'plasma'`) — Matplotlib colormap name for edges. Defaults to ``"plasma"``.
- `title` (`str`) (default: `'Graph Network'`) — Title of the plot. Defaults to ``"Graph Network"``.
- `legend_title` (`str`) (default: `'Membership values'`) — Title of the colorbar. Defaults to ``"Membership values"``.

**Examples**

```pycon
>>> import pandas as pd
>>> from neurostatx.io.loader import GraphLoader
>>> from neurostatx.network.viz import NetworkLayout
>>> edges = pd.DataFrame({"source": ["s1"], "target": ["c1"],
...                       "weight": [0.8]})
>>> g = GraphLoader().build_graph(edges, edge_attr="weight")
>>> g.layout(NetworkLayout.Spring, weight="weight")
>>> g.visualize("graph.png")
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L695-L860)

## neurostatx.io.loader.filter_node_centroids

*function*

```python
def filter_node_centroids(n)
```

Return True if ``n`` is a cluster-centroid node label.

**Parameters**

- `n` (`str`) — Node label.

**Returns**

- `match` (`bool`) — True when the label contains ``"c"``.

**Examples**

```pycon
>>> from neurostatx.io.loader import filter_node_centroids
>>> filter_node_centroids("c1")
True
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L14-L33)

## neurostatx.io.loader.filter_node_subjects

*function*

```python
def filter_node_subjects(n)
```

Return True if ``n`` is a subject node label.

**Parameters**

- `n` (`str`) — Node label.

**Returns**

- `match` (`bool`) — True when the label does not contain ``"c"``.

**Examples**

```pycon
>>> from neurostatx.io.loader import filter_node_subjects
>>> filter_node_subjects("s01")
True
```

[View source](https://github.com/gagnonanthony/NeuroStatX/blob/main/neurostatx/io/loader.py#L36-L55)