Protocol for identifying and comparing neuronal ensembles using different algorithms within a graphical user interface

Summary

Neuronal ensembles are groups of neurons with coordinated activity that are related to a specific brain function. Here, we present a protocol to identify and compare neuronal ensembles from neuronal activity data obtained through two-photon microscopy or electrophysiological recordings using a unified graphical user interface (Ensembles Comparison and Recognition [ENCORE]). We describe steps for installing ENCORE, data loading, neuronal ensemble identification, inspecting results, and comparison of five different algorithms. We then detail procedures for evaluating functional relevance of identified neuronal ensembles.

For complete details on the use and execution of this protocol, please refer to Carrillo-Reid.¹

Graphical abstract

Highlights

• •Graphical user interface to identify neuronal ensembles with different algorithms
• •Neuronal ensemble identification from optical or electrophysiological recordings
• •Identification of behaviorally relevant neuronal ensembles
• •Incorporation of custom-defined ensemble-detection algorithms

Publisher’s note: Undertaking any experimental protocol requires adherence to local institutional guidelines for laboratory safety and ethics.

Neuronal ensembles are groups of neurons with coordinated activity that are related to a specific brain function. Here, we present a protocol to identify and compare neuronal ensembles from neuronal activity data obtained through two-photon microscopy or electrophysiological recordings using a unified graphical user interface (Ensembles Comparison and Recognition [ENCORE]). We describe steps for installing ENCORE, data loading, neuronal ensemble identification, inspecting results, and comparison of five different algorithms. We then detail procedures for evaluating functional relevance of identified neuronal ensembles.

Before you begin

Recent advances on simultaneous recordings of hundreds of neurons have allowed the development of complex and accurate models of brain functions. Some of these functions can be explained by groups of neurons with coordinated activity within a defined time window, known as neuronal ensembles. However, a standardized method to identify these neuronal ensembles across different research groups is still lacking. Various approaches have been proposed to find neuronal ensembles, each based on different principles and tested in different animal models and brain regions. Among the different methods are:

Identification by Singular Value Decomposition (SVD) in two-photon calcium recordings of the mouse visual cortex, described by Carrillo-Reid et al.² and Velazquez-Contreras & Carrillo-Reid.³ Identification by Independent Component Analysis (ICA), proposed by Lopes-dos-Santos et al.⁴ in the rat hippocampus using single-unit recordings. Identification using Xsembles2P, proposed by Pérez-Ortega et al.⁵ in volumetric two-photon recordings of the mouse visual cortex. Identification based in Similarity Graph Clustering (SGC), proposed by Avitan et al.⁶ and implemented in calcium imaging data from the zebrafish optic tectum. Identification based in principle Component Analysis (PCA), proposed by Herzog et al.⁷ using spike train data from multi-electrode array recordings of ganglion cells.

Although these methods are useful in different scenarios, they may be difficult and time consuming to implement individually. The specific implementation of each method requires different formatting for the input data and produces different outputs, that complicates the comparison of results to select the best approach. A unified method for the identification of neuronal ensembles would increase the availability of these techniques to more researchers. If such standardization is implemented through a graphical user interface (GUI) that includes multiple visualizations, its accessibility would further increase, reaching even non-programmer users. ENCORE (Ensembles Comparison and Recognition) paves the way towards a more standardized approach for identifying neuronal ensembles and understanding their relevance in behavior and cognition by providing a standardized and extensible platform.

Innovation

ENCORE provides a unified graphical user interface (GUI) for identifying neuronal ensembles using multiple validated protocols within the same platform, enabling direct comparison between ensembles found by different analysis techniques. The platform facilitates evaluation of each method’s performance and the behavioral relevance of the resulting ensembles, while its modular and extensible architecture allows users to run analyses programmatically through a Python API and incorporate new ensemble-identification algorithms with minimal effort.

Hardware preparation

Timing: <5 min

This section provides a reference for the required hardware specifications for the computer running ENCORE.

• 1.Prepare a computer with at least a quad-core processor and at least 16Gb of RAM.

Note: The hardware needed may vary depending on the dataset size and specific algorithms used. It is recommended to use a screen at least 1280x860 for full visualization of the GUI buttons and visualizations. This pipeline has been tested on Windows systems, and distributions of Linux like Ubuntu and Debian. ENCORE has been tested in Python from 3.9 to 3.12. The protocol has been tested on both high-performance workstations and standard office machines.

Software preparation

Timing: <10 min

This section provides a guide for installing and verifying the installation of ENCORE.

• 2.Install MATLAB in the target machine.

Note: Use a modern version of MATLAB, at least from R2021b and above, as these versions are also compatible with recent version of Python, from version 3.9. If available, install MATLAB R2022b or above to use Python 3.10, that may also be used with MATLAB R2025a.

• 3.
  Identify the compatible Python version to use with the installed MATLAB instance.

  • a.
    Go to the official documentation of “Versions of Python Compatible with MATLAB Products by Release” by MathWorks.
  • b.
    Identify your installed MATLAB version in the table and the supported Python versions.

Note: ENCORE runs the GUI and ensemble analysis using Python code while most of the analysis algorithms use MATLAB as the source code. For this reason, ENCORE requires compatible versions of MATLAB and Python to ensure proper communication between the two environments.

Optional: Identify the compatible Python and MATLAB versions by using the table available in the “installation” section of the ENCORE online documentation.

Note: ENCORE has been tested with Python 3.9 and above, so in case of using a MATLAB version before R2020b it is highly recommended to update.

• 4.
  Install the necessary MATLAB toolboxes using the Add-Ons browser:

  • a.
    Install “Parallel Computing Toolbox”.
  • b.
    Install “Statistics and Machine Learning Toolbox”.
  • c.
    Install “Curve Fitting Toolbox”.
