gdar package

Submodules

gdar.flow module

class gdar.flow.FlowSignal(graph, f=None)

Bases: object

Class defining flow signal as well as useful transforms for decomposing flow signal into various spatial modes. The basis for the decomposition is the Hodge decomposition of the graph Laplacian, which decomposes the flow signal into gradient, curl, and harmonic components.

For mathematical details on the Hodge decomposition, see: [2] S. Barbarossa and S. Sardellitti, “Topological Signal Processing Over Simplicial Complexes,” in IEEE Transactions on Signal Processing

flow_ft(f=None, idx=None, spectral_analysis=True, mode='full')

Compute the Flow Fourier Transform of the flow signal on the graph. This decomposes the flow signal into gradient, curl, and harmonic components based on the Hodge decomposition of the graph Laplacian. Note that the eigenvectors of the gradient and curl components are not unit norm. To get a meaningful spectrum, the eigenvectors are normalized to have unit norm first if spectral_analysis is True. The hodge decomposition needs to be computed first by calling the hodge_decomposition.

Parameters:

• f (numpy.ndarray, optional) – Flow signal defined on the edges of the graph, shape (E, T) where E is the number of edges and T is the number of time steps. If None, use self.f.

• idx (int or array-like, optional) – Time indices for which the Flow Fourier Transform is computed. If None, compute the Flow Fourier Transform for all time steps.

• spectral_analysis (bool) – If True, normalize the eigenvectors of the gradient and curl components to have unit norm. This is useful for spectral analysis of the flow signal.

• mode (str) – The mode of decomposition. Can be ‘grad’, ‘curl’, or ‘full’. If ‘grad’, only the gradient spectrum is computed. If ‘curl’, only the curl spectrum is computed. If ‘full’, both gradient and curl spectra are computed, as well as harmonic spectrum.

Returns:

get_flow_adjacency_matrix(index=0, f=None)

Convert the flow signal into an adjacency matrix representation. This is useful for computing measures of network communication such as communicability.

Parameters:

• index (int) – Index of the flow signal if f is a matrix. If f is None, use self.f.

• f (numpy.ndarray, optional) – Flow signal or matrix. If None, use self.f.

Returns:

Flow signal represented as an adjacency matrix of shape (N, N), where N is the number of nodes in the graph. The flow signal is represented as a directed graph. That is, the adjacency matrix is asymmetric.

Return type:

numpy.ndarray

hodge_decomposition(mode='full')

Compute the Hodge decomposition of the flow signal on the graph. This defines the gradient, curl, and harmonic eigenfunctions of the flow signal and serves as the basis for the Flow Fourier transform.

Parameters:

mode (str) – The mode of decomposition. Can be ‘grad’, ‘curl’, or ‘full’. If ‘grad’, only gradient modes are computed. If ‘curl’, only curl modes are computed. If ‘full’, both gradient and curl modes are computed, as well as harmonic modes. Note that to compute the gradient componenet the node to edge incidence matrix B1 and to compute the curl comonent the edge to triangle incidence matrix B2 must be defined in the graph.

Returns:

Depending on the mode, returns the following:

• If mode is ‘grad’: (w_grad, V_grad)

• If mode is ‘curl’: (w_curl, V_curl)

• If mode is ‘full’: (w_grad, V_grad, w_curl, V_curl, w_harm, V_harm)

Return type:

tuple

set_flow_signal(f)

Set the flow signal for the FlowSignal object.

Parameters:

f (numpy.ndarray) – Flow signal defined on the edges of the graph, shape (E, T) where E is the number of edges and T is the number of time steps.

set_graph(graph)

Set the graph for the FlowSignal object.

Parameters:

graph (gdar.graph.Graph) – The graph object on which the model operates.

spectrogram(f=None, avg_win=1, mode='full')

Compute the spectrogram of the flow signal on the graph. This computes the magnitude square of the gradient and curl spectra of the flow signal and averages them over a sliding window of size avg_win. The hodge decomposition needs to be computed first by calling the function hodge_decomposition.

Parameters:

• f (numpy.ndarray, optional) – Flow signal defined on the edges of the graph, shape (E, T) where E is the number of edges and T is the number of time steps. If None, use self.f.

• avg_win (int) – Size of the sliding window for averaging the spectra.

• mode (str) – The mode of decomposition. Can be ‘grad’, ‘curl’, or ‘full’. If ‘grad’, only the gradient spectrogram is computed. If ‘curl’, only the curl spectrogram is computed. If ‘full’, both gradient and curl spectrograms are computed.

