pala-python

Python refactor of the PALA pipeline for Ultrasound Localization Microscopy (ULM).

This repository ports the original MATLAB-oriented PALA workflow into a Python package for localization, tracking, filtering, rendering, and large-scale in vivo processing.

• MATLAB-style compatibility modules under pala/PALA_scripts and pala/PALA_addons
• CPU pipeline for reproducible reference behavior
• optimized multi-GPU pipeline for large in vivo datasets

It is designed for researchers who want to run, extend, or benchmark ULM processing in Python while keeping a structure that remains easy to compare with the original PALA codebase.

Project Summary

pala-python provides:

• a Python package for localization, tracking, filtering, rendering, and data I/O
• a MATLAB-style compatibility layer for easier migration from the original PALA repository
• an optimized GPU pipeline for large in vivo rat brain datasets
• script-level entry points for CPU baseline and default GPU execution

Structure Conventions

• pala/PALA_scripts/: reusable package-level pipeline functions and MATLAB-style compatibility APIs
• pala/PALA_addons/: Python counterparts of MATLAB addon/toolbox-style modules
• scripts/: runnable repository entry points for end-to-end dataset processing
• pala/ulm/, pala/filtering/, pala/io/, pala/visualization/: lower-level implementation modules

Highlights

• run_in_vivo_ulm_example(): MATLAB-style baseline pipeline
• run_in_vivo_ulm_example_gpu(): optimized GPU pipeline with per-block parallel processing
• Default GPU entry: scripts/03_pala_full_analysis_gpu.py
• Default optimized output folder: RatBrain_Final_Pipeline_GPU_fast

Repository Layout

pala/
  PALA_addons/
    PALA_functions/
    ULM_toolbox/
  PALA_scripts/
  filtering/
  io/
  localization/
  ulm/
  utils/
  visualization/
scripts/
  02_pala_full_analysis.py
  03_pala_full_analysis_gpu.py
setup.py

Installation

Base install:

pip install -e .

GPU install in an environment with CUDA and CuPy available:

pip install -e .

This project was validated in a mamba environment named ULM with:

• Python 3.10
• cupy-cuda12x
• numpy
• scipy
• matplotlib

Usage

CPU baseline:

python scripts/02_pala_full_analysis.py

Default optimized GPU pipeline:

python scripts/03_pala_full_analysis_gpu.py

Outputs

The optimized GPU pipeline writes:

• block-wise tracks in block_tracks/
• final manifest .mat
• final matouts.mat
• rendered PNG outputs for MatOut, MatOut_zdir, VelNorm, and PowDop

Intended Use

• Reproduce a PALA-like workflow in Python
• Compare Python outputs with the original MATLAB codebase
• Run faster multi-GPU processing on larger in vivo datasets
• Use the package as a base for custom ULM research pipelines

Citation and References

If you use this repository in academic work, please cite the original PALA paper that describes the benchmark datasets, localization algorithms, and evaluation framework:

• Heiles, B., Chavignon, A., Hingot, V., Lopez, P., Teston, E., and Couture, O.
  Performance benchmarking of microbubble-localization algorithms for ultrasound localization microscopy.
  Nature Biomedical Engineering, 2022.
  DOI: 10.1038/s41551-021-00824-8

For broader background on ULM and super-resolution ultrasound imaging, see:

• Couture, O., Hingot, V., Heiles, B., Muleki-Seya, P., and Tanter, M.
  Ultrasound localization microscopy and super-resolution: A state of the art.
  IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control, 2018.
  DOI: 10.1109/TUFFC.2018.2850811

Related datasets referenced by the original PALA project are available at:

• Zenodo dataset: 10.5281/zenodo.4343435

This repository is a Python refactor inspired by the original MATLAB PALA codebase. When appropriate, please also acknowledge the original PALA repository and its authors.

Notes

• The GPU pipeline is the recommended default for large in vivo datasets.
• The CPU pipeline is kept as a simpler reference implementation.
• The repository does not include raw datasets or generated output folders.