macro_eeg_model.config

This package contains the configuration files for the simulation.

Submodules

• macro_eeg_model.config.configs
• macro_eeg_model.config.connectivity_model
• macro_eeg_model.config.model_config
• macro_eeg_model.config.nodes_processor
• macro_eeg_model.config.parser

Classes

ConnectivityModel	A class to model the connectivity between brain nodes. It computes
ModelConfig	A class to configure parameters and model the connectivity between brain nodes, including
NodesProcessor	A class to process given brain regions into their corresponding indices in
Parser	The Parser class is responsible for parsing the command line arguments and setting

Functions

get_simulate_config()	First parses command line arguments using get_parsed_args(), then
get_parsed_args()	Parses command line arguments using src.config.parser.Parser.parse_args().

Package Contents

macro_eeg_model.config.get_simulate_config()

First parses command line arguments using get_parsed_args(), then creates an instance of the src.config.model_config.ModelConfig class based on the parsed arguments.

Returns:

A tuple containing:

• config (ModelConfig): The configuration object for the simulation.

• model_name (str): The name of the model as specified in the command line arguments.

• n (int): The number of simulations to run, as specified in the command line arguments.

Return type:

tuple

macro_eeg_model.config.get_parsed_args()

Parses command line arguments using src.config.parser.Parser.parse_args().

Returns:

The parsed command line arguments as an argparse.Namespace object.

Return type:

argparse.Namespace

class macro_eeg_model.config.ConnectivityModel(given_nodes, relay_station)

A class to model the connectivity between brain nodes. It computes distances and connectivity weights between nodes, with optional relay stations.

nodes

The processed list of nodes used in the model.

Type:

list

nr_nodes

The total number of nodes in the model.

Type:

int

distances

The matrix of distances between nodes.

Type:

numpy.ndarray

connectivity_weights

The matrix of connectivity weights between nodes.

Type:

numpy.ndarray

_given_nodes

The list of nodes provided for the connectivity model.

Type:

list

_relay_station

The relay station node name, if any.

Type:

str

_relay_nodes

The list of relay nodes derived from the relay station, if applicable.

Type:

list

_relay_indices

The indices of the relay nodes in the connectivity model.

Type:

list

_nodes_indices

A dictionary mapping each node to its corresponding indices.

Type:

dict

_avg_counts

The average counts of connections between nodes.

Type:

numpy.ndarray

_avg_fc

The average functional connectivity between nodes.

Type:

numpy.ndarray

_avg_lengths

The average distances (lengths) between nodes.

Type:

numpy.ndarray

_relay_distances

The dictionary of average distances between nodes and the relay station.

Type:

dict

__init__(given_nodes, relay_station)

Initializes the ConnectivityModel with given nodes and an optional relay station.

Parameters:

• given_nodes (list) – The list of nodes to be used in the connectivity model.

• relay_station (str) – The relay station name (or None).

set_connectivity(custom_connectivity)

Assigns streamline lengths to the distances matrix (relayed, if applicable) and weights to the connectivity matrix based on either custom-provided values or default calculations based on functional connectivity (FC).

The values for a pair of nodes are extracted from _get_pair_stats().

Parameters:

custom_connectivity (bool) – If True, attempts to load and use custom connectivity weights from connectivity_weights.csv file in the configs path (see src.utils.paths.Paths).

Raises:

AssertionError – If the shape of the custom connectivity matrix is incorrect or the matrix has been incorrectly constructed.

_get_pair_stats(node1, node2)

Retrieves statistics for a pair of nodes, including counts, functional connectivity, and distances.

Parameters:

• node1 (str) – The name of the first node.

• node2 (str) – The name of the second node.

Returns:

A tuple containing lists of counts, functional connectivity values, and distances between the two nodes.

Return type:

tuple

_init_relay_distances()

Calculates and stores the average distance between each node and the relay station, if a relay station is specified.

_init_nodes()

Initializes and processes nodes using src.config.nodes_processor.NodesProcessor.get_nodes_indices().

_init_connectivity()

Initializes the connectivity matrix and distances between nodes.

It creates matrices for distances and connectivity weights between nodes, initializing with zeros or tuples as appropriate (depending on whether there is a relay station) and NaNs on the diagonal.

_load_data()

Loads precomputed connectivity data such as counts, functional connectivity, and streamline lengths between nodes from the connectivity data path (see src.utils.paths.Paths).

_init_data()

Checks if the necessary structural and functional connectivity data files exist. If the files are found, it loads them; otherwise, it triggers the data preparation process using src.data_prep.data_preparator.DataPreparator and then loads the prepared data.

class macro_eeg_model.config.ModelConfig(nodes: list[str], relay_station: str | None, sample_rate: int, t_lags: int, t_secs: int, t_burnit: int, noise_color: str, std_noise: int, dist_shape: float, dist_scale: float, dist_location: float, dist_trunc_percent: float, custom_connectivity=False)