• 5.Create a conda environment called “encore” with Python version 3.10 using the command:

> conda create -n encore python=3.10

> conda activate encore

CRITICAL: Change the version and the name according to your needs. The second command activates the environment.

Note: ENCORE is implemented in Python and runs natively without requiring MATLAB. MATLAB interoperability is optional and only necessary when users enable algorithms implemented in MATLAB.

Note: We recommend installing ENCORE in an isolated Python virtual environment to avoid dependency conflicts. This can be achieved using standard tools such as venv or conda/miniconda.

• 6.Install encore by running:

> pip install encore-toolkit

Note: ENCORE is distributed as a standard Python package via PyPI under the name encore-toolkit and can be installed using a single pip command. This installation provides the full graphical interface and Python-based analysis pipeline.

• 7.Verify the installation of the package by running the following command in the console, a version number should appear:

> encore --version

Note: Upon launch, ENCORE automatically reports which algorithms are available based on the current environment and provides informative messages if optional dependencies are missing.

• 8.
  Install the MATLAB engine for Python using pip.

  • a.
    Verify the supported MATLAB engine version for your MATLAB and Python setup.
  • b.
    Install the specific MATLAB engine version using pip.

Note: Installation of the MATLAB Engine for Python follows MathWorks prescribed procedure and depends on the user’s installed MATLAB and Python versions. As this process is external to ENCORE, detailed, version-specific instructions and a compatibility table are provided in the online documentation.

Note: To install the MATLAB engine for MATLAB 2023a and Python 3.10 run:

> pip install matlabengine==9.14.7

Alternatives: Locate and change the current directory in the terminal to the path of your MATLAB installation with the ENCORE environment activated. In this example the MATLAB version that is going to be used is the R2023a. If more than one MATLAB installation is available in the machine it is possible to select the version that you want to connect with the Python environment. For most MATLAB windows installations this can be done by typing:

> cd C:∖Program Files∖MATLAB∖R2023a∖extern∖engines∖python

> python -m pip install .

CRITICAL: These commands usually require an elevated terminal to be executed properly. Make sure that the terminal has administrator privileges, either by running “sudo” before the command in Linux systems or running the environment from an elevated terminal in windows.

• 9.Launch the GUI by running:

> encore

Alternatives: It is also possible to launch the GUI running:

> python -m encore

Note: Administrative privileges are no longer needed to activate the ENCORE environment and launch the GUI.

• 10.Prepare a matrix with the activity of the neurons over time and shape [N, T] for N neurons and T time points.

Note: ENCORE may use up to 6 different variables to perform analysis and visualizations. In short, each variable should be a matrix, of number of elements by time samples.

CRITICAL: The neuronal activity can be of two different types. “dFFo/FFo”: This variable should be a matrix with shape [N, T], showing the fluorescence of each neuron over time. This is used only for visualization purposes except for the SGC algorithm, which needs this variable to identify the ensembles. “Binary cell activity”: Key variable for the SVD, ICA, PCA and Xsembles2P algorithms. This should be a binary matrix with shape [N, T] showing the activity of the neurons over time, where non-zero values identify a neuron being active in that time bin.

Optional: Prepare matrices with data from other stimulation and behavioral paradigms to evaluate the functional relevance of the identified ensembles.

Note: The stimulation and behavioral matrices should have the shape of number of distinct elements by time samples. Showing the presence of stimulation or behavior at each point in time. Stimulation matrix: This should be a [S, T] matrix, showing the presence of each stimulus over time. Nonzero values are considered as that stimulus being presented in that time bin. Cells matrix: Matrix with shape [N, T] showing the exogenous activation of each cell in time. This variable is used to identify specific neurons in the analysis, e.g. opto-stimulated neurons. Nonzero values are considered as that neuron being active in that time bin. Behavior matrix: Matrix with shape [B, T] showing the value of different behaviors in each time point. Each behavior can be a binary array for presence or absence of such behavior or a continuous array showing other behavior as run speed.

Optional: Include location data for visualization as a [N, 2] or [N, 3] matrix showing the coordinates of each cell.

Note: If a larger coordinates matrix is loaded, only the first 2 columns of the first dimension will be considered. This is only for visualization purposes.

Note: In the definition of the shape of each matrix, T stands for number of timepoints or samples, N for number of neurons, S for number of different stimulus and B for number of different behaviors.

Key resources table

REAGENT or RESOURCE	SOURCE	IDENTIFIER
Deposited data
Synthetic example data	This paper	https://github.com/rivelco/ENCORE/tree/main/examples
ENCORE online documentation	This paper	https://rivelco.github.io/ENCORE/
Software and algorithms
encore-toolkit	This paper	https://github.com/rivelco/ENCORE
MATLAB 2021b or greater	MathWorks	https://www.mathworks.com/products/matlab.html
MATLAB Parallel Computing Toolbox	MathWorks	https://www.mathworks.com/products/parallel-computing.html
MATLAB Statistics and Machine Learning Toolbox	MathWorks	https://www.mathworks.com/products/statistics.html
MATLAB Curve Fitting Toolbox	MathWorks	https://www.mathworks.com/products/curvefitting.html
Python 3.10 (recommended) or greater	Python Software Foundation	https://www.python.org/downloads/
SVD	Carrillo-Reid et al.2	https://github.com/hanshuting/SVDEnsemble
ICA	Lopes-dos-Santos et al.4	https://github.com/tortlab/Cell-Assembly-Detection
PCA	Herzog et al.7	https://github.com/brincolab/NeuralEnsembles
SGC	Avitan et al.6	https://github.com/GoodhillLab/neural-assembly-detection/
Xsembles2P	Pérez-Ortega et al.5	https://github.com/PerezOrtegaJ/Xsembles2P
Other
Tested operating system	Windows 10	https://www.microsoft.com/en-us/software-download/windows10
Tested operating system	Windows 11	https://www.microsoft.com/en-us/software-download/windows11
Tested operating system	Ubuntu 18.04 LTS	https://releases.ubuntu.com/
Tested operating system	Ubuntu 20.04 LTS	https://releases.ubuntu.com/
Tested operating system	Ubuntu 24.04 LTS	https://releases.ubuntu.com/
Tested operating system	Debian 12.0	https://www.debian.org/distrib/
Tested operating system	Debian 13.0	https://www.debian.org/distrib/

