Graph Utility functions

The graph utility functions module is a set of utility functions when working with graphs. They contain functions for plotting graphs, converting them and checking for certain properties, for example checking if the graph asteroidal. The module is split into two main parts:

1. Conversion functions, which handle conversions between different graph formats
2. Non-conversion functions such as saving/writing graphs, plotting, etc.

All utility functions can also be used outside the PHOTONAI Graph framework to handle conversions or check graph layouts.

Graph Utility Functions

check_asteroidal(graph)

checks whether a graph or a list of graphs is asteroidal

Parameters:

Name	Type	Description	Default
graph	list or nx.classes.graph.Graph	a list of networkx graphs or a single networkx graph	required

return_boolean : boolean, default=True whether to return a True/False statement about the graphs or a list of asteroidal triples per graph

Returns:

Type	Description
list	A list of asteroidal triples or a single asteroidal triple

check_asteroidal_boolean(graph)

checks wether a graph or a list of graphs is asteroidal

Parameters:

Name	Type	Description	Default
graph	Union[nx.Graph, List[nx.Graph]]	Input graph(s)	required

Returns:

Type	Description
Union[bool, List[bool]]	True if graph is asteroidal, False otherwise per graph

draw_connectivity_matrix(matrix, colorbar=False, colorscheme='viridis', adjacency_axis=None, show=True)

Draw connectivity matrix.

Parameters:

Name	Type	Description	Default
matrix	numpy.ndarray, numpy.matrix or a list of those		required
the			required

colorbar : boolean, default=False Whether to use a colorbar in the drawn plot

colorscheme: str, default="viridis" colorscheme for plotting the connectivity matrix

adjacency_axis : int, default=None position of the the adjacency axis, if specified the array is assumed to have an additional axis where the matrix is stored.

show: bool, default=True whether to show the connectivity matrix or not.

Notes

If new nodes are added with features, and any of the old nodes do not have some of the feature fields, those fields are filled by initializers defined with set_n_initializer (default filling with zeros).

Examples:

Python Console Session

>>> g = get_random_connectivity_data()
>>> draw_connectivity_matrix(adjacency_axis=0)

draw_connectogram(graph, connection_style='arc3', colorscheme=None, nodesize=None, node_shape='o', weight=None, path=None, show=True)

This functions draws a connectogram, from a graph.

Parameters:

Name	Type	Description	Default
graph		input graph, a single networkx graph	required
connection_style		connection style, controlling the style of the drawn edges	'arc3'
colorscheme		colormap for drawing the connectogram	None
nodesize		controls size of the drawn nodes	None
node_shape		shape of the drawn nodes	'o'
weight		threshold below which edges are coloured differently than above	None
path		path where to save the plots as string, if no path is declared, plots are not saved. Path needs to be the full path including file name and ending, unlike in draw_connectograms	None
show		whether to plot the graph or not. Set it to false in headless environments	True

draw_connectograms(graphs, curved_edge=False, colorscheme=None, nodesize=None, node_shape='o', weight=None, path=None, ids=None, out_format=None, show=True)

This function draws multiple connectograms, from graph lists.

Parameters:

Name	Type	Description	Default
graphs		input graphs, a list of networkx graphs or a single networkx graph	required
curved_edge		whether to draw straight or curved edges	False
colorscheme		colormap for drawing the connectogram	None
nodesize		controls size of the drawn nodes	None
node_shape		shape of the drawn nodes	'o'
weight		threshold below which edges are coloured differently than above	None
path		path where to save the plots as string, if no path is declared, plots are not saved	None
ids		list of ids, after which to name the plots	None
out_format		output format for the graphs, as a string	None
show		whether to plot the connectograms or not. Set it to false in headless environments	True

get_random_connectivity_data(out_type='dense', number_of_nodes=114, number_of_individuals=10, number_of_modalities=2)

generate random connectivity matrices for testing and debugging

Parameters:

Name	Type	Description	Default
out_type		output type for connectivity data, default="dense"	'dense'
number_of_nodes		number of nodes in the matrix/graph	114
number_of_individuals		number of individual graphs/matrices	10
number_of_modalities		number of modalities as per matrix/graph	2

get_random_labels(l_type='classification', number_of_labels=10)

get random labels for testing and debugging functions.

Parameters:

Name	Type	Description	Default
l_type	str, default	controls the type labels. "classification" outputs binary labels 0 and 1, "regression" outputs random float.	'classification'

number_of_labels : int, default=10 number of labels to generate

Returns:

Type	Description
np.ndarray	The labels as np.ndarray

Notes

If used in conjunction with get_random_connectivity_data number_of_labels should match number_of_individuals.

Examples:

Python Console Session

>>> labels = get_random_labels()

individual_fishertransform(matrx, adjacency_axis=0)

applies a fisher transformation individually to each connectivity matrix in an array. all values need to be finite (non nans) as this would introduce complex numbers, which can not be handled by other methods.

Parameters:

Name	Type	Description	Default
matrx	np.ndarray	An array containing the adjacency values for the graphs	required
adjacency_axis		the position of the adjacency matrix	0

Returns:

Type	Description
np.ndarray	The fisher transformed matrices as an array

Examples:

Python Console Session

>>> X = get_random_connectivity_data()
>>> X_transformed = individual_fishertransform(X)

individual_ztransform(matrx, adjacency_axis=0)

applies a z-score transformation individually to each connectivity matrix in an array

Parameters:

Name	Type	Description	Default
matrx	np.ndarray	a list or of networkx graphs or a single networkx graph	required

adjacency_axis: int, default=0 the position of the adjacency matrix

Returns:

Type	Description
np.ndarray	The z-score transformed matrices as an array

Examples:

Python Console Session

>>> X = get_random_connectivity_data()
>>> X_transformed = individual_ztransform(X)

load_conn(path='', mtrx_name='matrix', subject_dim=3, modality_dim=2)

loads matlab 4d connectivity matrix from matlab file This function is untested and serves only as an example how to load connectivity data.

pydot_to_nx(graphs)

transforms pydot graphs to networkx graphs

Parameters:

Name	Type	Description	Default
graphs	list or pydot.Dot		required
a			required

Returns:

Type	Description
list or pydot.Dot	The input graph or graphs in networkx format

visualize_networkx(graphs, layout=nx.spring_layout, colorscheme='Blues', show=True)

Visualize a networkx graph or graphs using networkx built-in visualization.

Parameters:

Name	Type	Description	Default
graphs		a list or of networkx graphs or a single networkx graph	required
layout		layout of the graph, default is spring layout	nx.spring_layout
colorscheme		colormap for the nodes, default is Blues	'Blues'
show		whether to show the plot or not. Set it to False in headless environments	True

Examples:

Python Console Session

>>> g1, g2 = nx.line_graph(10), nx.line_graph(7)
>>> graphs = [g1, g2]
>>> visualize_networkx(graphs)