PunctaTools v2.0

PunctaTools is a Python toolkit for fluorescence microscopy workflows that bundles ROI segmentation, puncta segmentation, and downstream quantification into a single, reproducible package.

Features

• ROI segmentation -- Cellpose-based whole-cell segmentation with label stitching across z-stacks.
• Puncta segmentation -- Dual modes: Cellpose masks or Ilastik-assisted predictions with per-ROI normalization.
• Ilastik training data generation -- Prepare normalized ROI crops for training Ilastik pixel classifiers.
• Quantification -- Extensive per-ROI and per-puncta metrics including intensity, morphology, colocalization (PCC, SCC, Manders), surface area, and more.
• JSON-driven configuration -- Fully reproducible processing pipelines driven by simple JSON config files.

Installation

Using pip (recommended)

pip install -e .

Using conda (conda-forge)

Note for institutional users: This environment file uses the conda-forge channel exclusively, which does not require a commercial Anaconda license.

conda env create -f environment.yml
conda activate punctatools

Using pip with requirements.txt

pip install -r requirements.txt
pip install -e .

Requirements

• Python 3.9+
• CUDA/cuDNN configured for Cellpose GPU mode (optional but recommended)
• Ilastik installed separately for the Ilastik puncta workflow

Optional: Bio-Formats support

The quantification module reads TIFF/OME-TIFF files using tifffile by default. For proprietary microscope formats (Leica .lif, Zeiss .czi, Nikon .nd2, etc.), install the optional Bio-Formats backend:

pip install -e ".[bioformats]"

This requires a working Java installation (JDK) and adds python-bioformats and javabridge as dependencies. Note that python-bioformats is licensed under GPL-2.0.

Command Line

punctatools roi-seg         params.json   # ROI segmentation (Cellpose)
punctatools puncta-seg      params.json   # Puncta segmentation (Cellpose or Ilastik)
punctatools train-ilastik   params.json   # Generate Ilastik training ROIs
punctatools quantify        params.json   # ROI/puncta quantification

Each sub-command consumes a JSON configuration file. See the examples/ directory for templates.

Workflow

A typical analysis pipeline consists of the following steps:

1. ROI segmentation -- Segment cells/nuclei from raw fluorescence images using Cellpose.
2. Puncta segmentation -- Detect puncta within each ROI using either Cellpose or Ilastik.
   • For the Ilastik workflow, first generate training data with train-ilastik, train a pixel classifier in the Ilastik GUI, then run puncta-seg with "segmentation_method": "ilastik".
3. Quantification -- Measure intensity, morphology, and colocalization metrics per ROI and per punctum.

Project Structure

punctatools_v2/
  src/punctatools/
    cli.py                        # Command-line interface
    config.py                     # JSON config dataclasses
    segmentation/
      roi.py                      # Cellpose ROI segmentation
      puncta.py                   # Cellpose / Ilastik puncta segmentation
      ilastik_training.py         # Ilastik training ROI generation
    quantification/
      roi.py                      # ROI and sub-ROI quantification
    utils/
      metadata.py                 # ImageJ TIFF metadata helpers
  examples/                       # Example JSON configuration files
  environment.yml                 # Conda environment (conda-forge)
  requirements.txt                # Pip requirements

License

This project is licensed under the GNU General Public License v2.0. See LICENSE for details.