Step-by-step method details

Execute ENCORE and general layout

Timing: <5 min

In this section we describe how to launch the ENCORE interface and the general layout of the GUI.

• 1.
  Execute ENCORE.

  • a.
    Activate the environment with ENCORE installed.
  • b.
    Launch the GUI with the command:

> encore

Note: It is recommended to escalate the GUI window to the desired final size at the beginning of the analysis session. Even when it is possible to make changes in the size window at any point during runtime, maintaining a consistent window size throughout the analysis is better for the visualizations.

Note: There are some key elements in the GUI to consider during the general use of ENCORE. In the superior region of the GUI are the main tabs of the software. Use these sections to navigate among the different steps of the pipeline, from loading the data, to running ensembles identification algorithms, visualizing and saving the results. In the central section lies the body of each analysis step. In general, for the ensembles algorithms at the left is the parameter tunning panel, and at the right you can find tabs for visualizing the results and steps. For the visualization and other ensemble's analysis, there are panels at the left and top for selecting the desired result to visualize and relevant visualizations in the middle.

Note: At the bottom of the main window, there is a log for the entire software. This log provides useful information regarding the current step or process running. Also, using a color-based encoding, you can identify different types of events, such as notifications or simple logs in black, completed processes in green, warnings in yellow and errors in red. Given the nature of the communication between MATLAB and Python, some logs cannot be displayed in an efficient manner in this log. Make use of the same terminal from where ENCORE is running to know more about the underlying processes running. Some errors may be notified in the GUI with general descriptions, but more detail is provided in the terminal.

Load the data

Timing: <5 min

Here, we describe steps for loading files into the GUI, selecting the desired datasets to use for the analysis and how to perform some modifications to the data.

• 2.
  Load the file containing your data.

  • a.
    Go to the “Load data” tab in the main window (Figure 1A).
  • b.
    Click in the “Open file” button.
  • c.
    Navigate your file system and open the file containing your data.

Note: To facilitate familiarization with the interface and verification of a correct installation, the ENCORE repository includes several lightweight example datasets in the examples/ directory. These datasets are provided in multiple supported formats (.hdf5, .mat, and.npz) and contain synthetic neuronal activity designed to mimic common coactivation patterns observed in ensemble analyses. Users may load these files directly into the GUI to follow the steps described below and confirm that data loading, visualization, and analysis behave as expected.

Note: The button “Open file”, opens a new window for loading the files. It is possible to load data from a variety of file sources, as “mat”, “pkl”, “h5”, “nwb”, “npz” and “csv”. It only is possible to load one file at the time, but load variables from different files in the same session if necessary.

Note: In ENCORE, the user's data can be loaded just once, and all the subsequent analysis can be done using the same data.

Note: The contents of the file will be displayed in the “File structure preview” section of the same tab (Figure 1B). Here, many different data structures are supported, from Python, MATLAB and h5 based files. It is possible to browse each variable to get to the desired sections of the database. For Python dictionaries and h5 based files such as NWB, the groups and dictionaries would be loaded as a tree, where it is possible to see the name of each variable, the key of each element and the final matrix or dataset. This can also be done in MATLAB with cell structures or dictionaries.

• 3.Click in the name of the matrix or dataset that contains the data to be loaded to validate the selected variable as a valid input matrix for ENCORE. troubleshooting 1.

Note: Every variable in the loaded file is categorized automatically after loading a file. After the file has been loaded, it is enough to click in a variable to recognize the variable as valid or not for ENCORE.

Note: In the lower part of the “File structure preview” another field will display a summary of the currently selected variable. Only datasets and matrices are allowed to be assigned to the internal variables of ENCORE. In this preview you verify the selected dataset shape.

• 4.
  Assign the selected validated variable from the loaded database to one of the ENCORE analysis variables.

  • a.
    Go to the “Set selected variable as” panel at the bottom of the “File structure preview”.
  • b.
    Click on the button with the name of the variable to assign it.

Note: If the selected variable meets the criteria for a specific ENCORE variable the corresponding button will be enabled. By clicking this button, the selected variable from the file will be loaded to the computer's memory and assigned to the selected variable in ENCORE.

Note: If necessary, remove an assigned variable by using the “Clear” button below each variable. The name of the variable loaded for each ENCORE variable is confirmed below the “Clear” button with italic font. If no variable is loaded, then the confirmation legend will show “Nothing”. It is also possible to replace a variable by simply clicking again the assign button with another selected variable.

Note: After each variable is loaded, a pre-visualization will appear in the “Input data preview” panel at the right of the same window (Figure 1C). Use that panel and the axes labels to verify that the dataset is being interpreted in the right way by ENCORE. If the axes are inverted for any selected database, use the “Edit variable” section, as will be explained below. If necessary, alternate the visualization of any loaded variable by using the buttons in the upper region of this section.

• 5.Edit the loaded variables if needed.

Note: The same GUI can perform quick editing to the loaded variables with the tools in the “Edit variable” panel, below the data pre-visualization panel. These edits affect the dataset currently being visualized, not only the visualizations.

