factory¶

Builds SpatioTemporalGraph objects from correlation matrix sequences and area definitions.

Defines helpers to create spatio-temporal graphs.

fstg_toolkit.factory.graph_from_corr_matrix(matrix: array, areas_desc: DataFrame, corr_thr: float = 0.4, abs_thr: bool = True, area_col_name: str = 'Name_Area', region_col_name: str = 'Name_Region') → Graph[source]¶

Compute a symmetric graph from a symmetric correlation matrix.

Parameters:

matrix (numpy.array) – The symmetric correlation matrix.
areas_desc (pandas.DataFrame) – The dataframe listing the areas.
corr_thr (float, optional) – The threshold above which correlations are taken into account (default is 0.4).
abs_thr (bool, optional) – flag to use the threshold on absolute correlations (default is true).
area_col_name (str, optional) – The name of the column of areas’ names (default is ‘Name_Area’).
region_col_name (str, optional) – The name of the column of regions’ names (default is ‘Name_Region’).

Returns:

A non-directed graph with related area and region carried in node’s data and correlation carried in edge’s data.

Return type:

networkx.Graph

Example

One needs a symmetric matrix of correlation and a dataframe of areas with indices starting at 1 and names of areas and regions, as below. >>> M = np.array([ … [ 1, 0.12873788, -0.41853318], … [ 0.12873788, 1, 0.75087697], … [-0.41853318, 0.75087697, 1]]) >>> areas = pd.DataFrame({‘Id’: [1, 2, 3], ‘Name_Area’: [‘A1’, ‘A2’, ‘A3’], ‘Name_Region’: [‘R1’, ‘R1’, ‘R2’]}) >>> areas.set_index(‘Id’, inplace=True)

The matrix needs to be symmetric because the function outputs a non-directed graph, so it cannot handle properly asymmetric matrices. Also, its diagonal should be filled by ones, but it is not mandatory, as the function does not read it.

Finally, with the previous input (and defaults optional parameters), the function outputs the following non-directed graph. >>> G = graph_from_corr_matrix(M, areas) >>> G.nodes(data=True) NodeDataView({1: {‘area’: ‘A1’, ‘region’: ‘R1’}, 2: {‘area’: ‘A2’, ‘region’: ‘R1’}, 3: {‘area’: ‘A3’, ‘region’: ‘R2’}}) >>> G.edges(data=True) EdgeDataView([(1, 3, {‘correlation’: -0.41853318}), (2, 3, {‘correlation’: 0.75087697})])

fstg_toolkit.factory.networks_from_connect_graph(graph: Graph, regions: list[str]) → Graph[source]¶

Compute a graph of networks grouped by regions from an areas connectivity graph.

The networks are groups of areas that forms connected components within a region.

Parameters:

graph (networkx.Graph) – The areas connectivity graph.
regions (list[str]) – A list of regions’ names.

Returns:

A graph of areas in networks.

Return type:

networkx.Graph

Example

Let be a connectivity graph between areas, like described below. >>> G = nx.Graph() >>> G.add_nodes_from([ … (1, {‘area’: ‘A1’, ‘region’: ‘R1’}), … (2, {‘area’: ‘A2’, ‘region’: ‘R1’}), … (3, {‘area’: ‘A3’, ‘region’: ‘R2’})]) >>> G.add_edges_from([ … (1, 3, {‘correlation’: -0.41853318}), … (2, 3, {‘correlation’: 0.75087697})])

The graph of networks of connected areas for both regions is built using the following. >>> netG = networks_from_connect_graph(G, [‘R1’, ‘R2’]) >>> netG.nodes(data=True) NodeDataView({1: {‘areas’: {1}, ‘region’: ‘R1’, ‘internal_strength’: 1, ‘efficiency’: 1},

2: {‘areas’: {2}, ‘region’: ‘R1’, ‘internal_strength’: 1, ‘efficiency’: 1}, 3: {‘areas’: {3}, ‘region’: ‘R2’, ‘internal_strength’: 1, ‘efficiency’: 1}})

>>> netG.edges(data=True)
EdgeDataView([(1, 3, {'correlation': -0.41853318}), (2, 3, {'correlation': 0.75087697})])

fstg_toolkit.factory.spatio_temporal_graph_from_corr_matrices(corr_matrices: Iterable[ndarray], areas_desc: DataFrame, region_col_name: str = 'Name_Region', **corr_mat_kwd) → SpatioTemporalGraph[source]¶

Build a spatio-temporal graph a set of temporal correlation matrices and areas description.

Parameters:

corr_matrices (numpy.array) – The successive correlation matrices (one per time point).
areas_desc (pandas.DataFrame) – The description of areas to consider.
region_col_name (str, optional) – The name of the column in areas_desc that gives the associated region name (default is ‘Name_Region’).
corr_mat_kwd (dict, optional) – The options for the construction of a connectivity graph from a correlation matrix. For more information, see graph_from_corr_matrix().

