Analysis Runners

The runners module contains the core analysis pipelines used to identify and compare neuronal ensembles.

These functions can be executed:

  • From the graphical user interface

  • Directly from Python scripts

Each runner implements a complete analysis workflow, including:

  • Input validation

  • Algorithm selection

  • Execution

  • Result formatting

Module Reference

encore.runners.encore.run_example(input_data: dict, parameters: dict, code_folder_name='', include_answer=True, logger=None)

Run the example algorithm and generate dummy results for GUI integration.

This function serves as a reference implementation for new algorithms integrated into the ENCORE framework. It demonstrates the expected structure, logging behavior, parameter handling, result packing, and timing measurement required by the algorithm runner interface.

The function: - Logs input data structure and parameters - Measures execution time - Computes a simple parameter update based on user-selected options - Generates synthetic ensemble and neuronal activity data - Prepares an answer dictionary used by example plotting functions - Returns a standardized results dictionary consumed by the GUI

Algorithm developers should use this function as a template when implementing new runners.

Parameters:

  • input_data (dict[var_name] = numpy.ndarray) – Dict mapping variable name and data matrix provided by the pipeline. This example expects two keys ‘data_neuronal_activity’ and ‘data_dFFo’. Available variables are ‘data_neuronal_activity’, ‘data_dFFo’, ‘data_coordinates’ ‘data_stims’, ‘data_cells’, ‘data_behavior’. Each variable is expected to contain numpy matrix with shape (items, timepoints).

  • parameters (dict) – Dictionary of parameters defined in the algorithm configuration file and set via the GUI.

  • code_folder_name (str, optional) – Name of the algorithm code folder (optional, used for bookkeeping or logging).

  • include_answer (bool, optional) – Whether to include the answer field in the output, used for plotting example figures.

  • logger (function(str, str), optional) – Function to show the log of the function execution. This function should receive two strings as parameters, just like main.MainWindow.update_console_log. This function should receive two strings, the first one has the message and the second one the level. Defaults to None.

Returns:

Dictionary containing algorithm results, plotting data, updated parameters, execution time, and success status.

Return type:

dict

encore.runners.encore.run_ica(input_data, parameters, code_folder_name='Cell-Assembly-Detection', include_answer=True, logger=None)

Initializes and runs the MATLAB engine to execute the ICA algorithm on neural activity data. This function also handles MATLAB path setup and data conversion to MATLAB. At the end packs the results in the standard for ENCORE.

Parameters:

  • input_data (dict[var_name] = numpy.ndarray) – Dict mapping variable name and data matrix provided by the pipeline. This function expects only the key ‘data_neuronal_activity’ with binary neuronal activity. Available variables are ‘data_neuronal_activity’, ‘data_dFFo’, ‘data_coordinates’ ‘data_stims’, ‘data_cells’, ‘data_behavior’. Each variable is expected to contain numpy matrix with shape (items, timepoints).

  • parameters (dict) – Dictionary with parameters for the ICA algorithm.

  • code_folder_name (str, optional) – String with the name of the folder inside src/analysis that contains the MATLAB code for this function. This value must be specified in the YAML config file. Defaults to ‘Cell-Assembly-Detection’

  • include_answer (bool, optional) – Flag to indicate wether or not the original full answer of the algorithm. Defaults to True

  • logger (function(str, str), optional) – Function to show the log of the function execution. This function should receive two strings as parameters, just like main.MainWindow.update_console_log. This function should receive two strings, the first one has the message and the second one the level. Defaults to None.

Returns:

Dictionary with the results of the algorithm.

Return type:

dict

encore.runners.encore.run_pca(input_data, parameters, code_folder_name='NeuralEnsembles', include_answer=True, logger=None)

Initializes and runs the MATLAB engine to execute the PCA algorithm on neural activity data. This function also handles MATLAB path setup and data conversion to MATLAB. At the end packs the results in the standard for ENCORE.

Parameters:

  • input_data (dict[var_name] = numpy.ndarray) – Dict mapping variable name and data matrix provided by the pipeline. This function expects only the key ‘data_neuronal_activity’ with binary neuronal activity. Available variables are ‘data_neuronal_activity’, ‘data_dFFo’, ‘data_coordinates’ ‘data_stims’, ‘data_cells’, ‘data_behavior’. Each variable is expected to contain numpy matrix with shape (items, timepoints).

  • parameters (dict) – Dictionary with parameters for the PCA algorithm.

  • code_folder_name (str, optional) – String with the name of the folder inside src/analysis that contains the MATLAB code for this function. This value must be specified in the YAML config file. Defaults to ‘NeuralEnsembles’

  • include_answer (bool, optional) – Flag to indicate wether or not the original full answer of the algorithm. Defaults to True

  • logger (function(str, str), optional) – Function to show the log of the function execution. This function should receive two strings as parameters, just like main.MainWindow.update_console_log. This function should receive two strings, the first one has the message and the second one the level. Defaults to None.