Optional: Possible edits for each variable include “Transpose dataset”: This transposes the selected variable. It is useful for fixing inverted axes of the loaded datasets. “Bin”: Specify the bin size in terms of time points and the bin method, where “Sum” makes a sum of the specified bins number and “Mean” takes the average of those bins. The binning is performed once the “Bin” button is clicked. This procedure affects only the time axis, as identified in the visualization. “Trim matrix”: This function allows the user to preserve only a specific contiguous block of the dataset, for the specified axes. This is done in a 0-based index. To include the first element in the time axis you must set the “start” variable to 0. The extraction is performed once the button “Trim matrix” is clicked.

Note: Moving out of the “Load data” tab will trigger a validation process for the data, to ensure the correct interpretation of the loaded data, for example, to check if the number of neurons in the dFFo matrix corresponds with the binary activation matrix. If the data is not consistent then a warning will be raised in the logs box.

Note: Assign a specific label or name to the elements of the selected matrix using the “Label elements” tab in the editing tabs. This assignation occurs for the non-time axis. This function is useful for naming stimulus, behaviors or even cells. For this, use the table generated on this tab. The first column of the table shows the current name of the element, which by default is the index of the element in the matrix, in a 0-based indexing. In the “Label” column it is possible to assign any name for the specified element. Once the labels are assigned, use the “Save labels” button to save your changes. Only the modified elements will show the label instead of the index. The labels can be removed entirely and go back to the default index-based naming by using the “Delete all the labels” button. It is recommended to do this labeling process at the beginning of the analysis session, to include the specified names in all the plots and visualizations. However, it is possible to assign and/or modify these labels at any point of the analysis session, although refreshing of the visualizations may be necessary to load the new labels.

Figure 1.

Load the data and modify variables

(A) “Load data” tab in the general tabs of the GUI used to navigate between data loading, ensembles identification algorithms, results inspections, comparisons and results saving.

(B) Structure of the loaded file where the variable’s structure is shown as an interactive tree. In the lower part of the section is a variable description box. Atthe bottom of the section lies the buttons for assigning the selected variable from the file to one of the internal variables of ENCORE.

(C) Variable previsualization panel with possible editing options at the bottom of the section.

Run analysis to identify neuronal ensembles

Timing: 5–30 min

In this step we describe the general process of running an algorithm, tuning parameters and visualizing the results.

• 6.Go to the tab “ENCORE algorithms” to review the available algorithms.

Note: The execution of the included algorithms follows the same principle. The left panel provides information about the analysis and specifies the parameters for the execution. On the top region is specified the necessary data to run the analysis, usually the Binary Neuronal Activity. Once the variable has been selected the label “Loaded” will be shown.

• 7.Use the panel in the left section of each algorithm tab to set the parameters to be used for each analysis (Figure 2A).

Note: The algorithms parameters have a default value as recommended in the original paper for each one but may be changed accordingly to your needs.

Note: The “Load default values” button allows an easy retrieval on the default parameters. The name of the parameters preserves the names defined by the original authors, so it is easy to track the definition and use of such parameters across different sources.

Note: By hovering the editable field of each parameter for two seconds, a help box will appear to briefly show the definition and use of each parameter. Parameter tooltips are intended to assist with interface usage. Further reading of the original article describing the method may be needed to fully understand the use and relevance of each parameter.

Note: In some cases, a “Parallel processing” option is included, which leverages the use of the “parallel pool” from MATLAB to increase the speed of the analysis. This parallelization may be implemented separately if the original algorithm was not parallelized. However, consider that the creation of a parallel pool in MATLAB requires some time, so while the parallel processing option may speed up the analysis, it is important to consider that the creation of the pool itself may consume from 30 seconds to 1 minute. It is advisable to use this option only in larger datasets, where the time saved by parallel processing overcomes the cost of the creation of the pool.

• 8.Run the ensemble identification analysis using the “Run analysis” button in the bottom section of the left panel.

Note: If a mandatory parameter is left blank the program will select the default value for such parameter and fill the blank space for you. In algorithms where mandatory parameters are automatically calculated, then the program will calculate the appropriate parameters and fill the blanks.

Note: At the very bottom of the left panel, there is a text box with the paper and sources of the original publication of the algorithm. Use these references to further understand the use of each algorithm.

• 9.Review the process and result of the algorithm using the plots tabs in the right section. troubleshooting 2.

Note: When possible, the plots of each algorithm will be similar to the plots on the original papers, for better understanding and interpretation (Figure 2B).

• 10.Modify the selected parameters and rerun the algorithm if necessary.

Note: Once an algorithm is running, a new thread in the computer will create a new MATLAB instance where the selected analysis will run. This process is executed in parallel with the GUI so it is possible to keep using the GUI during the execution. Also, it is possible to execute different analysis at the same time, and these different processes will not interfere with each other as they are running in different MATLAB instances.

• 11.During the execution, check the GUI’s log that will show different messages about the state of the analysis (Figure 2C). troubleshooting 3.

Note: The Python console running in the background will show more detailed information about the steps of each algorithm in real time (Figure 2D).

Note: If a problem arises during the execution of an ensemble identification analysis, ENCORE reports it through a structured error-handling system. Detailed diagnostic messages are printed to the Python console, while a concise, user-oriented notification is displayed in the GUI log panel. Errors are explicitly classified according to their origin (algorithm execution or result plotting), allowing users to distinguish between failures in the underlying method and issues related to visualization. Importantly, these errors are constrained to the individual analysis being executed and do not affect the overall stability of the GUI. As a result, the same dataset may be analyzed with multiple algorithms, where some analyses may fail while others complete successfully.

