ColokRoll

Colocalization analysis for fluorescence microscopy images

ColokRoll is a Python toolkit for analyzing colocalization in multi-channel fluorescence microscopy images. It handles image loading, cell segmentation, colocalization quantification, and puncta analysis.

---

Features

Module	Description
Image Loading	Multi-format support (.nd2, .oir, .ome.tiff, TIFF)
Z-Slice Detection	Focus-based filtering with multiple strategies
Background Subtraction	GPU-accelerated with negative control support
Cell Segmentation	Cellpose integration via HuggingFace Spaces
Colocalization	Pearson, Manders, Jaccard metrics per-cell
Puncta Analysis	LoG and BigFISH detection methods

---

Workflow modes

ColokRoll supports two workflow modes for processing microscopy data:

Exploratory mode (parameter calibration)

Use on your first image to visually inspect and select optimal parameters:

import colokroll as cr

# Compare Z-slice detection strategies
comparison = cr.compare_strategies(image, display_inline=True)

# Visually inspect and pick the best strategy
result = comparison.results["FFT + Closest (k=14)"]
filtered_image = image[result.indices_keep]

# Calibrate background subtraction with negative control
corrected, meta = bg_subtractor.subtract_background(
    image=channel_data,
    channel_name="ALIX",
    is_negative_control=True,  # Optimize for minimal residual signal
)
# Extract validated parameters for batch processing
best_params = meta['parameters_used']

Batch mode (production processing)

Apply validated parameters consistently across all images:

# Use explicit parameters from calibration
result = cr.select_z_slices(image, method="fft", strategy="closest", keep_top=14)

# Apply validated background subtraction parameters
corrected, meta = bg_subtractor.subtract_background(
    image=channel_data,
    method="two_stage",
    **validated_params  # From negative control calibration
)

See docs/workflow_modes.md for detailed guidance.

---

Installation

# Clone and install
git clone https://github.com/SaezAtienzar/colok-roll.git
cd colok-roll
pip install -e .

# With GPU acceleration
pip install -e ".[gpu]"

---

Quick start

import colokroll as cr
from pathlib import Path

# 1. Load image
loader = cr.ImageLoader()
image = loader.load_image("path/to/image.ome.tiff")
loader.rename_channels(['DAPI', 'ALIX', 'Phalloidin', 'LAMP1'])

# 2. Z-slice selection
result = cr.select_z_slices(image, method="combined", strategy="relative", threshold=0.6)
filtered_image = image[result.indices_keep]

# 3. Background subtraction
bg_subtractor = cr.BackgroundSubtractor()
results = {}
for i, ch in enumerate(loader.get_channel_names()):
    corrected, meta = bg_subtractor.subtract_background(
        image=filtered_image[:, :, :, i],
        channel_name=ch,
        is_negative_control=(ch == "ALIX"),  # If this is a negative control
    )
    results[ch] = (corrected, meta)

# 4. Cell segmentation
segmenter = cr.CellSegmenter(output_dir=Path("./output"))
seg = segmenter.segment_from_results(
    results=results,
    channel_a="Phalloidin",
    channel_b="DAPI",
)

# 5. Colocalization analysis
import numpy as np
corrected_stack = np.stack([results[ch][0] for ch in loader.get_channel_names()], axis=-1)

coloc = cr.compute_colocalization(
    image=corrected_stack,
    mask=seg.mask_path,
    channel_a="ALIX",
    channel_b="LAMP1",
    channel_names=loader.get_channel_names(),
    thresholding="otsu",
)

---

Documentation

Guide	Description
Workflow modes	Exploratory vs batch processing
Z-slice detection	Focus metrics and strategy comparison
Background subtraction	Methods and negative control support
Cell segmentation	Cellpose integration
Colocalization	Metrics and analysis
Puncta analysis	Spot detection with BigFISH

---

Module overview

colokroll/
├── core/                    # Configuration, utilities
├── data_processing/         # Image loading, projections (MIP, SME)
├── imaging_preprocessing/   # Z-slice detection, background subtraction
├── analysis/                # Segmentation, colocalization, puncta
└── visualization/           # Plotting tools

---

Configuration

GPU acceleration

pip install cupy-cuda12x  # For CUDA 12.x

Cellpose API

Cell segmentation uses HuggingFace Cellpose Space (no local installation required).

---

License

MIT License - see LICENSE for details.

Acknowledgments

• Cellpose for cell segmentation
• BigFISH for puncta detection
• BioIO for microscopy format support
• scikit-image for image processing

---

SaezAtienzar Lab | GitHub