neurostatx.io.loader

Classes

Name	Description
DatasetLoader	Load, reshape, and persist tabular datasets.
GraphLoader	Load, build, annotate, and visualize NetworkX graphs.

Functions

Name	Description
filter_node_centroids	Return True if n is a cluster-centroid node label.
filter_node_subjects	Return True if n is a subject node label.

DatasetLoaderclass#

View source

class DatasetLoader()

Load, reshape, and persist tabular datasets.

dataattributeinstance attribute#

View source

data = None

nb_subjectsattributeinstance attribute#

View source

nb_subjects = None

nb_variablesattributeinstance attribute#

View source

nb_variables = None

custom_functionmethod#

View source

def custom_function(func, **kwargs)

Apply func to the loaded DataFrame.

Parameters

Name	Type	Default	Description
func	callable	required	Function called as func(data, **kwargs).
**kwargs		{}	Additional keyword arguments forwarded to func.

Returns

result

Return value of func.

Examples

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

drop_columnsmethod#

View source

def drop_columns(columns)

Drop columns by integer index or name.

Parameters

Name	Type	Description
columns	list	Column indices or names to drop.

Returns

selfDatasetLoader

Loader with the specified columns removed.

Examples

>>> 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']

get_datamethod#

View source

def get_data()

Return the loaded DataFrame.

Returns

datapandas.DataFrame

The loaded data.

Examples

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

get_descriptive_columnsmethod#

View source

def get_descriptive_columns(columns)

Return selected descriptive columns by integer index.

Parameters

Name	Type	Description
columns	list	Integer column indices to extract.

Returns

datapandas.DataFrame

DataFrame containing the selected columns.

Examples

>>> 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']

get_metadatamethod#

View source

def get_metadata()

Return the number of rows and columns.

Returns

metadatadict

Mapping with nb_subjects and nb_variables.

Examples

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

import_datamethod#

View source

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

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

Parameters

Name	Type	Default	Description
data	pandas.DataFrame or array - like	required	Data to import.
columns	list	None	Column names to use. If None, pandas default names are kept.
index	array - like	None	Index used when constructing a DataFrame from array-like data.
**kwargs		{}	Additional keyword arguments forwarded to pandas.DataFrame.from_dict.

Returns

selfDatasetLoader

Loader with the imported data.

Examples

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

joinmethod#

View source

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

Concatenate df with the loaded table along columns.

Parameters

Name	Type	Default	Description
df	pandas.DataFrame	required	DataFrame or Series to concatenate.
left	bool	True	If True, df is placed on the left. Defaults to True.
**kwargs		{}	Additional keyword arguments forwarded to pandas.concat.

Returns

selfDatasetLoader

Loader with the concatenated table.

Examples

>>> 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']

load_datamethod#

View source

def load_data(file, **kwargs)

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

Parameters

Name	Type	Default	Description
file	str	required	Input file to load.
**kwargs		{}	Additional keyword arguments forwarded to pandas.

Returns

selfDatasetLoader

Loader with data populated.

Examples

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

reset_indexmethod#

View source

def reset_index(**kwargs)

Reset the DataFrame index in place.

Parameters

Name	Default	Description
**kwargs	{}	Additional keyword arguments forwarded to pandas.DataFrame.reset_index.

Returns

selfDatasetLoader

Loader with a reset index.

Examples

>>> 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]

save_datamethod#

View source

def save_data(file, **kwargs)

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

Parameters

Name	Type	Default	Description
file	str	required	Output file name.
**kwargs		{}	Additional keyword arguments forwarded to pandas.

Examples

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

set_typemethod#

View source

def set_type(dtype, columns=None)

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

Parameters

Name	Type	Default	Description
dtype	str	required	Target dtype.
columns	list	None	Integer column indices to convert. If None, all columns are converted.

Returns

selfDatasetLoader

Loader with updated dtypes.

Examples

>>> 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'

transposemethod#

View source

def transpose()

Transpose the loaded table.

Returns

selfDatasetLoader

Loader with transposed data.

Examples

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

GraphLoaderclass#