CRITICAL: ENCORE will report when the algorithm has not identified any ensembles. If this is the case, the plots for such algorithm will be loaded up to the point where the execution fails. This is useful if the program has stopped at some point for the parameters given to the analysis. For example, the PCA algorithm needs some thresholds for identifying ensembles. The algorithm may run properly but after applying the thresholds may end up with no more data to process. The plots will reflect this point in execution, so you can visualize the source of the problem and adjust the parameters accordingly.

Figure 2.

Execution of the neuronal identification algorithms

(A) Panel showing the parameters available for modification for the selected algorithm. In the figure the parameters for the SVD algorithm are shown. Note the “Load default values” and the “Run analysis” buttons at the bottom.

(B) Significative plots for the selected algorithm. The number of available tabs for this panel varies for each method.

(C) ENCORE log showing general information related to the execution of the algorithms. Informative logs are shown in black font and completed in green, errors in red and warnings in yellow.

(D) The Python console shows more details about the execution of each algorithm. Inthis case, showing an error during the MATLAB execution.

Visualize the results with detail

Timing: <5 min

In this section we describe in depth visualization options for the results of each algorithm.

• 12.Inspect the results of every ensemble and algorithm in the tab “Ensembles visualizer” once at least one analysis has been executed (Figure 3A). troubleshooting 4.

Note: In the “Ensembles visualizer” tab, the upper region is used to select the results of a given algorithm. Only algorithms with valid results will be available in this panel. Once loaded, the tab “General” shows a summary of the selected ensemble. In this tab, on the left panel, the interface shows options for selecting a specific ensemble to visualize, also to review the total number of ensembles identified by this algorithm (Figure 3B). Additionally, the lower panel contains the members of the ensemble, as defined by their index in the given original matrix. The exclusive members of the ensemble are the neurons indexes that appear only in the selected ensemble and not in others. The time points of activation show the index of the time bins where the ensemble activates, as reported by the original algorithm.

Note: If coordinates were provided from the beginning of the analysis, then the left panel in the plots right section will show the distribution of the registered neurons, showing with different colors the neurons in the ensemble, the exclusive neurons of the ensemble and the rest of the neurons (Figure 3C). The plotted data can be modified to show only the ensemble and other visualization options, by using the options of the panel on the left.

Note: If fluorescence data has been added from the beginning, the plot on the right will show the fluorescence traces of the neurons in that ensemble, next to their index so they can be matched with the spatial representation on the left. Also, the activation of the ensemble is shown with red vertical bands over all the fluorescence traces. Make use of the different visualization options to change the color, size, markers and assign custom labels to each neuron only in this visualization.

Note: If some data needed for these visualizations has not been loaded from the beginning, it is possible to load it later. For this, go back to the “Load data” tab and load the missing data, such as coordinates or fluorescence. Once the data is loaded, go to the “Ensembles visualizer” tab and click again in the algorithm results. This will refresh the visualizations integrating the new data.

Note: In this section, the rest of the tabs show the results for all the ensembles simultaneously, categorized by different characteristics. The “All the spatial distributions” shows maps with the distributions for every ensemble. The “All the binary activations” tab shows the activations of every neuron in every ensemble. The “All the dFFo” tab shows the fluorescence activity of every neuron in every ensemble. Finally, the “All ensembles’ activations” tab shows the activity of every ensemble on time.

Figure 3.

Inspection of the results for each algorithm

(A) Algorithm selection bar. Only the algorithms with valid results are available for selection.

(B) Ensemble selection panel, showing visualization options and a summary of the neurons associated with every ensemble and the time points of activation for each ensemble.

(C) Spatial map and fluorescence of the neurons in the selected ensemble.

Compare results across different algorithms

Timing: <10 min

In this section we specify different comparison approaches for the results of each algorithm.

• 13.
  Select the ensembles to compare.

  • a.
    Go to the “Ensembles compare” tab.
  • b.
    Use the panel on the left to select the specific ensembles that are going to be used for comparison in the visualizations (Figure 4A). troubleshooting 5.

Note: The results of each algorithm can be compared against each method and against stimulation and behavioral data. The results of these comparisons may indicate convergence of results rather than accuracy of the methods.

• 14.Click on the “Similarities in members” tab to identify the ensembles that group together the same neurons to find convergencies in the neurons assigned by each method to each neuronal ensemble (Figure 4B).

Note: The “Similarities in members” tab shows a correlation map between the neurons in each ensemble, compared with the rest of the ensembles in every other algorithm. This is computed by using 1-D binary arrays with N elements for N neurons. In this array, the index of each element represents the index of the neuron. A value of 1 in the index i indicates that the neuron i belongs to the ensemble. Different correlation metrics can be computed to measure similarities. For the similarity of members, it is suggested to use the Jaccard Index (JI), which is defined as the size of the intersection of two sets divided by the union of both sets. In this case, if two selected ensembles do not share any neurons the JI = 0. If two different ensembles share the same neurons the JI = 1.

• 15.Click on the “Similarities in timecourses” tab to identify the ensembles that shares the most similar activations across the different algorithms (Figure 4C).

Note: The “Similarities in timecourses” tab shows a correlation map between the binary activation of each ensemble with the rest. Similarly to the “Similarities in members” this is calculated by applying a correlation metric to the 1-D array of the activation of each ensemble.

Note: The “Similarities in timecourses” and “Similarities in members” provides different information about each algorithm. Two different methods can identify the same moments of activation for an ensemble but differ slightly in the members of each ensemble based on the specific metrics of inclusion for a neuron in every ensemble. At the same time, two different methods can find the same set of neurons for an ensemble but differ slightly in the moments of activity of such ensemble, based on the specific criteria and thresholds for defining an ensemble as active.

Note: Both for the “Similarities in members” or the “Similarities of timecourses” can be computed with different metrics, each providing different insights of the data (Figure 4D). Use Table 1 as a guide to identify the best metric according to the specific question.

