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.6.0 (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:

# 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

GPU (CUDA) users: install this first

Skip this if you're on macOS (no CUDA) or don't have an NVIDIA GPU -- Option A/B below will just install the CPU build automatically, no extra steps needed.

If you do have an NVIDIA GPU (Windows/Linux) and want DeepUnitMatch to run on it, install the CUDA-enabled PyTorch build before Option A or B below:

pip install --extra-index-url https://download.pytorch.org/whl/cu126 torch

(if you've cloned this repo, pip install -r requirements-cuda.txt from this folder does the same thing). Do this first because plain pip install UnitMatchPy / pip install -e . alone always installs the CPU-only build -- PyPI's default torch wheel is CPU-only, and pip has no way to detect that a GPU is present. Once torch is already installed and satisfies the version range Option A/B ask for, they'll leave it alone instead of overwriting it with the CPU build.

Verify it worked:

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

This should print a version ending in +cuXXX (not +cpu) and True. If it's not, see pyproject.toml's torch dependency comment, or check nvidia-smi shows a working driver.

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

Option A: Install the released package (PyPI)

pip install UnitMatchPy

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

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:

# 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

pip install -e .

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

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) 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 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.)