Metadata-Version: 2.4
Name: encore-toolkit
Version: 3.0.0
Summary: GUI for Ensembles Comparison and Recognition
Author: Ricardo Velazquez Contreras
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/rivelco/ENCORE
Project-URL: Documentation, https://rivelco.github.io/ENCORE/
Project-URL: Issues, https://github.com/rivelco/ENCORE/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6>=6.0
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: h5py
Requires-Dist: scikit-learn
Requires-Dist: pyqtdarktheme
Requires-Dist: pyyaml
Requires-Dist: pydantic
Provides-Extra: dev
Requires-Dist: pyqt6-tools; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: setuptools==81.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinxcontrib-napoleon; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: build; extra == "test"
Provides-Extra: all
Requires-Dist: pyqt6-tools; extra == "all"
Requires-Dist: pytest; extra == "all"
Requires-Dist: build; extra == "all"
Requires-Dist: sphinx>=7.0; extra == "all"
Requires-Dist: furo; extra == "all"
Requires-Dist: sphinx-copybutton; extra == "all"
Requires-Dist: sphinxcontrib-napoleon; extra == "all"
Requires-Dist: sphinx-autodoc-typehints; extra == "all"
Requires-Dist: setuptools==81.0.0; extra == "all"
Dynamic: license-file

<!-- PROJECT LOGO -->
<br />
<div align="center">
  <a href="https://github.com/rivelco/ENCORE">
    <img src="https://raw.githubusercontent.com/rivelco/ENCORE/main/src/encore/gui/ENCORE_logo.png" alt="Logo" width="80" height="80">
  </a>

  <h3 align="center">ENCORE - Ensembles Comparison and Recognition</h3>

  <p align="center">
    <a href="https://github.com/rivelco/ENCORE/actions/workflows/windows-compatibility.yml">
      <img src="https://github.com/rivelco/ENCORE/actions/workflows/windows-compatibility.yml/badge.svg" alt="Windows Compatibility">
    </a>
    &middot;
    <a href="https://github.com/rivelco/ENCORE/actions/workflows/linux-compatibility.yml">
      <img src="https://github.com/rivelco/ENCORE/actions/workflows/linux-compatibility.yml/badge.svg" alt="Linux Compatibility">
    </a>
    &middot;
    <a href="https://github.com/rivelco/ENCORE/actions/workflows/macos-compatibility.yml">
      <img src="https://github.com/rivelco/ENCORE/actions/workflows/macos-compatibility.yml/badge.svg" alt="macOS Compatibility">
    </a>
  </p>

  <br />

  <p align="center">
    GUI to identify and compare neuronal ensembles in calcium or electrical recordings using five different algorithms.
    <br />
    <a href="https://rivelco.github.io/ENCORE/"><strong>Read the documentation</strong></a>
    <br />
    <a href="https://doi.org/10.1016/j.xpro.2026.104443">Read the paper</a>
    <br />
    <br />
    <a href="https://link.springer.com/book/10.1007/978-1-0716-4208-5">Read the book</a>
    &middot;
    <a href="https://github.com/rivelco/ENCORE/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
    &middot;
    <a href="https://github.com/rivelco/ENCORE/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
  </p>
</div>

## Demo

<p align="center">
<img align="center" src="docs/source/_static/demo_usage.gif" width="100%" alt="ENCORE demo usage"/>
</p>

## About ENCORE

Graphic User Interface to perform a variety of neuronal ensembles identification's methods.

This GUI currently incorporates five different algorithms:

- SVD based method: Carrillo-Reid, et al. "Endogenous sequential cortical activity evoked by visual stimuli." Journal of Neuroscience 35.23 (2015): 8813-8828.
- PCA based method: Herzog et al. 2021 "Scalable and accurate automated method for neuronal ensemble detection in spiking neural networks. https://pubmed.ncbi.nlm.nih.gov/34329314/ Rubén Herzog Dec 2021
- ICA based method: Lopes-dos-Santos V, Ribeiro S, Tort AB (2013) Detecting cell assemblies in large neuronal populations. J Neurosci Methods 220(2):149-66. 10.1016/j.jneumeth.2013.04.010
- Xsembles2P method: Pérez-Ortega, J., Akrouh, A. & Yuste, R. 2024. Stimulus encoding by specific inactivation of cortical neurons. Nat Commun 15, 3192. doi: 10.1038/s41467-024-47515-x
- Similarity Graph Clustering method: L. Avitan et al. "Spontaneous Activity in the Zebrafish Tectum Reorganizes over Development and Is Influenced by Visual Experience". Curr. Biol. 27 (2017). DOI: 10.1016/j.cub.2017.06.056

**More analysis and features coming soon...**