• 16.
  Compare specific ensembles with detail.

  • a.
    Click on the “Space map” tab to visually compare the members of each ensemble (Figure 4E).
  • b.
    Click on the “Time profiles” tab to compare specific ensembles by time profiles (Figure 4F).

Note: If available, select also stimuli and behavior to include in the similarity maps and visualizations.

Figure 4.

Comparisons of the results of each algorithm

(A) Ensemble selection panel. It is possible to select the current ensemble, behavior and stimulus to compare in the “Space map” and “Time profiles” tabs.

(B) Similarity maps for the neurons included in each ensemble and each algorithm.

(C) Similarity maps for the time profiles of each ensemble and each algorithm.

(D) Configuration panel for the visualization and metrics used for each comparison map. It’s possible to change the identifier color for each ensemble in the “Space map” and “Time profiles” panel using the “Results selector” menu in this panel, also, to include or not the results from an algorithm in the plots.

(E) Spatial map for the neurons in the selected algorithms. When more than one algorithm selects the same neuron for an ensemble the circle that identifies each neuron will show divisions to show the identification colors for each algorithm.

(F) Side by side view of the time profiles of the selected ensembles of each algorithm. In the example the activations are also compared to the presentation of a stimulus labeled as “Stim Go”.

Table 1.

Comparison metrics for similarities in results

Metric	Sensitive to	Good for “similarities in members”	Good for “similarities in timecourses”
Cosine	Pattern detection.	Relative member composition. Two ensembles with similar proportions of shared neurons get high similarity, even if one is larger.	Similarity activity profiles, but not duration of activity. Tells about if the ensembles tend to be active in the same periods.
Pearson	Linear co-fluctuations.	Shared membership above baseline. Two ensembles are correlated if having an element in one increases the chance of it being in the other.	Co-activation trends, time correlation. Answers if the sets activate together across time.
Jaccard	Absolute overlap.	Overlap of elements. Can indicate if most neurons of one ensemble also appear in the other or if ensembles have mostly disjoint membership.	Overlap in activation periods, not pattern shape.

Performance comparison for each method

Timing: <10 min

In this section, we explain the usage of behavioral or stimulation data to measure the performance of each method at identifying neuronal ensembles related to each element.

• 17.Use the “Performance Comparison” tab to compare the results of each method with the data from behavior or stimulation. troubleshooting 6.

CRITICAL: The performance comparison process relies on the availability of behavioral or stimulation data. In order to have performance metrics, make sure to load one of these additional variables.

Note: As proven by other studies, the activation of specific ensembles shows a high correlation with the presentation of relevant stimulus or behaviors.

• 18.Select the methods to use for comparison and run the comparison by pressing the button “Compare” at the top of the tab.

Note: The “Compare” tab will generate different correlations maps showing relationships between ensembles and stimuli, ensembles and behavior and individual neurons in the same ensemble.

Note: The “Correlation between cells” tab shows one correlation map for each ensemble in each selected method. The correlation is computed using Pearson’s correlation between the binary activation of each neuron inside each ensemble. This provides a quantitative approach to measure how similar the activations of each neuron are in the same ensemble, further expanding the measure of the precision of each method in the loaded dataset.

Note: The “Correlation with stimulus” tab shows one correlation map for each selected algorithm. The correlation is computed by using the Pearsons correlation coefficient of the binary activation of the ensemble and the presentation of each stimulus, if provided. At the same time, the “Correlation with behavior” tab, shows a correlation map between each behavior and the activity of each ensemble.

Note: The “Cross correlation ensembles and stimuli” shows a cross-correlation plot for each ensemble and each method. This procedure allows the identification of temporal relationships between the activation of each ensemble with every loaded stimulus. Similarly, the “Cross correlation with behavioral activity” shows cross-correlation maps plots between each ensemble and each behavior.

Saving and exporting results

Timing: <5 min

This section explains the general procedure for exporting the plots generated by ENCORE and the quantitative data generated by the comparison protocols.

• 19.Customize every plot using the bottom section of every visualization.

Note: The customization section uses the visualization capabilities of Matplotlib objects to modify the current visualization of the plot. Use the different options to customize the plot design as needed.

Note: In short, the House icon at the left returns the visualization to the default view. The next two arrows switch between visualizations, if any changes have been made to the plot. The cross arrows that follow allows you to pan and zoom in the current view by suing the left or right click respectively. The magnifying glass icon zooms to the drawn rectangle. Next, the sliders icon allows the modification of borders and spacing between the objects in the plot. The plot icon that follows shows a variety of tools depending on the type of plot that is being used. These changes include modification to title, and axis labels, change of scales and ranges for every axis, change of colors of lines, and colormaps for correlation maps. The last icon saves the current figure to a PNG or SVG file. In the case of the SVG file, the text is exported as such, for easy modification in vectorial image editing software.

• 20.Save the results to a file using the “Save” tab. troubleshooting 7.

Note: Select the data to be saved by checking the boxes next to each category. Then press the “Save as” button at the bottom, using the format that best fits your needs.

Note: In the save section, the “Input user data” includes the data loaded to the GUI, each variable receives the name of the variable as described in the “Load data” tab.

Note: The “Minimal results” option integrates in the file three variables for each algorithm used. This are a binary matrix called “timecourse” with shape (E, T) for E ensembles and T time points, where a value of 1 in the position (E_i, T_j) indicates that the ensemble i was active at the time point j. In the binary matrix “neus_in_ens” with shape (E, N) for E ensembles and N neurons, a value of 1 in the position (E_i, N_j) indicates that the neuron j belongs to the ensemble i. Finally, the variable “ensembles_cant” that contains an integer indicating the total number of ensembles identified by this method.

Note: The “Analysis parameters” option includes a structure for each algorithm with the values used for each method, ideal for replicating the results.

