Metadata-Version: 2.4
Name: UnitMatchPy
Version: 3.3.1
Summary: Automatic matching of neurons across sessions
Author: Enny van Beest, Célian Bimbard, Suyash Agarwal, Wentao Qiu
License: CC BY-NC-SA 4.0 International
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.21
Requires-Dist: scipy<2.0,>=1.9
Requires-Dist: pandas<3.0,>=1.5
Requires-Dist: matplotlib<4.0,>=3.6
Requires-Dist: joblib<2.0,>=1.2
Requires-Dist: tqdm<5.0,>=4.64
Requires-Dist: h5py<4.0,>=3.8
Requires-Dist: scikit-learn<2.0,>=1.2
Requires-Dist: mtscomp
Requires-Dist: torch<3.0,>=2.1
Provides-Extra: full
Requires-Dist: mat73<1.0,>=0.62; extra == "full"
Requires-Dist: spikeinterface<0.120,>=0.100; extra == "full"
Provides-Extra: notebooks
Requires-Dist: ipykernel<7,>=6; extra == "notebooks"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# UnitMatchPy and DeepUnitMatch

This repository contains:
- **UnitMatchPy**: automatic matching of neurons across sessions (Python package).
- **DeepUnitMatch**: DeepUnitMatch pipeline and demos (see preprint below).

## References

- **UnitMatch:** https://www.nature.com/articles/s41592-024-02440-1
- **DeepUnitMatch preprint:** https://www.biorxiv.org/content/10.64898/2026.01.30.702777v1

## Versions

- **UnitMatchPy version:** `3.3.1` (from `pyproject.toml`)
- **DeepUnitMatch:** code lives under `DeepUnitMatch/` (see **DeepUnitMatch (DUM)** section)

## System requirements

Both UnitMatchPy and DeepUnitMatch can be ran on a standard computer, with sufficient RAM (>32GB for large datasets). 
This software is supported for Windows and macOS, and has been tested on Windows 11.

## Installation

`pip install` (including `pip install -e .`) installs into whatever Python environment your `pip` points to (system Python, a conda env, or a virtualenv). `pip` does **not** create or name environments.

We recommend using Anaconda/Miniconda (conda) to create an isolated environment first:

```bash
# Create a new environment (pick any name you like; example: UMPy)
conda create -n UMPy python=3.11 pip #(press y when prompted)
conda activate UMPy
```

Then install using pip (options below). This step should take less than few minutes.

### Option A: Install the released package (PyPI)

```bash
pip install UnitMatchPy
```

Optional extras (heavier dependencies used by some notebooks and integration with SpikeInterface):

```bash
pip install "UnitMatchPy[full,notebooks]"
```

### Option B: Install a local, editable copy (for development / modified code)

First, open a terminal and navigate to this folder (the one containing `pyproject.toml`). The `pip install -e` command must be run from here:

```bash
# Windows (PowerShell) - note; you may have to give writing access to the specific CONDA environment via Windows Security → Virus & threat protection → Ransomware protection → Manage ransomware protection. For example, if the below steps result in "could not create 'UnitMatchPy.egg-info'"

Look at Controlled folder access:
cd $HOME\Documents\GitHub\UnitMatch\UnitMatchPy

# macOS / Linux
cd ~/Documents/GitHub/UnitMatch/UnitMatchPy
```

```bash
pip install -e .
```

Optional extras (e.g. if you'd like to run the notebooks or integrate with SpikeInterface):

```bash
pip install -e ".[full,notebooks]"
```

## Demo notebooks

All demo notebooks are in `Demo Notebooks/`.

### Run UnitMatchPy 

To run UnitMatchPy, standard spike sorting data is needed (channel positions and extracted raw waveforms for each unit). Waveforms can be extracted externally (e.g. [BombCell](https://github.com/Julie-Fabre/bombcell)) or using the demo notebooks:
- `Demo Notebooks/extract_raw_data_demo.ipynb` (compressed `.cbin`/`.ch` or raw)
- `Demo Notebooks/extract_raw_data_demo_open_ephys.ipynb` (Open Ephys)
- `Demo Notebooks/UMPy_spike_interface_demo.ipynb` ([SpikeInterface](https://spikeinterface.readthedocs.io/en/latest/) workflow)

Example notebooks:
- `Demo Notebooks/UMPy_example.ipynb` (recommended starting point)
- `Demo Notebooks/UMPy_example_detailed.ipynb` (more modular / advanced)

The GUI is an optional step to curate and explore UnitMatch outputs; see `Demo Notebooks/GUI_Reference_Guide.md` for usage tips and shortcuts.

### Run DeepUnitMatch 

To try the DeepUnitMatch version, start with:
- `Demo Notebooks/DeepUnitMatch.ipynb`

It should take just a few minutes to run on a standard PC. 

If you want to train / fine-tune a model on your own data, see:
- `Demo Notebooks/DUM_training.ipynb`

Important note: DeepUnitMatch current trained model is for Npix 2.0 4-shank only. You will need to train a new model with your own data if you have any other type of probe. (For example, Mouse2 from the figshare data is a Npix 1 dataset, you'll notice the trained model won't give good results on this mouse for that reason.)
