Store networks & compute distributions of network properties

class braindynamics_starprotocol.network.networkdata.NetworkData

Bases: object

trial_nr

Number of experimental trials (2D time series) from which networks will be extracted.

Type:

int

edge_nr

Number of edges in the functional brain network.

Type:

int

edgelist_arr

Array of edge lists (in format <source> <target> <weight>) for each trial.

Type:

np.ndarray

laglist_arr

Array of lag lists (in format <source> <target> <lag>) for each trial.

Type:

np.ndarray

node_nr

Number of nodes in the functional brain network.

Type:

int

info_dict

Dictionary storing metadata (e.g. node labels).

Type:

dict

clear()

Function that clears NetworkData object.

compute_ew_for_Cliffs_delta() → ndarray

Function that prepares the edge weights for Cliff’s delta computation, accordingly to Varga et al. 2024

Returns:

array of shape (number of edges, number of trials) representing the edge weights for all trials

Return type:

np.ndarray

compute_ewd(bin_nr: int = 30, ewd_vmin: float = -1.0, ewd_vmax: float = 1.0) → ndarray

Function that computes edge weight distributions from multiple trials, accordingly to Varga et al 2024.

Parameters:

• bin_nr (int, optional) – number of bins for the distribution. Defaults to 30.

• ewd_vmin (float, optional) – minimum value for the distribution bins. Defaults to -1.0.

• ewd_vmax (float, optional) – maximum value for the distribution bins. Defaults to 1.0.

Returns:

array of shape (number of edges, number of bins) representing the edge weight distribution

Return type:

np.ndarray

compute_nd_for_Cliffs_delta(norm_factor: float = 1.0) → ndarray

Function that computes the node distances for Cliff’s delta accordingly to Varga et al. 2024

Parameters:

norm_factor (float, optional) – normalizion factor for edge weights (useful when there’s a correlation value above 1.0 due to numerical error/interpolation in SCA). Defaults to 1.0.

Returns:

array of shape (number of nodes, number of nodes * number of trials) representing the node distances for all trials

Return type:

np.ndarray

compute_ndd(bin_nr: int = 30, ndd_vmin: float = None, ndd_vmax: float = None, norm_factor: float = 1.0) → ndarray

Function that computes the node distance distribution accordingly to Varga et al. 2024

Parameters:

• bin_nr (int, optional) – _number of bins for the distribution. Defaults to 30.

• ndd_vmin (float, optional) – minimum value for the distribution bins. Defaults to -1.

• ndd_vmax (float, optional) – maximum value for the distribution bins. Defaults to -1.

• norm_factor (float, optional) – normalizion factor for edge weights (useful when there’s a correlation value above 1.0 due to numerical error/interpolation in SCA). Defaults to 1.0.

Returns:

array of shape (number of nodes, number of bins) representing the node distance distribution

Return type:

np.ndarray

compute_new_for_Cliffs_delta() → ndarray

Function that computes the node edge weights for Cliff’s delta (aggregated EWD for the nodes), accordingly to Varga et al. 2024

Parameters:

-

Returns:

array of shape (number of nodes, number of nodes * number of trials) representing the node edge weights for all trials

Return type:

np.ndarray

compute_newd(bin_nr: int = 30, newd_vmin: float = -1.0, newd_vmax: float = 1.0) → ndarray

Function that computes the node edge weight distribution (aggregated EWD for the nodes), accordingly to Varga et al. 2024

Parameters:

• bin_nr (int, optional) – number of bins for the distribution. Defaults to 30.

• newd_vmin (float, optional) – mimimum value for the distribution bins. Defaults to -1.0.

• newd_vmax (float, optional) – maximum value for the distribution bins. Defaults to 1.0.

Returns:

array of shape (number of nodes, number of bins) representing the node edge weight distribution

Return type:

np.ndarray

extract(samp_mat_list: list, corrgram: CrossCorrelogram, use_fisher: bool = True, cc_method: str = 'C', export_to_filelists: tuple = None) → None

Function that extracts functional brain networks from experimental trial samples. Functional connectivity (edge weights) is defined as cross-correlation (either classical Pearson or SCA developed by Nikolic et al)

Parameters:

• samp_mat_list (list) – list of trial sample matrices of shape (number of trials, number of channels/nodes, length of a trial)

• corrgram (CrossCorrelogram) – cross-correlogram object with pre-defined parameters

• use_fisher (bool, optional) – use Fisher transform or not in scaled correlation computation (see Nikolic et al. 2012). Defaults to True.

• cc_method (str, optional) – choose implementation (python or cython). Defaults to C.

get_maxabs_weights() → float

Function that finds the maximum absolute edge weight across the trials. It can be used to normalize all edge weights.

Returns:

value of maximum absolute edge weight (if it’s above 1.0, return 1.0 instead)

Return type:

float

get_minmax_distances(norm_factor: float = 1.0) → tuple

Function that finds the minimum and maximum distance (shortest path length between nodes).

Parameters:

norm_factor (float, optional) – normalizion factor for edge weights (useful when there’s a correlation value above 1.0 due to numerical error/interpolation in SCA). Defaults to 1.0.

Returns:

minimum and maximum distance value

Return type:

tuple

load_from_filelist(filelist_path: str, load_lags: bool = False) → None

Function that loads edgelists from filelist.

Parameters:

filelist_path (str) – Path to filelist (enumeration of edge list files)

Raises:

ValueError – uneven edge list lengths

write_to_filelist(filelist_path: str, save_lags: bool = False) → None

Function that exports edgelists into separate files and generates the filelist.

Parameters:

• filelist_path (str) – path to filelist

• save_lags (bool, optional) – save edge weights (maxabs) or lags (time offsets from correlogram). Defaults to False.