A class to configure parameters and model the connectivity between brain nodes, including the distances, connectivity weights, and the generation of delays.

nodes

The list of processed nodes used in the model.

Type:

list[str]

nr_nodes

The total number of nodes in the model.

Type:

int

relay_station

The relay station node name, if any.

Type:

str, optional

sample_rate

The sampling rate of the model, in Hz.

Type:

int

nr_lags

The number of time lags calculated based on the sample rate and the total time (ms) in lags.

Type:

int

t_secs

The total time of the simulation in seconds.

Type:

int

t_burnit

The burn-in time for the simulation, in seconds.

Type:

int

noise_color

The color of the noise to be used in the simulation.

Type:

str

std_noise

The standard deviation of the noise to be used in the simulation.

Type:

int

distances

A matrix containing the distances between the nodes.

Type:

numpy.ndarray

connectivity_weights

A matrix containing the connectivity weights between the nodes.

Type:

numpy.ndarray

delay_calculator

An instance of the src.simulation.delay_calculator.DelayCalculator class used to calculate delay distributions.

Type:

DelayCalculator

_dist_shape

The shape parameter for the delay distribution (xi in GEV distribution).

Type:

float

_dist_scale

The scale parameter for the delay distribution (sigma in GEV distribution).

Type:

float

_dist_location

The location parameter for the delay distribution (mu in GEV distribution).

Type:

float

_truncation_percentile

The percentile at which to truncate the delay distribution.

Type:

float

__init__(nodes: list[str], relay_station: str | None, sample_rate: int, t_lags: int, t_secs: int, t_burnit: int, noise_color: str, std_noise: int, dist_shape: float, dist_scale: float, dist_location: float, dist_trunc_percent: float, custom_connectivity=False)

Initializes the ModelConfig with specified parameters for nodes, connectivity, simulation, and delay distribution.

Parameters:

• nodes (list[str]) – The list of nodes to be used in the connectivity model.

• relay_station (str, optional) – The relay station name, if any.

• sample_rate (int) – The sampling rate of the model, in Hz.

• t_lags (int) – The total time in lags for the simulation.

• t_secs (int) – The total time of the simulation in seconds.

• t_burnit (int) – The burn-in time for the simulation, in seconds.

• noise_color (str) – The color of the noise to be used in the simulation.

• std_noise (int) – The standard deviation of the noise to be used in the simulation.

• dist_shape (float) – The shape parameter for the delay distribution (xi in GEV distribution).

• dist_scale (float) – The scale parameter for the delay distribution (sigma in GEV distribution).

• dist_location (float) – The location parameter for the delay distribution (mu in GEV distribution).

• dist_trunc_percent (float) – The percentile at which to truncate the delay distribution.

• custom_connectivity (bool, optional) – If True, use custom connectivity weights from a pre-specified file.

__str__()

Returns a string representation of the ModelConfig object, including details about the nodes, connectivity, simulation parameters, and GEV distribution parameters.

Returns:

A formatted string representation of the ModelConfig object.

Return type:

str

plot(plots_dir)

Plots (using _plot_properties()) the connectivity model’s distances (summed through the relay, if applicable) and normalized weights matrices using heatmaps.

Parameters:

plots_dir (pathlib.Path) – The directory where the plots are saved.

Raises:

AssertionError – If the plots directory does not exist.

_plot_properties(matrix, title, plots_dir, factor=1.0)

Helper method to plot a heatmap of a given matrix with specified properties.

Parameters:

• matrix (numpy.ndarray) – The matrix to be plotted as a heatmap.

• title (str) – The title for the plot, used to label the saved file.

• plots_dir (pathlib.Path) – The directory where the plots are saved.

• factor (float, optional) – A scaling factor applied to the matrix values (default is 1.0).

class macro_eeg_model.config.NodesProcessor(given_nodes, relay_station)

A class to process given brain regions into their corresponding indices in the Julich brain parcellation by finding the final generation children of the given nodes.

given_nodes

List of nodes to be processed.

Type:

list

relay_station

The relay station node, if any, that connects different brain regions.

Type:

str

_areas_dict

A dictionary mapping brain areas to their hierarchical structure using src.data_prep.areas_terminology_parser.AreasTerminologyParser.parse_into_dict().

Type:

dict

__init__(given_nodes, relay_station)

Initializes the NodesProcessor with the provided nodes, relay station, and whether to separate left and right brain nodes.

Parameters:

• given_nodes (list) – List of nodes to be processed.

• relay_station (str) – The relay station node, if any.

get_nodes_indices()

Processes the nodes and the relay station, if any, and retrieves their corresponding indices using _process_nodes().

Returns:

A tuple containing relay nodes, relay nodes indices, interaction nodes, and interaction nodes indices.

