macro_eeg_model.evaluation

This package contains the (power and coherence) evaluation functions to compare simulated EEG data against real EEG data.

Submodules

• macro_eeg_model.evaluation.coherence_computer
• macro_eeg_model.evaluation.evaluator
• macro_eeg_model.evaluation.fooof_tester
• macro_eeg_model.evaluation.peak_tester
• macro_eeg_model.evaluation.simulation_data_extractor

Classes

CoherenceComputer	A class responsible for computing the coherence between signals.
Evaluator	A class responsible for evaluating simulated EEG data .
PeakTester	A class responsible for testing the significance of peak power values compared to other frequency ranges.
SimulationDataExtractor	The SimulationDataExtractor class is responsible for extracting and processing simulation data.

Package Contents

class macro_eeg_model.evaluation.CoherenceComputer(fs, window_type='hann')

A class responsible for computing the coherence between signals.

fs

The sampling frequency of the signals.

Type:

int

_window_type

The type of window used for smoothing signals before coherence computation.

Type:

str

__init__(fs, window_type='hann')

Initializes the CoherenceComputer with the given sampling frequency and window type.

Parameters:

• fs (int) – The sampling frequency of the signals.

• window_type (str, optional) – The type of window to apply for smoothing the signals before coherence computation (default is ‘hann’).

compute_coherence_matched(sig1, sig2, smooth_signals=True)

Computes the coherence between two signals using _compute_coherence(), with an option to smooth the signals before computation using _smooth_signal().

Parameters:

• sig1 (numpy.ndarray) – The first signal array.

• sig2 (numpy.ndarray) – The second signal array.

• smooth_signals (bool, optional) – If True, applies a smoothing window to the signals before computing coherence (default is True).

Returns:

A tuple containing:

• positive_freqs (numpy.ndarray): The array of positive frequency values.

• positive_coherence (numpy.ndarray): The coherence values corresponding to the positive frequencies.

Return type:

tuple

Raises:

AssertionError – If the two signals do not have the same shape.

_compute_coherence(sig1, sig2)

Computes the coherence between two signals using their cross-spectrum and power spectra.

Parameters:

• sig1 (numpy.ndarray) – The first signal array with shape (nr_epochs, n_samples).

• sig2 (numpy.ndarray) – The second signal array with the same shape as sig1.

Returns:

A tuple containing:

• positive_freqs (numpy.ndarray): The array of positive frequency values.

• positive_coherence (numpy.ndarray): The coherence values corresponding to the positive frequencies.

Return type:

tuple

_smooth_signal(signal)

Applies a smoothing window to a signal.

Parameters:

signal (numpy.ndarray) – The input signal array to be smoothed.

Returns:

The smoothed signal.

Return type:

numpy.ndarray

class macro_eeg_model.evaluation.Evaluator

A class responsible for evaluating simulated EEG data . It computes metrics such as coherence and power spectra across different brain regions (nodes).

frequencies

The frequency range for evaluating the data ([0, 30] Hz).

Type:

list

simulation_data_extractor

An instance of the src.evaluation.simulation_data_extractor.SimulationDataExtractor class used to extract and process simulated EEG data.

Type:

SimulationDataExtractor

__init__()

Initializes the Evaluator class, setting up the frequency range and loading real and simulated data.

evaluate(plot_overview=True)

Evaluates and compares the coherence and power metrics using _evaluate_metric().

Parameters:

plot_overview (bool, optional) – If True, generates overview plots for the evaluated metrics; if False, generates individual plots for (pairs of) brain regions. (default is True).

_evaluate_metric(evaluation_func, desc, plot_overview, rows, cols, save_file_name)

A helper function to evaluate a specific metric (e.g., coherence or power) across nodes or node pairs.

Parameters:

• evaluation_func (function) – The function to evaluate the metric (_evaluate_coherence_node_pair() or _evaluate_power_node()).

• desc (str) – The description for the tqdm progress bar.

• plot_overview (bool) – If True, generates overview plots for the evaluated metrics; if False, generates individual plots for (pairs of) brain regions.

• rows (int) – The number of rows in the overview plot.

• cols (int) – The number of columns in the overview plot.

• save_file_name (str) – The file name for saving the overview plot.