View source

class GraphLoader()

Load, build, annotate, and visualize NetworkX graphs.

graphattributeinstance attribute#

View source

graph = None

nb_edgesattributeinstance attribute#

View source

nb_edges = None

nb_nodesattributeinstance attribute#

View source

nb_nodes = None

add_edge_attributemethod#

View source

def add_edge_attribute(attributes)

Set edge attributes from a nested dictionary.

Parameters

Name	Type	Description
attributes	dict	Mapping of edge to attribute dictionary.

Examples

>>> 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}})

add_node_attributemethod#

View source

def add_node_attribute(attributes)

Set node attributes from a nested dictionary.

Parameters

Name	Type	Description
attributes	dict	Mapping of node to attribute dictionary.

Examples

>>> 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}})

build_graphmethod#

View source

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

Build a graph from an edgelist DataFrame.

Parameters

Name	Type	Default	Description
data	pandas.DataFrame	required	Edgelist used to construct the graph.
source	str	'source'	Source-node column name. Defaults to "source".
target	str	'target'	Target-node column name. Defaults to "target".
**kwargs		{}	Additional keyword arguments forwarded to networkx.from_pandas_edgelist.

Returns

selfGraphLoader

Loader with the constructed graph.

Examples

>>> 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

custom_functionmethod#

View source

def custom_function(func, **kwargs)

Apply func to the loaded graph.

Parameters

Name	Type	Default	Description
func	callable	required	Function called as func(graph, **kwargs).
**kwargs		{}	Additional keyword arguments forwarded to func.

Returns

result

Return value of func.

Examples

>>> 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

fetch_attributes_dfmethod#

View source

def fetch_attributes_df(attributes=None)

Return subject-node attributes as a DatasetLoader.

Parameters

Name	Type	Default	Description
attributes	list	None	Attribute names to fetch. If None, all attributes except label are returned.

Returns

dataDatasetLoader

Loader containing subject-node attributes.

Examples

>>> 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

fetch_edge_datamethod#

View source

def fetch_edge_data(weight='membership')

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

Parameters

Name	Type	Default	Description
weight	str	'membership'	Edge attribute used as weights. Defaults to "membership".

Returns

dataDatasetLoader

Loader containing one column per cluster.

Examples

>>> 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

get_graphmethod#

View source

def get_graph()

Return the loaded NetworkX graph.

Returns

graphnetworkx.Graph

The loaded graph.

Examples

>>> 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

get_metadatamethod#

View source

def get_metadata()

Return the number of nodes and edges.

Returns

metadatadict

Mapping with nb_nodes and nb_edges.

Examples

>>> 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

layoutmethod#

View source

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

Compute node positions and store them as a pos attribute.

Parameters

Name	Type	Default	Description
layout	NetworkLayout	NetworkLayout.Spring	Layout algorithm to use.
weight	str	'membership'	Edge attribute used as layout weights. Defaults to "membership".
**kwargs		{}	Additional keyword arguments forwarded to the NetworkX layout function.

Examples

>>> 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)

load_graphmethod#

View source

def load_graph(file, **kwargs)

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

Parameters

Name	Type	Default	Description
file	str	required	Input file to load.
**kwargs		{}	Additional keyword arguments forwarded to NetworkX.

Returns

selfGraphLoader

Loader with graph populated.

Examples

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

save_graphmethod#

View source

def save_graph(file, **kwargs)

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

Parameters

Name	Type	Default	Description
file	str	required	Output file to save.
**kwargs		{}	Additional keyword arguments forwarded to NetworkX.

Examples

>>> 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")

visualizemethod#

View source

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

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

Examples

>>> 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")

filter_node_centroidsfunction#

View source

def filter_node_centroids(n)

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

Parameters

Name	Type	Description
n	str	Node label.

Returns

matchbool

True when the label contains "c".

Examples

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

filter_node_subjectsfunction#

View source

def filter_node_subjects(n)

Return True if n is a subject node label.

Parameters

Name	Type	Description
n	str	Node label.

Returns

matchbool

True when the label does not contain "c".

Examples

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