Return type:

tuple

_process_nodes(nodes)

Processes a list of nodes and retrieves their corresponding indices using _get_nodes_and_indices().

Parameters:

nodes (list) – List of nodes to be processed.

Returns:

A tuple containing the processed nodes and their indices.

Return type:

tuple

_get_nodes_and_indices(node)

Retrieves the final generation nodes and their corresponding indices for a given brain region (node). Uses _initialize_nodes_and_indices() to set up initial structures, _find_final_generation_children() to locate the final generation nodes, and _populate_nodes_indices() to assign indices based on the Julich brain parcellation.

Parameters:

node (str) – The name of the brain region (node) to retrieve indices for.

Returns:

A tuple containing:

• nodes: list of nodes corresponding to the brain region.

• nodes_indices: dictionary mapping each node to its corresponding indices.

Return type:

tuple

_initialize_nodes_and_indices(node)

Initializes the nodes and their corresponding indices, considering left and right brain separation.

Parameters:

node (str) – The node to initialize.

Returns:

A tuple containing the initialized nodes and their indices.

Return type:

tuple

_find_final_generation_children(dictionary, target, found=False)

Recursively finds the final generation children of a target node in the areas dictionary.

Parameters:

• dictionary (dict) – The dictionary containing hierarchical brain area mappings (initially _areas_dict).

• target (str) – The target node to find children for.

• found (bool, optional) – Whether the target node has been found (default is False).

Returns:

A list of final generation children nodes.

Return type:

list

_populate_nodes_indices(nodes_indices, children, node)

Populates the nodes indices with the corresponding Julich labels.

Parameters:

• nodes_indices (dict) – The dictionary to populate with node indices.

• children (list) – The list of child nodes to process.

• node (str) – The original node being processed.

Returns:

The populated nodes indices.

Return type:

dict

class macro_eeg_model.config.Parser(parser)

The Parser class is responsible for parsing the command line arguments and setting default values.

parser

The argument parser instance used to parse command line arguments.

Type:

argparse.ArgumentParser

_default_n

The default number of simulations to run.

Type:

int

_default_model_name

The default name of the model.

Type:

str

_default_nodes

The default brain areas where the nodes are placed.

Type:

str

_default_relay_station

The default brain area to use as a relay station.

Type:

str

_default_custom_connectivity

Indicates whether to use custom connectivity by default.

Type:

bool

_default_t_lags

The default lagged time in milliseconds.

Type:

int

_default_sample_rate

The default sample rate in Hz.

Type:

int

_default_t_secs

The default simulation time in seconds.

Type:

int

_default_t_burnit

The default number of seconds (burn-in) to delete for model convergence.

Type:

int

_default_noise_color

The default color of the noise.

Type:

str

_default_std_noise

The default standard deviation of the noise.

Type:

int

_default_dist_shape

The default shape parameter for the lag distributions.

Type:

float

_default_dist_scale

The default scale parameter for the lag distributions.

Type:

float

_default_dist_location

The default location parameter for the lag distributions.

Type:

float

_default_dist_trunc_percent

The default truncation percentile for the lag distributions.

Type:

float

__init__(parser)

Initializes the Parser with an argparse parser and loads the default values from model_params.yml configuration file in the configs data path (see src.utils.paths.Paths)

Parameters:

parser (argparse.ArgumentParser) – The argument parser instance used to parse command line arguments.

static _load_yaml(file_path)

Loads a YAML file from the specified path.

Parameters:

file_path (str or pathlib.Path) – The path to the YAML file to load.

Returns:

The contents of the YAML file as a dictionary.

Return type:

dict

parse_args()

Parses known arguments from the command line, validates them, and returns them as an argparse Namespace object.

Returns:

The parsed command line arguments.

Return type:

argparse.Namespace

_add_arguments()

Adds the command line arguments to the parser and sets their default values based on the loaded YAML configuration.

static _validate_args(args)

Validates the parsed command line arguments.

Parameters:

args (argparse.Namespace) – The parsed command line arguments.

Raises:

ValueError – If the parsed arguments are invalid.

static _parse_relay_station(relay_station_value: str)

Parses the relay station argument from the command line. If the provided value is “none”, it returns None; otherwise, it returns the string value.

Parameters:

relay_station_value (str) – The relay station value provided from the command line.

Returns:

The parsed relay station value, or None if “none” is provided.

Return type:

str or None

static _parse_nodes(nodes_str)

Parses a string into a list of nodes.

This method converts a semicolon-separated string of node names into a list of strings. For example: “node1; node2; node3” -> [“node1”, “node2”, “node3”].

Parameters:

nodes_str (str) – The semicolon-separated string of node names.

Returns:

A list of node names.

Return type:

list

Raises:

argparse.ArgumentTypeError – If the input string cannot be parsed into a valid list of nodes.