_get_nodes(pairwise=False)

Generates nodes or node pairs for evaluation.

Parameters:

pairwise (bool, optional) – If True, generates pairs of nodes (for coherence evaluation), otherwise generates individual nodes (for power evaluation) (default is False).

Returns:

A tuple containing one or two nodes, depending on the value of pairwise.

Return type:

tuple

_evaluate_peaks(node, fig=None, ax=None, show_legend=True)

Evaluates the presence of alpha peaks (using _get_peaks()) and plots (using _plot_metric()) detrended power spectrum for a given node.

Parameters:

• node (str) – The name of the brain region to evaluate.

• fig (matplotlib.figure.Figure, optional) – The figure object for plotting (default is None).

• ax (matplotlib.axes.Axes, optional) – The axis object for plotting (default is None).

• show_legend (bool, optional) – If True, shows the legend on the plot (default is True).

_evaluate_fooof(node, fig=None, ax=None, show_legend=True)

Evaluates the presence of peaks (using _get_fooof_peaks()) and plots (using _plot_metric()) the peaks.

Parameters:

• node (str) – The name of the brain region to evaluate.

• fig (matplotlib.figure.Figure, optional) – The figure object for plotting (default is None).

• ax (matplotlib.axes.Axes, optional) – The axis object for plotting (default is None).

• show_legend (bool, optional) – If True, shows the legend on the plot (default is True).

_evaluate_power_node(node, fig=None, ax=None, show_legend=True)

Evaluates (using _get_simulated_power()) and plots (using _plot_metric()) the power spectrum for a given node.

Parameters:

• node (str) – The name of the brain region to evaluate.

• fig (matplotlib.figure.Figure, optional) – The figure object for plotting (default is None).

• ax (matplotlib.axes.Axes, optional) – The axis object for plotting (default is None).

• show_legend (bool, optional) – If True, shows the legend on the plot (default is True).

_evaluate_coherence_node_pair(node1, node2, fig=None, ax=None, show_legend=True)

Evaluates (using _get_simulated_coherences()) and plots (using _plot_metric()) the coherence between a pair of nodes.

Parameters:

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

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

• fig (matplotlib.figure.Figure, optional) – The figure object for plotting (default is None).

• ax (matplotlib.axes.Axes, optional) – The axis object for plotting (default is None).

• show_legend (bool, optional) – If True, shows the legend on the plot (default is True).

_get_fooof_peaks(node)

Computes the peaks in the power spectrum for a given node using FooofTester.

Parameters:

node (str) – The name of the brain region for which to compute the peaks.

Returns:

A tuple containing:

• frequencies (numpy.ndarray): The array of frequencies.

• all_binary_peaks (dict): A dictionary of binary peaks for each simulation, keyed by simulation name.

Return type:

tuple

_get_peaks(node)

Computes the peaks in the power spectrum for a given node using PeakTester.

Parameters:

node (str) – The name of the brain region for which to compute the peaks.

Returns:

A tuple containing:

• frequencies (numpy.ndarray): The array of frequencies.

• powers (dict): A dictionary of simulated power spectra, keyed by simulation name.

• p_values (dict): A dictionary of p-values for the peak test, keyed by simulation name.

• test_names (dict): A dictionary of test names for the peak test, keyed by simulation name.

Return type:

tuple

_get_simulated_power(node)

Retrieves the simulated power spectrum for a given node.

Parameters:

node (str) – The name of the brain region for which to retrieve the simulated power spectrum.

Returns:

A tuple containing:

• frequencies (numpy.ndarray): The array of frequencies.

• powers (dict): A dictionary of simulated power spectra, keyed by simulation name.

Return type:

tuple

_get_simulated_coherences(node1, node2)

Computes the simulated coherence between a pair of nodes for each simulation using src.simulation.coherence_computer.CoherenceComputer.compute_coherence_matched() .

Parameters:

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

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

Returns:

A tuple containing:

• frequencies (numpy.ndarray): The array of frequencies for coherence.

• coherences (dict): A dictionary of simulated coherence values, keyed by simulation name.

Return type:

tuple

