DECODE-Plex

DECODE-Plex is a deep-learning-based framework for high-density single-molecule localization microscopy (SMLM) in multi-channel imaging experiments. It localizes dense and overlapping emitters across multiple channels while modeling the photophysical and optical properties of multi-channel systems.

This repository accompanies the DECODE-Plex manuscript and provides code, trained weights, configuration files, point spread functions (PSFs), and raw inference data required to reproduce the results reported in the paper.

DECODE-Plex is built on DECODE, a DEep COntext DEpendent neural network for sub-pixel emitter localization, and uses experimentally calibrated PSF models such as those obtained with SMAP or uiPSF.

Repository Contents

The repository contains scripts and notebooks for the main stages of the DECODE-Plex workflow:

1. PSF calibration and preparation.
2. Model training with experiment-specific configuration files.
3. Inference/localization using trained models.
4. Channel assignment for dual-color datasets.

Example workflows are provided in the ./notebook directory. Please update the file paths in each notebook according to your local data layout before running the examples.

Data and Reproducibility

We provide the materials needed to reproduce all figures in the manuscript, including:

• trained model weights;
• training configuration files;
• calibrated point spread functions;
• raw data used for inference;
• example scripts/notebooks for running localization and downstream analysis.

Data access is here:

After downloading the repository, create the following folders in the project root.

Linux:

mkdir -p ./data ./calibration ./outputs ./results

Windows PowerShell:

New-Item -ItemType Directory -Force data, calibration, outputs, results

Place the downloaded files into the corresponding folders:

• ./data: raw inference movies and example datasets used as inputs by the notebooks;
• ./calibration: calibrated PSFs, transformation files, and other calibration-related files;
• ./outputs: trained model checkpoints, training outputs, and intermediate outputs generated by DECODE-Plex;
• ./results: localization tables and figure-reproduction results.

Localization results inferred by DECODE-Plex are stored in .h5 format and can be directly opened and further analyzed in SMAP. If the downloaded archive already contains results or figure-output files, keep them under ./results.

Installation

Only the GPU version of DECODE-Plex has been tested. For model training and high-density inference, we recommend a workstation equipped with a modern NVIDIA GPU, such as an RTX 3090 or RTX 4090. A CUDA-compatible GPU with sufficient memory is required for practical training times.

System Requirements

• GPU: NVIDIA GPU with CUDA support and at least 8 GB GPU memory
• RAM: at least 16 GB
• CPU: multi-core CPU recommended
• OS: Linux or Windows
• Package manager: conda or miniconda
• Windows users: install the current NVIDIA display driver before creating the environment. The conda environment supplies the CUDA runtime used by PyTorch.

Verified Environment

Component	Version
Python	3.10
PyTorch	2.1.2
PyTorch CUDA runtime	12.1
TensorFlow	2.20.0

Setup

Clone the repository:

git clone git@github.com:ries-lab/DECODE-Plex.git
cd DECODE-Plex/

Create the local data directories.

Linux:

mkdir -p ./data ./calibration ./outputs ./results

Windows PowerShell:

New-Item -ItemType Directory -Force data, calibration, outputs, results

Create and activate the conda environment:

conda config --set channel_priority flexible
conda env create -f environment.yaml
conda activate decode_plex

The environment file includes the third-party libraries needed by uiPSF. Installing the bundled uiPSF package in editable mode makes the local uipsf source importable from notebooks and scripts regardless of the current working directory.

Install DECODE-Plex and the bundled uiPSF package in editable mode:

pip install -e .
pip install -e ./uipsf
python -m ipykernel install --user --name decode_plex --display-name "Python (decode_plex)"

On Windows, if your shell does not accept the ./uipsf path, use:

pip install -e .\uipsf

Platform Notes

We strongly recommend running and reproducing DECODE-Plex on Linux. Linux is the primary tested platform for this repository, especially for GPU-enabled workflows and uiPSF-based PSF fitting. Windows support is provided on a best-effort basis, but it has not been tested as thoroughly and may expose platform-specific issues in TensorFlow, CUDA libraries, or uiPSF native components.

If unexpected uiPSF-related errors occur on Windows or another local setup, we recommend following the original uiPSF installation and usage instructions to generate or fit the PSF model independently. The resulting calibrated PSF model can then be specified in the DECODE-Plex configuration files and used for training or inference.

Usage

The typical DECODE-Plex workflow consists of the following steps.

1. Prepare PSF Calibration Files

Obtain or download the calibrated multi-channel PSFs and place them in ./calibration. These PSFs are used to simulate training data and to model the optical response of the imaging system.

2. Train or Load a Model

Use the provided configuration files to train DECODE-Plex models for the corresponding experimental conditions. For reproducing the manuscript figures, use the supplied trained weights and matching configuration files.

3. Run Localization

Run inference on the provided raw data or on your own SMLM movies. Raw input data should be placed in ./data, and localization results should be written to ./results.

4. Perform Channel Assignment

For dual-color experiments, run the channel-assignment workflow after localization to separate emitters by channel.

Paper

TODO

Contact

For questions about this repository or the manuscript reproduction workflow, please contact:

• Hao Sha (shahao@hit.edu.cn)