Note: The “Full results of every analysis” option includes all the data produced by every method; this data may not have been used by ENCORE but may be relevant for further analysis specific for each method.

Note: The “Ensembles compare analysis” includes the similarity maps calculated in the tab “Ensemble compare”, such as the similarity maps between members and time courses.

Note: The “Performance Comparison” option includes the data for the “Performance comparison” tab, such as correlation and cross-correlation data between ensembles, neurons and stimuli or behavior.

Note: Although different formats are provided for the results file, it is recommended to use the H5 format, which can be used both in Python and MATLAB environments but also, by other analysis software like R. Additionally, this format allows the compression of large datasets and easy visualization of the contents even without using a programming language by using HDF5 visualizers.

Expandability and custom algorithm integration

Timing: Variable

ENCORE was designed with extensibility as a core principle, allowing advanced users to incorporate new ensemble-detection algorithms without modifying or recompiling the graphical interface. In this section, we describe the option to integrate additional custom-made analysis into ENCORE. New methods can be added through a lightweight plug-in-style pipeline that separates algorithm definition, parameter specification, execution, and visualization.

• 21.
  Optionally integrate new algorithms into ENCORE.

  Note: A fully documented step-by-step guide, including templates and an example algorithm is provided in the online documentation in the section “Adding New Algorithms to ENCORE”. This example algorithm is also included in the “ENCORE analysis” tab as a demo of this feature.

  • a.
    Download the GitHub repository with the source code of ENCORE.
  • b.
    Install ENCORE in editable mode using the command:

    > pip install -e .
  • c.
    Define the algorithm configuration using the YAML template in the “Adding New Algorithms to ENCORE” tab of the online documentation.

    Note: The structured configuration file defines the required inputs for the function, parameters, parameter bounds and output structures.

  • d.
    Implement the algorithm function in Python.

    Note: An example algorithm function is also included in the online documentation. If the core code of the algorithm is written in MATLAB, it’s possible to call the MATLAB engine to run that code from the Python function.

  • e.
    Include the configuration YAML structure in the file “src∖encore∖config∖encore_runners_config.yaml” under the “encore_runners” directive.
  • f.
    Include the new Python function in the file “src∖encore∖runners∖encore.py”.

    Optional: Include a plotting function for your algorithm in the file “src∖encore∖plotters∖encore_plots.py”. The plotting function must be based on Matplotlib for visualizing results within the GUI.

    Note: Once registered, the algorithm becomes automatically available in the interface, with parameter widgets, validation rules, and logging behavior generated from the configuration file.

    Note: All user-defined parameters and input data are validated prior to execution using a centralized validation layer, ensuring early detection of incompatible data types, invalid parameter ranges, or missing inputs. This design minimizes runtime failures and prevents crashes.

Programmatic access and batch analysis

Timing: Variable

In addition to the GUI, ENCORE provides a Python Application Programming Interface (API) that enables programmatic access to all supported ensemble identification algorithms. This interface allows advanced users to run analyses directly from Python scripts, facilitating batch processing, automated pipelines, and reproducible workflows. In this section we describe the general process of using the ENCORE Python API.

• 22.
  Optionally access the Python API to run sequential analyses of many datasets.

  Note: The Python API mirrors the internal execution logic of the GUI and produces standardized outputs, including algorithm results, execution times, and success flags, allowing consistent interpretation across interfaces. Detailed usage examples, including batch analysis workflows and code templates, are provided in the online ENCORE documentation in the section “Running batch analyses using the ENCORE Python API”.

  • a.
    Import the algorithms to use in your code, for example:

    > from encore.runners.encore import run_svd
  • b.
    Define the parameters to use for this algorithm in a Python dictionary pairing the name of each parameter with the value for that parameter.

    Note: The names of the parameters and allowed values for each algorithm can be found in the “Analysis Runners” section of the online documentation.

  • c.
    Pass the neuronal activity and algorithm’s parameters to the function to obtain the result of that algorithm.

    > algorithm_result = run_svd(

      input_data = {'data_neuronal_activity': raster},

      parameters = parameters)

    Note: Using the API, users can organize multiple datasets and parameter configurations, execute analyses sequentially or in custom loops, and collect results in structured Python objects. This approach makes it possible to analyze multiple recordings using identical settings, perform parameter sweeps, or integrate ENCORE into larger data processing pipelines. While the GUI operates on one dataset at a time, the API enables flexible multi-dataset execution under user control.

Expected outcomes

ENCORE applies up to five different algorithms to neuronal activity data to identify neuronal ensembles, the members of each ensemble and their activation times. These ensembles are further compared between each other to identify consistent results across different methods. When behavioral or stimulation data is provided, ENCORE can identify relationships between the activation of a neuronal ensemble and the presentation of a stimuli or a behavior.

In its current version, ENCORE provides different strategies that may be suitable for different data sources. With robust activation of ensembles, such as those observed in the visual cortex with the presentation of varying angles drifting gratings, the different algorithms may provide additional verification of the ensemble related to each line orientation. This verification arises from the comparison of neurons that belong to each ensemble and the specific moment of activation in time.

Processing times were estimated using synthetic datasets generated to match typical neuronal ensemble activity patterns, allowing precise control over neuron count and recording length. All benchmarks were obtained on a machine meeting the recommended hardware specifications (i.e., laptop with Core i5-1145G7, 16GB RAM) and were executed sequentially through the GUI, without parallelization. Each algorithm was run using its default parameter settings and completed without errors (Table 2). Reported execution times exclude MATLAB Engine initialization and result visualization, focusing exclusively on core algorithm runtime.

Table 2.

Running times of four representative algorithms using synthetic data