_plot_metric(title, sim_frequencies, sim_data, plot_type='line', fig=None, ax=None, show_legend=True, y_label=None, xlim=None, ylim=None, file_label=None, label_addons=None)

Plots a metric (e.g., coherence or power) of data using _plot_simulated_data().

Parameters:

• title (str) – The title of the plot.

• sim_frequencies (numpy.ndarray) – The array of frequencies for the simulated data.

• sim_data (dict) – The simulated data (e.g., power or coherence) to plot, keyed by simulation name.

• plot_type (str, optional) – The type of plot to create (default is “line”). Currently, “line”, “scatter”, “mean_std” are supported.

• fig (matplotlib.figure.Figure, optional) – The figure object for plotting (default is None).

• ax (matplotlib.axes.Axes, optional) – The axis object for plotting (default is None).

• show_legend (bool, optional) – If True, shows the legend on the plot (default is True).

• y_label (str, optional) – The label for the y-axis (default is None).

• xlim (list, optional) – The x-axis limits for the plot (default is None).

• ylim (list, optional) – The y-axis limits for the plot (default is None).

• file_label (str, optional) – The file name label for saving the plot (default is None).

• label_addons (dict, optional) – The dictionary of label addons to append to the name of the data (default is None).

static _plot_simulated_data(ax, frequencies, data, label_addons, plot_type='line')

Plots the simulated EEG data on a given axis.

Parameters:

• ax (matplotlib.axes.Axes) – The axis object for plotting.

• frequencies (numpy.ndarray) – The array of frequencies for the simulated data.

• data (dict) – The simulated data (e.g., power or coherence) to plot, keyed by simulation name.

• label_addons (dict) – The dictionary of label addons to append to the name of the data.

• plot_type (str, optional) – The type of plot to create (default is “line”). Currently, “line”, “scatter”, “mean_std” are supported.

static _get_ax(ax, rows, cols, i)

Helper function to get the appropriate subplot axis.

Parameters:

• ax (numpy.ndarray) – The array of axis objects for subplots.

• rows (int) – The number of rows in the subplot grid.

• cols (int) – The number of columns in the subplot grid.

• i (int) – The index of the current plot.

Returns:

The appropriate axis object for the current subplot.

Return type:

matplotlib.axes.Axes

class macro_eeg_model.evaluation.PeakTester(frequencies, peaks_range, others_range)

A class responsible for testing the significance of peak power values compared to other frequency ranges.

frequencies

The array of frequencies corresponding to the power spectrum.

Type:

numpy.ndarray

peaks_range

The range of frequencies where peaks are expected.

Type:

tuple

others_range

The range of frequencies where other values are expected.

Type:

tuple

powers

The epoched power spectrum of the simulated EEG data.

Type:

list

peak_values

The mean power values in the peak range for each epoch.

Type:

list

other_values

The mean power values in the other range for each epoch.

Type:

list

__init__(frequencies, peaks_range, others_range)

Initializes the PeakTester class with the provided frequency ranges.

Parameters:

• frequencies (numpy.ndarray) – The array of frequencies corresponding to the power spectrum.

• peaks_range (tuple) – The range of frequencies where peaks are expected.

• others_range (tuple) – The range of frequencies where other values are expected.

compute_test_result(simulation_name, epoched_powers)

Computes the statistical test result for the peak power values compared to other frequency ranges.

Parameters:

• simulation_name (str) – The name of the simulation. (should include “pink” if the data was simulated with pink noise)

• epoched_powers (list) – The epoched power spectrum of the simulated EEG data.

Returns:

A tuple containing:

• frequencies (numpy.ndarray): The array of frequencies corresponding to the power spectrum.

• mean_power (numpy.ndarray): The mean power spectrum across epochs of the simulated EEG data.

• p_value (float): The calculated p-value.

• test_name (str): The name of the statistical test used.

Return type:

tuple

_separate_peaks(power)

Separates the power values in the peak and other frequency ranges.

Parameters:

power (numpy.ndarray) – The power spectrum of the simulated EEG data.

_detrend_data(powers, is_pink)

Detrend the pink noise in the power spectrum by fitting a power-law trend and removing it.

Parameters:

• powers (numpy.ndarray) – The power spectrum of the simulated EEG data.