Returns:

Depending on the mode, returns the following:

• If mode is ‘grad’: (w_grad, Spec_grad)

• If mode is ‘curl’: (w_curl, Spec_curl)

• If mode is ‘full’: (w_grad, Spec_grad, w_curl, Spec_curl)

Return type:

tuple

gdar.gdar_model module

class gdar.gdar_model.GDARModel(graph, K)

Bases: object

Implements the Graph Diffusion Autoregressive (GDAR) model along with other related multivariate autoregressive models. Furthermore, additional sparsity constraints can be applied to the model coefficients.

For mathematical details on the model, see: [1] Schwock et al., Inferring Neural Communication Dynamics from Field Potentials Using Graph Diffusion Autoregression

dtf(coeff_spec)

Compute Directed Transfer Function (DTF) from coefficient spectrum. DTF is a measure of the directed connectivity between two nodes in a multivariate autoregressive model. :type coeff_spec: :param coeff_spec: Coefficient spectrum of shape (N, N, n), where N is the number of nodes and n is

the number of frequency bins.

Returns:

DTF estimate of shape (N, N, n).

Return type:

np.ndarray

fit_gdar(data, I_sparse=None)

Fits the GDAR model to the data. The parameters are estimated in closed form using the generalized least squares (GLS) estimator.

Parameters:

• data (np.ndarray) – NxT data matrix, where T is the number of time steps and N is the number of nodes.

• I_sparse (np.ndarray or None) – Additional enforced sparsity structure. Defined by horizontal stacking of adjacency matrix. If None, the sparsity structure is defined by the graph’s adjacency matrix.

Returns:

Coefficients of the fitted GDAR model.

Return type:

np.ndarray

fit_gvar(data, I_sparse=None)

Fits VAR model that is constrained to the graph structure. The parameters are estimated in closed form using the generalized least squares (GLS) estimator. This is the same as the GDAR model, but without the symmetry constraint. In [1], this is referred to as the eVAR model.

Parameters:

• data (np.ndarray) – NxT data matrix, where T is the number of time steps and N is the number of nodes.

• I_sparse (np.ndarray or None) – Additional enforced sparsity structure. Defined by horizontal stacking of adjacency matrix. If None, the sparsity structure is defined by the graph’s adjacency matrix.

Returns:

Coefficients of the fitted GVAR model.

Return type:

np.ndarray

fit_restricted(data, C=None, sym=False, I_sparse=None)

Fits VAR model with sparsity and symmetry constraints. If sym=True, this implemented the GDAR model for a given graph. Parameters are estimated in closed form using the generalized least squares (GLS) estimator.

Parameters:

• data (np.ndarray) – NxT data matrix, where T is the number of time steps and N is the number of nodes.

• C (np.ndarray or None) – Noise covariance matrix. If None, the noise covariance matrix is the identity matrix.

• sym (bool) – If True, applies symmetry constraint to the model coefficients.

• I_sparse (np.ndarray or None) – Additional enforced sparsity structure. Defined by horizontal stacking of adjacency matrix. If None, the sparsity structure is defined by the graph’s adjacency matrix.

Returns:

Coefficients of the fitted model. Shape is N x N x K, where K is the order of the model.

Return type:

np.ndarray

fit_var(data)

Fits standard VAR model without any constraints. Parameters are estimated in closed form using the ordinary least squares (OLS) estimator.

Parameters:

data (np.ndarray) – NxT data matrix, where T is the number of time steps and N is the number of nodes.

Returns:

Coefficients of the fitted VAR model. Shape is N x N x K, where K is the order of the model.

Return type:

np.ndarray

get_flow_gdar(data, coeffs=None)

Compute the GDAR flow signal (i.e. unidirectional flow) based on the model coefficients. The flow is computed by convolving the gradient of the data with the model coefficients. The flow matrix has shape E x T, where E is the number of edges in the graph and T is the number of time points minus K + 1 (the order of the model).

Parameters:

• data (np.ndarray) – NxT data matrix, where N is the number of nodes and T is the number of time points.

• coeffs (np.ndarray) – Fitted GDAR model coefficients of appropriate shape.

Returns:

FlowSignal object containing the computed flow signal.

Return type:

gdar.flow.FlowSignal

get_flow_var(data, coeffs=None, constrained=False)

Compute the VAR flow signal (i.e. bidirectional flow). The computed flow matrix either has shape N x N x T - K + 1 if the flow is computed for all possible edges or shape 2 x E x T - K + 1 if the flow is computed only for the edges of the predefined graph. The flow is computed by convolving the data with the model coefficients.