> [!IMPORTANT]
> For detailed instructions about installation and usage, go to the [documentation website](https://rivelco.github.io/ENCORE/)

## Installation

## System requirements

The GUI is very low resource demanding. It is advisable to run it in a screen at least 1170 x 660 pixels to see al the buttons clearly. For the system requirements it is recommended a modern CPU and at least 16Gb of RAM. This for agile tuning and execution of the analysis.

This specs, while recommended, are not mandatory. If you can run MATLAB 2020A then you can run this GUI and the included analysis.

### OS Compatibility

ENCORE is compatible with Linux distributions, macOS and Windows. You can verify the current compatibility status of ENCORE by looking at the tags generated by the automated testing on each one of these platforms. Each platform has been tested against the `main` branch of this repository that also produces the package in PiPy. 

| Platform | Versions | Python versions tested | Test status |
| -------- | -------- | ---------------------- | ----------- |
| Windows  | Latest   | 3.9, 3.10, 3.11        | [![Windows Compatibility](https://github.com/rivelco/ENCORE/actions/workflows/windows-compatibility.yml/badge.svg)](https://github.com/rivelco/ENCORE/actions/workflows/windows-compatibility.yml) |
| Ubuntu   | 22.04, 24.04 | 3.9, 3.10, 3.11    | [![Linux Compatibility](https://github.com/rivelco/ENCORE/actions/workflows/linux-compatibility.yml/badge.svg)](https://github.com/rivelco/ENCORE/actions/workflows/linux-compatibility.yml) |
| macOS   | Latest    | 3.9, 3.10, 3.11        | [![macOS Compatibility](https://github.com/rivelco/ENCORE/actions/workflows/macos-compatibility.yml/badge.svg)](https://github.com/rivelco/ENCORE/actions/workflows/macos-compatibility.yml) |

> [!IMPORTANT]
> The compatibility of ENCORE is not limited only to the platforms and Python versions used in the GitHub Actions tests.

> [!NOTE]
> Every time new code is pushed to the `main` branch of the repository a series of automatic tests are triggered. This tests installs the code in the repository using `pip install .[test]` in servers running the specified OS and Python versions. Then it uses `pytest` to execute the code in the `tests/` folder, which basically ensures that ENCORE is executable and that the Python API is available for all the included algorithms.

## Needed dependencies

- MATLAB (version 2020A or above)
- Python 3.9 or above

### Needed MATLAB modules

- Parallel Computing Toolbox
- Statistics and Machine Learning Toolbox
- Curve Fitting Toolbox

## Installation process

The recommended installation method relies on Conda to manage your Python environments. I highly recommend using conda for this purpose. 
To install using this method simple open your terminal and type these commands.

These commands creates a conda environment called `encore` with Python 3.10 and then activates it.

```bash
conda env create -n encore python=3.10
conda activate encore
```

### Installation using pip

To install ENCORE in the current environment simply run:

```bash
pip install encore-toolkit
```

## Verifying the installation

To verify that ENCORE is installed correctly, run:

```bash
python -c "import encore; print(encore.__version__)"
```

## Install the MATLAB engine for Python

To run the currently available algorithms it is necessary to install in the python environment the MATLAB engine. This can be done by looking for yor MATLAB installation path, to something like this:

```bash
cd C:\Program Files\MATLAB\R2023a\extern\engines\python
``` 

The idea is to locate the engine for Python.

Once you're there and with your correct python environment activated then simply run:

```bash
python -m pip install .
```

It is possible that you need to run that command from an elevated terminal.

> [!TIP]
> More information about the MATLAB engine installation is available [in the docs](https://rivelco.github.io/ENCORE/installation).

## Run the GUI

To run the GUI you now just need to run a command from your terminal:

```bash
encore
```

You can also run:

```bash
python -m encore
```

## Needed data

This GUI requires just matrices for all the input data that can be loaded from different files. All these matrices follow the same logic. For data that shows a timeseries like the recording of neurons or the recording of stimulation then the matrix must have a shape `[elements, timepoints]`. Every element (neuron or stimulation or even behavior) should have the recording of their activity over time.

The datasets that indicates belonging to a group must have the format of a binary matrix with shape `[groups, elements]`.

Consider that any of these matrices could be transposed in your file and you can re-transpose it using the GUI. Just make sure that the axes labels match your data.

### Variable `dFFo/FFo`

Matrix with the shape `[neurons, timepoints]` that stores continuous values describing the fluorescence activity of each neuron.

### Variable `Binary cell activity`

This should be a binary matrix with shape `[neurons, timepoints]`. If the element `[neuron, timpeoint] == 1` then this indicates that that neuron was active in that timepoint.

### Variable `Coordinates`

This variable should be a matrix with shape `[neuron, dimentions]`, where for each neuron it is specified its coordinates for 2 dimensions, `x` and `y`. The current version only supports 2 dimensions.

### Variable `stimulation`

Binary matrix with shape `[stimuli, timepoints]`. The value `[stim, timpoint] == 1` indicates if the stimulation `stim` was present at the timepoint `timepoint`. 

### Variable `cells`

Binary matrix with shape `[groups, cell]`. The value `[group, cell] == 1` indicates if the group `group` includes the cell `cell`.

### Variable `behavior`

Binary matrix with shape `[behaviors, timepoints]`. The value `[behavior, timepoint] == 1` indicates that the behavior `behavior` was present in the timepoint `timepoint`. 

## Contribute to this project

The main goal of this project is to be easily used to identify neuronal ensembles using different approaches. If you have suggestions, feature requests or bug reports, don't hesitate to use the Issues section of this repo.

## Cite ENCORE

To cite ENCORE you can use:

```
Ricardo Velazquez-Contreras, Luis Carrillo-Reid,
Protocol for identifying and comparing neuronal ensembles using different algorithms within a graphical user interface,
STAR Protocols,
Volume 7, Issue 2,
2026,
104443,
ISSN 2666-1667,
https://doi.org/10.1016/j.xpro.2026.104443.
(https://www.sciencedirect.com/science/article/pii/S2666166726000961)
```

<!-- MARKDOWN LINKS & IMAGES -->
[repo-link]: https://github.com/rivelco/ENCORE