Dataset size (neurons, timepoints)	SVD	PCA	ICA	Xsembles2P
50, 1000	7.07s	31.91s	1.33s	5.30
100, 3000	16.87s	37.87s	1.55s	6.48
250, 5000	488.55	93.72	1.70s	15.88

Table 2 summarizes the dataset dimensions used for benchmarking and the corresponding execution times (in seconds) for four representative algorithms implemented in ENCORE. Actual processing times depend on the selected algorithm, data characteristics, and system configuration.

Limitations

The performance evaluation of each method relies on the availability of behavioral or stimulation data. Additionally, most algorithms use binary activity data, so magnitude of activity, such as firing rate or fluorescence amplitude may be overlooked in these implementations. ENCORE analyses one database at the time in the GUI and currently it is not possible to evaluate differences between the ensembles across different sessions. However, programmatic access through the Python API allows advance users to run multiple analyses in custom workflows and to perform downstream cross-session comparisons outside the GUI. Finally, each method has a variety of parameters that must be tuned for every dataset, making the process semi-automatic rather than fully automated.

Troubleshooting

Problem 1

ENCORE does not identify the selected variable as a valid dataset. Related to Step 3.

Potential solution

ENCORE uses a custom parser with a mix of controls to identify the selected variable as a matrix even from different file formats. To make sure the variable will be identified as a matrix by ENCORE, use “Datasets” objects for HDF5 files, NumPy arrays for Python and numerical matrices for MATLAB, not cell arrays. Make sure to include more than one element in each matrix, a matrix with just one element will be interpreted as a scalar. In any case, ENCORE will show a description of each selected variable in the “Variable description” field, showing also the identified type of that variable to aid with the debug of the file.

Problem 2

The algorithm does not find any neuronal ensembles. Related to Step 9.

Potential solution

This may happen for several different reasons, depending on the input data and the specific algorithm used. If any plots have been shown in the plots tab of the algorithm, there may be some clues about the cause of the result. For example, setting thresholds too high for coactive number of neurons in SVD, PCA or Xsembles2P may result in very few neurons used for the analysis. Very high correlation thresholds for PCA or Xsembles2P may also restrict the final number of ensembles found. Try changing thresholds and values to have less restrictive analysis and tune from there.

Problem 3

No algorithm finds any ensemble in the database. Related to Step 11.

Potential solution

This problem typically arises from having very few neurons in the database, from very short recordings or very dispersed data, with most neurons silent for the duration of the recording. Increase the number of neurons to at least 40, and the duration of the recording to at least 2000 samples to have better results.

Problem 4

ENCORE reports an error and closes unexpectedly while creating plots. Related to Step 12.

Potential solution

This problem may arise when the activity data and visualization data have different shapes. For most cases this is solved by checking the consistency of each loaded variable. If working with a binary activity matrix of [N, T] the appropriate dimensions for the fluorescence activity is also [N, T] and the same number of time points for the stimulation and behavior data.

Problem 5

The plots are scaled wrong, showing incomplete figures or with very small size. Related to Step 13.

Potential solution

This problem may emerge after plotting any visualization and later changing the size of the ENCORE window. There are two ways to solve this problem. First, refresh the plot by triggering again the visualization render by pressing the corresponding button of the analysis or changing tabs inside the GUI. Second, use the “Configure subplots button” marked with the slider’s icon in the toolbox at the bottom of every plot. Then press “Tight layout” for the plot to update to the current window size.

Problem 6

The labels assigned to elements in a variable do not show up in the visualization. Related to Step 17.

Potential solution

This problem emerges when changing the labels after the visualization has been rendered. To fix this problem update the plot by retriggering the plot render or by using the “Tight layout” button in the “Configure subplots” button in the plot’s toolbox.

Problem 7

There is an error when saving the results file. Related to Step 20.

Potential solution

Some variables generated by some algorithms may include elements that cannot be parsed to the selected output format. For example, time objects in Python do not have a direct conversion to a HDF5 format. Or cell structures from MATLAB to Python or HDF5 format. To help with this, ENCORE implements several manual parsing procedures to help with the conversion of such structures. However, it is possible that not all the different combinations of file formats are currently supported. As a potential solution, try different formats to export the data, mostly Python and MATLAB formats. This data can later be parsed using specific programming language and through custom scripts. Also, it is encouraged to raise an issue in the Issues section of ENCORE GitHub page to ask for such implementation.

Resource availability

Lead contact

Further information and requests for resources should be directed to and will be fulfilled by the lead contact, Luis Carrillo-Reid (carrillo.reid@comunidad.unam.mx).

Technical contact

Technical questions on executing this protocol should be directed to and will be answered by the technical contact, Ricardo Velázquez-Contreras (rivelco@comunidad.unam.mx).

Materials availability

This study did not generate new materials.

Data and code availability

ENCORE is open-source and publicly available on GitHub https://github.com/rivelco/ENCORE and archived on Zenodo under the https://doi.org/10.5281/zenodo.18373149. This study did not generate new datasets.

Acknowledgments

This work was supported by grants from The Kavli Foundation (NeuroData Discovery Award to L.C.-R. and R.V.-C.) and UNAM-DGAPA-PAPIIT (IN213923 to L.C.-R.). R.V.-C. is a doctoral student of the Programa de Doctorado en Ciencias Biomédicas at Universidad Nacional Autónoma de México (UNAM) and has received a fellowship (no. 1223559) from Secretaría de Ciencias, Humanidades, Tecnología e Innovación (SECIHTI, formerly CONAHCYT).

Author contributions

Conceptualization, L.C.-R. and R.V.-C.; code, R.V.-C.; writing – original draft, R.V.-C.; writing – review and editing, L.C.-R. and R.V.-C.; funding acquisition, L.C.-R. and R.V.-C.

Declaration of interests

The authors declare no competing interests.