Parameters:

• data (np.ndarray) – N x T data matrix, where N is the number of nodes and T is the number of time points.

• coeffs (np.ndarray) – Fitted VAR model coefficients of appropriate shape.

• constrained (bool) – If True, compute flow only along edges of the predefined graph.

Returns:

FlowSignal object containing the computed flow signal.

Return type:

gdar.flow.FlowSignal

get_noise_covariance(data, coeffs=None)

Estimates noise covariance matrix from the residuals of the fitted model.

Parameters:

• data (np.ndarray) – NxT data matrix, where T is the number of time steps and N is the number of nodes.

• coeffs (np.ndarray or None) – Coefficients of the fitted model. If None, uses the current model coefficients.

Returns:

Estimated noise covariance matrix. Shape is N x N.

Return type:

np.ndarray

param_connectivity(coeff_spec)

Compute parameter connectivity from coefficient spectrum. This is a measure of the strength of the connection between two nodes from the model coefficients and is defined as the absolute value of the coefficient spectrum normalized by the geometric mean of the denominators of the coefficients of the nodes.

Parameters:

coeff_spec (np.ndarray) – Coefficient spectrum of shape (N, N, n), where N is the number of nodes and n is the number of frequency bins.

Returns:

Parameter connectivity estimate of shape (N, N, n).

Return type:

np.ndarray

pdc(coeff_spec)

Compute Partial Directed Coherence (PDC) from coefficient spectrum. PDC is a measure of the directed connectivity between two nodes in a multivariate autoregressive model.

Parameters:

coeff_spec (np.ndarray) – Coefficient spectrum of shape (N, N, n), where N is the number of nodes and n is the number of frequency bins.

Returns:

PDC estimate of shape (N, N, n).

Return type:

np.ndarray

spectrum(coeffs=None, n=1999)

Compute the spectrum of the model coefficients using the discrete Fourier transform (DFT). This is the basis for many functional connectivity metrics such as Directed Transfer Function (DTF) and Partial Directed Coherence (PDC).

Parameters:

• coeffs (np.ndarray or None) – Coefficients of the fitted model. If None, uses the current model coefficients.

• n (int) – Number of frequency bins for the DFT.

Returns:

Coefficient spectrum of shape (N, N, n), where N is the number of nodes and n is the number of

frequency bins.

Return type:

np.ndarray

gdar.graph module

class gdar.graph.Graph

Bases: object

Generic graph class. Different ways of representing a graph

B2_all_triangles()

Compute the edge to triangle incidence matrix B2 using all possible triangles in the graph. This function checks all edges and finds all triangles that can be formed by the edges.

Returns:

Edge to triangle incidence matrix B2

Return type:

np.ndarray

add_edges(edge_list)

Add edges to existing graph.

Parameters:

• edge_list (list) – List of edges to add, where each edge is a tuple (from_node, to_node).

• edges. (Note that the edge list should not contain duplicate)

custom_proximity_graph(node_positions, dist=None)

Creates graph based on node proximity, where the distance threshold can be specified for each node individually.

Parameters:

• node_positions (dict) – Dictionary with node positions. Each entry should be of the form node_id: pos, where pos is a numpy array of shape (2,) for 2D or (3,) for 3D.