Returns:

A structure that hold a spatio-temporal graph of functional connectivity data.

Return type:

SpatioTemporalGraph

Example

>>> M1 = np.array([
...     [          1,  0.12873788, -0.41853318],
...     [ 0.12873788,           1,  0.75087697],
...     [-0.41853318,  0.75087697,           1]])
>>> M2 = np.array([
...     [          1,  0.52873788, -0.41853318],
...     [ 0.52873788,           1,  0.75087697],
...     [-0.41853318,  0.75087697,           1]])
>>> areas = pd.DataFrame({'Id': [1, 2, 3], 'Name_Area': ['A1', 'A2', 'A3'], 'Name_Region': ['R1', 'R1', 'R2']})
>>> areas.set_index('Id', inplace=True)
>>> result = spatio_temporal_graph_from_corr_matrices((M1, M2), areas)
>>> result.nodes(data=True)
NodeDataView({1: {'t': 0, 'areas': {1}, 'region': 'R1', 'internal_strength': 1, 'efficiency': 1},
              2: {'t': 0, 'areas': {2}, 'region': 'R1', 'internal_strength': 1, 'efficiency': 1},
              3: {'t': 0, 'areas': {3}, 'region': 'R2', 'internal_strength': 1, 'efficiency': 1},
              4: {'t': 1, 'areas': {1, 2}, 'region': 'R1', 'internal_strength': 0.52873788, 'efficiency': 1.0},
              5: {'t': 1, 'areas': {3}, 'region': 'R2', 'internal_strength': 1, 'efficiency': 1}})
>>> result.edges(data=True)
OutEdgeDataView([(1, 3, {'t': 0, 'type': 'spatial', 'correlation': -0.41853318}),
                 (1, 4, {'type': 'temporal', 'transition': <RC5.PP: 2>}),
                 (2, 3, {'t': 0, 'type': 'spatial', 'correlation': 0.75087697}),
                 (2, 4, {'type': 'temporal', 'transition': <RC5.PP: 2>}),
                 (3, 1, {'t': 0, 'type': 'spatial', 'correlation': -0.41853318}),
                 (3, 2, {'t': 0, 'type': 'spatial', 'correlation': 0.75087697}),
                 (3, 5, {'type': 'temporal', 'transition': <RC5.EQ: 1>}),
                 (4, 5, {'t': 1, 'type': 'spatial', 'correlation': 0.75087697}),
                 (5, 4, {'t': 1, 'type': 'spatial', 'correlation': 0.75087697})])

fstg_toolkit.factory.spatio_temporal_graph_from_networks_graphs(networks_graphs: tuple[Graph, ...]) → DiGraph[source]¶

Compute a spatio-temporal graph that encompasses networks graphs at successive time points.

Parameters:: networks_graphs (tuple[networkx.Graph]) – The networks graphs at successive time points.
Returns:: The spatio-temporal graph.
Return type:: networkx.DiGraph

Example

>>> netG1 = nx.Graph()
>>> netG1.add_nodes_from([
...     (1, {'areas': {1}, 'region': 'R1', 'internal_strength': 1}),
...     (2, {'areas': {2, 3}, 'region': 'R2', 'internal_strength': -0.5})])
>>> netG1.add_edges_from([(1, 2, {'correlation': -0.42})])
>>> netG2 = nx.Graph()
>>> netG2.add_nodes_from([
...     (1, {'areas': {1, 2}, 'region': 'R1', 'internal_strength': 0.75}),
...     (2, {'areas': {3}, 'region': 'R2', 'internal_strength': 1})])
>>> netG2.add_edges_from([(1, 2, {'correlation': 0.41})])
>>> st_G = spatio_temporal_graph_from_networks_graphs((netG1, netG2))
>>> st_G.nodes(data=True)
NodeDataView({1: {'t': 0, 'areas': {1}, 'region': 'R1', 'internal_strength': 1},
              2: {'t': 0, 'areas': {2, 3}, 'region': 'R2', 'internal_strength': -0.5},
              3: {'t': 1, 'areas': {1, 2}, 'region': 'R1', 'internal_strength': 0.75},
              4: {'t': 1, 'areas': {3}, 'region': 'R2', 'internal_strength': 1}})
>>> st_G.edges(data=True)
OutEdgeDataView([(1, 2, {'t': 0, 'type': 'spatial', 'correlation': -0.42}),
                 (1, 3, {'type': 'temporal', 'transition': <RC5.PP: 2>}),
                 (2, 1, {'t': 0, 'type': 'spatial', 'correlation': -0.42}),
                 (2, 3, {'type': 'temporal', 'transition': <RC5.PO: 4>}),
                 (2, 4, {'type': 'temporal', 'transition': <RC5.PPi: 3>}),
                 (3, 4, {'t': 1, 'type': 'spatial', 'correlation': 0.41}),
                 (4, 3, {'t': 1, 'type': 'spatial', 'correlation': 0.41})])