• is_pink (bool) – A flag indicating whether the data was simulated with pink noise.

Returns:

A tuple containing:

• non_zero_freqs (numpy.ndarray): The array of non-zero frequencies.

• flattened_powers (numpy.ndarray): The corresponding detrended power spectrum

Return type:

tuple

_choose_and_run_test(paired=True)

Automatically selects and runs the correct statistical test based on data characteristics.

Parameters:

paired (bool) – A flag indicating whether the data is paired or independent.

Returns:

A tuple containing:

• t_stat (float): The calculated t-statistic.

• p_value (float): The calculated p-value.

• test_name (str): The name of the statistical test used.

Return type:

tuple

class macro_eeg_model.evaluation.SimulationDataExtractor

The SimulationDataExtractor class is responsible for extracting and processing simulation data. It organizes the data by nodes and simulations, allowing for easy access to both raw and processed data.

nodes

An array of node names used in the simulations.

Type:

numpy.ndarray

simulation_names

A list of simulation names.

Type:

list

sample_rates

A dictionary mapping simulation names to their corresponding sample rates.

Type:

dict

simulations_data_per_node

A dictionary organizing the processed simulation data by node.

Type:

dict

simulations_power_per_node

A dictionary organizing the processed power spectra by node.

Type:

dict

simulations_epoched_power_per_node

A dictionary organizing the processed epoched power spectra by node.

Type:

dict

__init__()

Initializes the SimulationDataExtractor by loading and processing the simulation data using methods from this class.

_get_simulations_data_per_node(processed_simulations_data)

Organizes the processed simulation data by node and then simulation name.

Parameters:

processed_simulations_data (dict) – The dictionary containing processed simulation data organized by simulation name and then node.

Returns:

A dictionary organizing the simulation data by node and then simulation name.

Return type:

dict

_get_simulations_epoched_power_per_node(processed_simulations_epoched_power)

Organizes the processed epoched power spectra by node and then simulation name.

Parameters:

processed_simulations_epoched_power (dict) – The dictionary containing processed epoched power spectra organized by simulation name and then node.

Returns:

A dictionary organizing the epoched power spectra by node and then simulation name.

Return type:

dict

_get_processed_simulations_epoched_power(simulations_info, epoch_len=1000)

Processes and organizes the epoched power spectra data by simulation name and then node.

Parameters:

• simulations_info (dict) – A dictionary containing simulation information objects.

• epoch_len (int, optional) – The length of each epoch in milliseconds (default is 1000).

Returns:

A dictionary organizing the processed epoched power spectra data by simulation name and then node.

Return type:

dict

_get_simulations_power_per_node(processed_simulations_power)

Organizes the processed power spectra by node and then simulation name.

Parameters:

processed_simulations_power (dict) – The dictionary containing processed power spectra organized by simulation name and then node.

Returns:

A dictionary organizing the power spectra by node and then simulation name.

Return type:

dict

_get_processed_simulations_power(simulations_info)

Processes and organizes the power spectra data by simulation name and then node.

Parameters:

simulations_info (dict) – A dictionary containing simulation information objects.

Returns:

A dictionary organizing the processed power spectra data by simulation name and then node.

Return type:

dict

_get_processed_simulations_data(simulations_info)

Processes and organizes the raw simulation data by simulation name and then node.

Parameters:

simulations_info (dict) – A dictionary containing simulation information objects.

Returns:

A dictionary organizing the processed simulation data by simulation name and then node.

Return type:

dict

_get_simulations_info()

Loads simulation information from saved files in the directories within the output path (see src.utils.paths.Paths) using src.simulation.simulation_info.SimulationInfo.load_simulation_info(). and checks for consistency in node names.

Returns:

A tuple containing:

• simulations_info (dict): A dictionary of SimulationInfo objects keyed by simulation name.

• sample_rates (dict): A dictionary of sample rates keyed by simulation name.

Return type:

tuple

Raises:

AssertionError – If the nodes in any simulation do not match the expected node names.

static _get_surface_nodes(nodes)

Returns the surface nodes from the given list of nodes. Currently, the surface nodes are all nodes except the thalamus.

Parameters:

nodes (list) – A list of node names.

Returns:

A list of surface node names.

Return type:

list