Returns:

Dictionary with the results of the algorithm.

Return type:

dict

encore.runners.encore.run_sgc(input_data, parameters, code_folder_name='SGC', include_answer=True, logger=None)

Initializes and runs the MATLAB engine to execute the SGC algorithm on neural activity data. This function also handles MATLAB path setup and data conversion to MATLAB. At the end packs the results in the standard for ENCORE.

Parameters:

  • input_data (dict[var_name] = numpy.ndarray) – Dict mapping variable name and data matrix provided by the pipeline. This function expects only the key ‘data_dFFo’ with binary neuronal activity. Available variables are ‘data_neuronal_activity’, ‘data_dFFo’, ‘data_coordinates’ ‘data_stims’, ‘data_cells’, ‘data_behavior’. Each variable is expected to contain numpy matrix with shape (items, timepoints).

  • parameters (dict) – Dictionary with parameters for the SGC algorithm.

  • code_folder_name (str, optional) – String with the name of the folder inside src/analysis that contains the MATLAB code for this function. This value must be specified in the YAML config file. Defaults to ‘SGC’

  • include_answer (bool, optional) – Flag to indicate wether or not the original full answer of the algorithm. Defaults to True

  • logger (function(str, str), optional) – Function to show the log of the function execution. This function should receive two strings as parameters, just like main.MainWindow.update_console_log. This function should receive two strings, the first one has the message and the second one the level. Defaults to None.

Returns:

Dictionary with the results of the algorithm.

Return type:

dict

encore.runners.encore.run_svd(input_data, parameters, code_folder_name='SVD', include_answer=True, logger=None)

Initializes and runs the MATLAB engine to execute the SVD algorithm on neural activity data. This function also handles MATLAB path setup and data conversion to MATLAB. At the end packs the results in the standard for ENCORE.

Parameters:

  • input_data (dict[var_name] = numpy.ndarray) – Dict mapping variable name and data matrix provided by the pipeline. This function expects only the key ‘data_neuronal_activity’ with binary neuronal activity. Available variables are ‘data_neuronal_activity’, ‘data_dFFo’, ‘data_coordinates’ ‘data_stims’, ‘data_cells’, ‘data_behavior’. Each variable is expected to contain numpy matrix with shape (items, timepoints).

  • parameters (dict) – Dictionary with parameters for the SVD algorithm.

  • code_folder_name (str, optional) – String with the name of the folder inside src/analysis that contains the MATLAB code for this function. This value must be specified in the YAML config file. Defaults to ‘SVD’

  • include_answer (bool, optional) – Flag to indicate wether or not the original full answer of the algorithm. Defaults to True

  • logger (function(str, str), optional) – Function to show the log of the function execution. This function should receive two strings as parameters, just like main.MainWindow.update_console_log. This function should receive two strings, the first one has the message and the second one the level. Defaults to None.

Returns:

Dictionary with the results of the algorithm.

Return type:

dict

encore.runners.encore.run_x2p(input_data, parameters, code_folder_name='Xsembles2P', include_answer=True, logger=None)

Initializes and runs the MATLAB engine to execute the Xsembles2P algorithm on neural activity data. This function also handles MATLAB path setup and data conversion to MATLAB. At the end packs the results in the standard for ENCORE.

Parameters:

  • input_data (dict[var_name] = numpy.ndarray) – Dict mapping variable name and data matrix provided by the pipeline. This function expects only the key ‘data_neuronal_activity’ with binary neuronal activity. Available variables are ‘data_neuronal_activity’, ‘data_dFFo’, ‘data_coordinates’ ‘data_stims’, ‘data_cells’, ‘data_behavior’. Each variable is expected to contain numpy matrix with shape (items, timepoints).

  • parameters (dict) – Dictionary with parameters for the Xsembles2P algorithm.

  • code_folder_name (str, optional) – String with the name of the folder inside src/analysis that contains the MATLAB code for this function. This value must be specified in the YAML config file. Defaults to ‘Xsembles2P’

  • include_answer (bool, optional) – Flag to indicate wether or not the original full answer of the algorithm. Defaults to True

  • logger (function(str, str), optional) – Function to show the log of the function execution. This function should receive two strings as parameters, just like main.MainWindow.update_console_log. This function should receive two strings, the first one has the message and the second one the level. Defaults to None.

Returns:

Dictionary with the results of the algorithm.

Return type:

dict