• dist (tuple or dict) –

  Distance threshold. If a tuple is provided, it will be used to assign nodes to two different distance thresholds. If a dictionary is provided, it should contain the distance thresholds for each node. The dictionary should be of the form: ``` dist_dct = {

  dist1: [d1_n1, d1_n2, …], dist2: [d2_n1, d2_n2, …], …

  where dist1, dist2, etc. are the distance thresholds and d1_n1, d1_n2, etc. are the nodes that

Returns:

The graph object with the generated proximity graph.

Return type:

self

delaunay_triangulation(node_positions)

Compute the Delaunay triangulation of the graph based on the node positions.

Parameters:

node_positions (dict) – Dictionary with node positions. Each entry should be of the form node_id: pos, where pos is a numpy array of shape (2,) for 2D or (3,) for 3D.

Returns:

Edge to triangle incidence matrix B2

Return type:

np.ndarray

generate_from_edge_list(edge_list)

Generate graph from edge list. Each entry of the edge_list should be a tuple of the form (from_node, to_node). Node labeling should start at 0 and be consecutive integers. Which node is the from_node and which is the to_node is arbitrary for the GDAR model. The functions will set the number of nodes N and edges E, the node list nodes, node to edge incidence matrix B1, the adjacency matrix A, the degree matrix D, the combinatorial Laplacian L, the edge list edge_list, the list of unique nodes, and the neighbors. The edge list will be sorted such that the smaller node index is always the first element in the tuple. dictionary.

Parameters:

edge_list (list) – List of edges, where each edge is a tuple (from_node, to_node).

get_diameter()

Compute diameter of graph

Returns:

Diameter of the graph, which is the maximum distance between any two nodes in the graph.

Return type:

int

get_graph_laplacian()

Compute the combinatorial Laplacian of the graph, which is defined as L = B1 @ B1.T, where B1 is the node

to edge incidence matrix.

Returns:

Combinatorial Laplacian matrix L

Return type:

np.ndarray

get_hodge_laplacian()

Compute the full Hodge-1 Laplacian of the graph. Note that the edge-to-triangle incidence matrix B2 has to be set before calling this function. This can be done by calling delaunay_triangulation or B2_all_triangles.

Returns:

Hodge-1 Laplacian matrix L1

Return type:

np.ndarray

get_lower_hodge_laplacian()

Compute the lower Hodge-1 Laplacian of the graph, which is defined as L1l = B1.T @ B1, where B1 is the

node to edge incidence matrix.

Returns:

Lower Hodge-1 Laplacian matrix L1l

Return type:

np.ndarray

get_subgraph_edges_from_nodes(node_list)

Returns subgraph in the form of a list of edges. Only edges that are connected to nodes in node_list are included.

Parameters:

node_list (list) – List of node indices for which the subgraph edges should be returned.

Returns:

List of edge indices that are connected to the nodes in node_list.

Return type:

list

get_upper_hodge_laplacian()

Compute the upper Hodge-1 Laplacian of the graph. Note that the edge-to-triangle incidence matrix B2 has to be set before calling this function. This can be done by calling delaunay_triangulation or B2_all_triangles.

Returns:

Upper Hodge-1 Laplacian matrix L1u

Return type:

np.ndarray

nn_graph(node_positions, n_neighbors=8)

Creates a nearest neighbor graph if either x and y or x, y, and z coordinates are given.

Parameters:

• node_positions (dict) – Dictionary with node positions. Each entry should be of the form node_id: pos, where pos is a numpy array of shape (2,) for 2D or (3,) for 3D.

• n_neighbors (int) – Number of nearest neighbors to connect each node to. Default is 8.

Returns:

The graph object with the generated nearest neighbor graph.

Return type:

self

proximity_graph(node_positions, dist_th=5)

Creates graph based on node proximity. All nodes that are less or equal than dist_th away from each other are connected.

Parameters:

• node_positions (dict) – Dictionary with node positions. Each entry should be of the form node_id: pos, where pos is a numpy array of shape (2,) for 2D or (3,) for 3D.

• dist_th (float) – Distance threshold. Nodes that are closer than this distance will be connected.

Returns:

The graph object with the generated proximity graph.

Return type:

self

remove_edges(edge_list)

Remove edges from existing graph.

Parameters:

• edge_list (list) – List of edges to remove, where each edge is a tuple (from_node, to_node).

• graph. (Note that the edge list should not contain edges that are not in the)

set_node_position_name(node_positions, node_names=None)

Set node positions and optionally node names for the graph.

Parameters:

• node_positions (dict) – Dictionary with node positions. Each entry should be of the form node_id: pos, where pos is a numpy array of shape (2,) for 2D or (3,) for 3D.

• node_names (list, optional) – List of node names. If provided, should have the same length as the number of nodes in the graph. Default is None.

gdar.visualization module

gdar.visualization.plot_flow_field(graph, flow_vector, projection='xy', plot_potentials=True, origin='lower', ax=None, cmap='bwr_r', vmin=-0.5, vmax=0.5, interpolation='bilinear', node_size=30, node_color='lightgray', flow_filed_scaling_factor=15, arrowstyle='-|>', mutation_scale=8, arrow_color='black', linewidth=2)

Plot flow and potential field from flow vector. The potential field is computed as graph.B1 @ flow_vector and plotted as a background using imshow. The flow field is computed as the average flow at each node.

Parameters:

• graph (gdar.graph.Graph) – Graph object containing edge_list and node_positions.

• flow_vector (np.ndarray) – Flow vector with flow values for each edge.

• projection (str) – Projection if x, y, z coordinates are given in node_positions. Options are ‘xy’, ‘xz’, ‘yz’, or None (default). If None, the first two dimensions (xy) are used.

• plot_potentials (bool) – If True, plot potential field as background (default: True).

• origin (str) – Origin parameter for imshow (default: ‘lower’).

• ax (matplotlib axis) – Matplotlib axis to draw on (default: None, creates new figure).

• cmap (str or Colormap) – Colormap for potential field (default: ‘bwr_r’).

• vmin (float) – Minimum value for potential field colormap (default: -0.5).

• vmax (float) – Maximum value for potential field colormap (default: 0.5).

• interpolation (str) – Interpolation method for imshow (default: ‘bilinear’).

• node_size (int) – Size of nodes in the graph (default: 30).

• node_color (str or list) – Color of nodes in the graph (default: ‘lightgray’).

• flow_filed_scaling_factor (float) – Scaling factor for flow field arrows (default: 15).

• arrowstyle (str) – Arrow style for flow field arrows (default: ‘-|>’).

• mutation_scale (int) – Mutation scale for flow field arrows (default: 8).

• arrow_color (str) – Color of flow field arrows (default: ‘black’).

• linewidth (float) – Line width of flow field arrows (default: 2).

Returns:

If plot_potentials is True, returns a tuple (potentials, flow_vector) where potentials is the

potential field and flow_vector is the flow vector at each node. If plot_potentials is False, returns only the flow_vector at each node.

Return type:

tuple or array

gdar.visualization.plot_flow_graph(graph, flow_vector, directed=True, projection=None, **kwargs)

Plot flow graph using NetworkX.

Parameters:

• graph (gdar.graph.Graph) – Graph object containing edge_list and node_positions.

• flow_vector (np.ndarray) – Flow vector with flow values for each edge.

• directed (bool) – If True, plot as directed graph; otherwise, as undirected.

• projection (str) – Projection if x, y, z coordinates are given in node_positions. Options are ‘xy’, ‘xz’, ‘yz’, or None (default). If None, the first two dimensions (xy) are used.

• kwargs – Additional keyword arguments for the NetworkX draw function. The following keyword arguments are set automatically if not provided, or are in addition to the ones already set by NetworkX draw function: - edge_cmap: Colormap for edge weights (default: cm.bwr). - vlim_quantile: Quantile for setting vmin and vmax of the colormap (default: None). - edge_vmin: Minimum value for edge weights (default: min(flow_vector)). - edge_vmax: Maximum value for edge weights (default: max(flow_vector)). - width: Width of edges (default: 3.0). - node_size: Size of nodes (default: 100). - node_color: Color of nodes (default: ‘lightgray’). - color_label: Label for the colorbar (default: ‘flow magnitude’). - extend: Extend option for the colorbar (default: ‘neither’). - show_colormap: Whether to show the colormap (default: True). - cmap_pad: Padding for the colormap (default: -0.05). - edgelist: List of edges to highlight in the plot. - ax: Matplotlib axis to draw on (default: current axis).

gdar.visualization.plot_graph(graph, directed=True, projection=None, **kwargs)

Plot graph using NetworkX.

Parameters:

• graph (gdar.graph.Graph) – Graph object containing edge_list and node_positions.

• directed (bool) – If True, plot as directed graph; otherwise, as undirected.

• projection (str) – Projection if x, y, z coordinates are given in node_positions. Options are ‘xy’, ‘xz’, ‘yz’, or None (default). If None, the first two dimensions (xy) are used.

• kwargs – Additional keyword arguments for the NetworkX draw function.

gdar.visualization.set_edge_weights(edge_list, edge_weights=None)

Set weights for edges in a graph. This is needed for creating a NetworkX graph with weighted edges.

Parameters:

• edge_list (list) – List of edges in the graph, where each edge is a tuple (node1, node2).

• edge_weights (list, optional) – List of weights corresponding to each edge. If None, all edges are assigned a weight of 1.

Returns:

List of edges with weights, where each edge is a tuple (node1, node2, {‘weight’: weight}).

Return type:

list

gdar.visualization.truncate_colormap(cmap, minval=0.0, maxval=1.0, n=100)

Truncate a colormap to a specified range.

Parameters:

• cmap (Colormap) – The colormap to truncate.

• minval (float) – The lower bound of the range to keep (0.0 to 1.0).

• maxval (float) – The upper bound of the range to keep (0.0 to 1.0).

• n (int) – Number of colors in the truncated colormap.

Returns:

A new colormap that is truncated to the specified range.

Return type:

LinearSegmentedColormap

Module contents