Skip to content

🔬 Lab Tools Index

Status Legend

🟢 Active: Actively maintained.
🟡 Stable: No new features, but it works. Use as-is.
🟠 Orphaned: (Use at your own risk). Unmaintained.
🔴 Deprecated: Do not use for new projects.

Getting Started

Essential templates and starting points for new lab members.

ell_code_template

  • Status: 🟢 Active
  • Developed by: Frederic Ballllosera
  • Description: Python templates and working examples for cell image analysis workflows. Includes base and advanced templates with configuration management, logging, and batch processing. Five complete examples: cell cropping, Cellpose segmentation, micronuclei detection, Otsu thresholding, and Phenocycler QPTIFF extraction. Recently added cell cycle quantification (Oct 2025).
  • Link: https://github.com/CellProfiling/ell_code_template
  • Key Features:
    • Base template (beginner-friendly) and advanced template (parallel processing)
    • Configuration hierarchy: hardcoded → YAML → CLI arguments
    • CSV-driven batch processing
    • Shared utilities: image_handling, micronuclei analysis, cell cycle quantification
    • Thread-safe concurrent operations

      Note: Start here! Before writing a new analysis script, check this repo for a template. Actively maintained with regular feature additions.

Cell & Nuclei Segmentation

Tools for segmenting cells and nuclei in microscopy images.

HPA Cell Segmentation

  • Status: 🟡 Stable (HPA-Cell-Segmentation) / 🟢 Active (HPACellSegmentatorPortable)
  • Developed by:
    • HPA-Cell-Segmentation: Hao Xu, Fredric Johansson, Casper Winsnes
    • HPACellSegmentatorPortable: Frederic Ballllosera
  • Description: Automated cell and nuclei segmentation tools for confocal microscopy images. Uses DPN-UNet architecture with pretrained models. HPA-Cell-Segmentation is the original mature implementation (last updated Jan 2024). HPACellSegmentatorPortable is a modernized rework with updated dependencies, simplified usage, and better cross-platform support (actively maintained through Aug 2025).
  • Links:
  • Key Features:
    • Multi-channel segmentation (microtubules, ER, nuclei)
    • Pretrained models with auto-download
    • GPU acceleration (CUDA 11.2)
    • Batch processing, optional cell crops with binary masks
    • Flexible configuration (YAML, CLI, CSV batch files)

      Note: Please use HPACellSegmentatorPortable for all new projects. It works with modern Python libraries and has fewer dependency issues.

HPAConsensusSegmentatorPortable

  • Status: 🟢 Active
  • Developed by: Frederic Ballllosera, Ankit Gupta
  • Description: Label-free multi-model consensus cell and nucleus segmentation for HPA-style immunofluorescence FOVs (microtubules, ER, nucleus). Three equally voting models run on every FOV: HPACellSegmentator, Cellpose-SAM and Cellpose-dino. A cell is kept when at least two models find it, and its boundary is settled with multi-label STAPLE, weighting each model by its estimated reliability. Each consensus cell gets exactly one nucleus, and cells without a nucleus are rejected. Can also generate single-cell crops. This pipeline segmented 1,807,237 cells across 86,816 HPA v25 FOVs.
  • Link: https://github.com/CellProfiling/HPAConsensusSegmentatorPortable
  • Key Features:
    • Three models: HPACellSegmentator (bundled, no separate install), Cellpose-SAM and Cellpose-dino, with all weights downloaded automatically
    • Runs on the raw images at their native bit depth (16-bit stays 16-bit)
    • Outputs 16-bit labeled cell and nucleus masks with matching labels, bounding-box CSVs with each model's STAPLE reliability, and a QC overlay; optionally also each model's own masks
    • Optional single-cell crops (PNG or NPY) with filters for border cells, cell size and nucleus size
    • Configuration: constants → config.yaml → CLI arguments, with a CSV batch list (path_list.csv)
    • Python 3.12; a CUDA GPU is strongly recommended (it falls back to CPU, but is very slow there)

Note: Installing it needs git, because two dependencies (segment-anything and dinov3) are only available on GitHub. dinov3 is under Meta's own DINOv3 License, not MIT.

CellposeSegmentatorPortable

  • Status: 🟢 Active
  • Developed by: Frederic Ballllosera, Fredric Johansson
  • Description: A simple wrapper that runs Cellpose segmentation on grayscale FOV images, in three modes: nuclei only, nuclei + one cytoplasm marker, or nuclei + two cytoplasm markers combined (e.g. microtubules and ER). It has two backends: Cellpose cyto3 (default), run on each cytoplasm channel guided by the nuclear mask, or Cellpose-SAM, a single pass over a 3-channel stack. A custom merge step gives nuclear pixels priority, splits regions containing several nuclei and fills gaps from the second cytoplasm channel. Built on the base template of ell_code_template.
  • Link: https://github.com/CellProfiling/CellposeSegmentatorPortable
  • Key Features:
    • cyto3 backend (Cellpose 3.1) or Cellpose-SAM backend (needs Cellpose 4.x, tested with 4.1.1)
    • Optional normalization for dim or uneven nuclei, with a QC image
    • Configurable nucleus and cell diameters
    • Input images as local paths or URLs, listed in a CSV batch file (path_list.csv)
    • Outputs labeled PNG masks: nuclei, each cytoplasm channel (or the raw Cellpose-SAM mask) and the final merged cell_mask.png
    • Configuration: constants → config.yaml → CLI arguments; optional CUDA GPU (strongly recommended for Cellpose-SAM)

hpaseg

  • Status: 🟢 Active
  • Developed by: Frederic Ballllosera
  • Description: Batch segmentation and single-cell quantification for HPA-style brightfield IHC images (RGB images stained with hematoxylin for nuclei and DAB for the target protein). It separates the two stains by color deconvolution, detects nuclei with Laplacian-of-Gaussian blob detection and grows them into approximate cells, then measures per-cell intensities and calls each cell protein-positive or negative at a low and a high threshold. Uses classical image processing (scikit-image), so no deep-learning model or GPU is needed.
  • Link: https://github.com/CellProfiling/hpaseg
  • Key Features:
    • Hematoxylin/DAB color deconvolution
    • Automatic tagging of the staining distribution (weak / localized / strong), or set per image
    • Per-cell mean and 90th-percentile intensities with low/high positivity flags, in cell_data.csv
    • Also saves the segmentation mask (.npy) and overlay PNGs
    • CSV batch list (batch.csv) with per-image parameters; a failing image is logged and skipped
    • Python 3.12, with a Dockerfile and docker-compose setup included

Note: For brightfield IHC images only. For immunofluorescence images, use the segmentation tools above.

Subcellular Protein Localization

Tools for analyzing protein subcellular localization patterns.

SubCell / SubCellPortable

  • Status: 🟢 Active (both repositories)
  • Developed by: Ankit Gupta, Konstantin Kahnert, Frederic Ballllosera
  • Description: Self-supervised vision foundation model for protein subcellular localization prediction and cellular morphology analysis. subcell-embed is the research training framework for developing new models. SubCellPortable is the inference wrapper for running predictions on new datasets. SubCellPortable generates 1536-dimensional embeddings and predicts protein localization across 31 compartments from multi-channel fluorescence microscopy images.
  • Links:
  • Key Features: PyTorch-based, supports H5AD/AnnData output, GPU-accelerated batch processing, S3 download support
  • Citation: Gupta et al. (2024) bioRxiv: 10.1101/2024.12.06.627299

Embedding & Feature Extraction

Tools for generating embeddings and feature representations from microscopy images.

SubCell / SubCellPortable

  • Status: 🟢 Active
  • Developed by: Ankit Gupta, Konstantin Kahnert, Frederic Ballllosera
  • Description: Generates high-quality 1536-dimensional embeddings that capture cellular morphology and protein localization patterns. These embeddings can be used for downstream analysis, clustering, classification, and visualization tasks.
  • Links:
  • Key Features: Self-supervised learning, proteome-wide feature extraction, H5AD/AnnData output format, scanpy-compatible

    Note: See full details in Subcellular Protein Localization section above.

Cell Shape Analysis

Tools for quantifying cell and nuclear morphology.

2dShapeSpacePortable

  • Status: 🟢 Active
  • Developed by: Frederic Ballllosera, based on the research by Trang Le and Will Leineweber
  • Description: A pipeline that quantifies the shape of cells and nuclei in 2D fluorescence images and maps how a protein is distributed within those shapes. It encodes each cell and nucleus outline as Fourier coefficients, runs PCA over all cells to find the main shape modes (the "shape space") and an average cell, and then samples the protein signal in shape-aligned coordinates: either as concentric rings between the nucleus and the membrane, or by warping each cell onto the average shape. A portable, generalized version of the analysis in the Cell Shape paper.
  • Link: https://github.com/CellProfiling/2dShapeSpacePortable
  • Key Features:
    • Input: already segmented cells (a nucleus mask, a cell mask and a protein image per cell), listed in path_list.csv
    • Fourier contour encoding with several alignment options; likely segmentation errors are filtered out by their cell-to-nucleus area ratio
    • PCA shape modes, with shape-variation plots and GIFs
    • Protein maps per cell and averaged per shape-mode bin (rings or warp mode)
    • Optional comparison of subcellular locations by Pearson correlation
    • GUI (GUI.py) or command line (process.py); configuration: config.yaml → CLI flags
    • Python 3.10 or higher (tested on 3.11 and 3.12)
  • Citation: Cell Shape paper by Trang Le and Will Leineweber: https://www.sciencedirect.com/science/article/pii/S2405471226000712

Note: It needs segmented cells as input: run one of the segmentation tools first.

Image Visualization & Exploration

Tools for viewing and exploring microscopy images.

ellviewer

  • Status: 🟢 Active
  • Developed by: Frederic Ballllosera
  • Description: HTML-based multi-channel microscopy image viewer. Useful for sharing layered fluorescence images with dynamic channel controls, transparency adjustment, and zoom/pan functionality. Runs as static HTML with CSV-based configuration. Supports pyramidal tiling for high-resolution imagery (15000+ pixels). GPU-accelerated rendering with Fabric.js.
  • Link: https://github.com/CellProfiling/ellviewer
  • Key Features:
    • Static HTML deployment
    • CSV metadata file for configuration
    • Multi-channel compositing with 8-bit/16-bit support
    • Dynamic transparency, coloring, intensity clipping
    • Optional pixel-to-micron scaling
    • Python utility for pyramid generation (create_pyramid.py)

      Note: Useful for sharing JUMP pilot images and multi-channel immunofluorescence datasets. Last updated July 2025.

Data Processing Pipelines

Workflow pipelines for large-scale data processing.

JUMP-Pilot Processing Script

Image Format Conversion & Metadata (ImageJ plugins)

ImageJ plugins for converting microscope vendor-specific formats to standardized formats and processing image metadata.

TifCs_To_HPA-PNG-JPEG

  • Status: 🟢 Active
  • Developed by: Jan N. Hansen
  • Description: A Fiji ImageJ plugin that converts single-channel TIFF files into PNG/JPEG formats styled after the Human Protein Atlas. Provides intensity scaling with customizable percentile-based adjustment (16-bit to 8-bit), channel merging capabilities for multi-channel overlays, and batch processing support for consistent image adjustment across datasets. Includes white channel support for brightfield/transillumination integration.
  • Link: https://github.com/CellProfiling/TifCs_To_HPA-PNG-JPEG
  • Key Features:
    • Batch processing with grouped adjustment
    • Customizable intensity scaling (default: 0.001% to 99.999% percentiles)
    • Multi-channel merging with individual channel exports
    • White channel support for brightfield integration
    • Zenodo archival (DOI: 10.5281/zenodo.17237265)

Sp8-Lif_To_Memento

  • Status: 🟢 Active
  • Developed by: Jan N. Hansen
  • Description: A Fiji plugin designed to convert microscopy data from Leica Sp8 confocal microscopes (.lif files) into accessible formats including .ome.tif, PNG, JPG, or multi-page TIF. Supports 3D stack images and multi-channel hyperstacks with 99.9% percentile intensity scaling at the image level. Includes CSV-based metadata mapping for antibody ID, plate ID, and protein names, making output suitable for Memento projects.
  • Link: https://github.com/CellProfiling/Sp8-Lif_To_Memento
  • Key Features:
    • 3D stack and hyperstack support
    • Multiple output format options (.ome.tif, PNG, JPG, multi-page TIF)
    • CSV metadata integration
    • Intensity scaling at image level for consistency
    • Companion tool available for joint intensity scaling across wells
    • Zenodo archival (DOI: 10.5281/zenodo.15778558)

HPA_Convert_OPERA_To_LIMS-OMETIF

  • Status: 🟢 Active
  • Developed by: Jan N. Hansen
  • Description: An ImageJ plugin that converts image output from Opera Phenix and Operetta CLS microscopes into OME-TIF format with proper metadata preservation. Restructures OPERA microscope output folders into organized directory structures (LIMS-style, canonical OME-TIF, or Memento-compatible). Features coordinate correction from OPERA's well-relative system to LIMS plate-based schemes and optional automatic cropping from standard 2160×2160 pixel output.
  • Link: https://github.com/CellProfiling/HPA_Convert_OPERA_To_LIMS-OMETIF
  • Key Features:
    • Three output format options (LIMS, canonical OME-TIF, Memento)
    • Metadata transfer from OPERA XML to OME-TIF XML
    • X/Y coordinate correction for plate-based systems
    • Automatic image cropping capability
    • Batch folder processing

HPA_Convert_Sp8_To_OMETIF

  • Status: 🟢 Active
  • Developed by: Jan N. Hansen
  • Description: A Fiji plugin that converts OME-TIF files exported from Leica's LAS X microscopy software (DMi8-Sp8 or Stellaris 8) into HPA LIMS-compliant OME-TIF formats. Processes 3D viewer-exported image files from confocal microscopes with batch processing capabilities and OME XML metadata correction. Supports both z-stack and non-z-stack images.
  • Link: https://github.com/CellProfiling/HPA_Convert_Sp8_To_OMETIF
  • Key Features:
    • Batch folder processing
    • Z-stack and non-z-stack support
    • OME XML metadata correction
    • LAS X software compatibility (DMi8-Sp8, Stellaris 8)
    • Complementary to Sp8-Lif_To_Memento for different export workflows

HPA_LIMS_Channel_Selector

  • Status: 🟡 Stable
  • Developed by: Jan N. Hansen
  • Description: An ImageJ plugin developed for the HPA Sperm project that selects the best channel from two channels acquired under identical settings but with different gain or exposure times. Works exclusively with output from HPA_Convert_OPERA_To_LIMS-OMETIF, providing an important quality-control step in the image processing pipeline for dual-acquisition imaging workflows.
  • Link: https://github.com/CellProfiling/HPA_LIMS_Channel_Selector
  • Key Features:
    • Dual-channel quality selection based on acquisition parameters
    • Works with HPA_Convert_OPERA_To_LIMS-OMETIF output folder structure

      Note: Requires HPA_Convert_OPERA_To_LIMS-OMETIF as a preprocessing step. Last updated December 2023.

Infrastructure & Utilities

Scripts and utilities for lab infrastructure and data management.

backup_to_ellvault.sh

  • Status: 🟡 Stable
  • Developed by: Konstantin Kahnert
  • Description: rclone-based script for automated backups from Sherlock to ell-vault storage. Supports multiple backup modes: full directories (GROUP_HOME, GROUP_SCRATCH, SCRATCH), single folders, or batch lists from CSV. Features file locking to prevent concurrent runs, configurable verification (size-only or checksum), optional sync mode, and dry-run testing. Includes crontab examples for scheduled backups.
  • Download: backup_to_ellvault.sh
  • Sherlock Locations:
    • Utility folder: $GROUP_HOME/utils/backup_to_ellvault.sh
  • Key Features:
    • Five backup modes: --group_home, --group_scratch, --scratch, --folder, --folders-file
    • Optional --sync (mirrors, deletes remote extras), --dry-run (test mode), --checksum (thorough verification)
    • File locking with 6-hour timeout
    • Automated mapping: GROUP_HOME → ell_vault:/sherlock/group_home, etc.
    • Configured rclone settings: 32 checkers, 16 transfers, fast-list, mmap
  • Usage Examples: 
    # Backup entire group home
backup_to_ellvault.sh --group_home

# Backup specific folder
backup_to_ellvault.sh --folder "$GROUP_SCRATCH/konstantin/projectA"

# Batch backup from list
backup_to_ellvault.sh --folders-file folders_to_backup.txt

# Sync mode (careful - deletes remote extras!)
backup_to_ellvault.sh --group_scratch --sync

    Note: This is the only official script for backing up to ell-vault. Always use this instead of raw rclone commands to ensure proper locking and verification.

PyShowwwcase

  • Status: 🟢 Active
  • Developed by: Frederic Ballllosera
  • Description: A reusable Django web front-end for batch processing pipelines. It gives any command-line pipeline a multi-user web interface where users upload input files into projects, submit runs, and view the results once the pipeline finishes. The web app and the pipeline are fully decoupled: the web app only adds a job to a MariaDB queue, and cron loops launch the pipeline in its own Docker image, one run at a time. Connecting a new pipeline means copying the template and filling in a small, clearly marked block of custom code.
  • Link: https://github.com/CellProfiling/pyshowwwcase
  • Key Features:
    • File and project manager: login or guest/demo access, uploads with optional zip extraction, browse, rename, download, delete
    • Run page with a pipeline-specific form, and a queue page to follow or cancel your jobs
    • Results page per pipeline: inline images, an embedded viewer, or a redirect to an external viewer such as ellviewer
    • A template/ to start new integrations, plus three reference implementations: PIPEX, proticelli and hpaseg
    • Configuration in setup/.env (secrets, ports, hosts) and the custom section of settings.py
    • Python 3.12, Django 4.2 LTS, MariaDB; needs a host with Docker + docker compose, cron and nginx
  • Documentation: the repo's README.md (architecture), implementations.md (the reference implementations) and howto.md (step by step from the template to a new implementation)

Note: Internal lab tool, not hardened for public exposure. Guests are allowed by default and users can write the pipeline's arguments themselves, so keep any instance behind trusted networking.

Archive (Deprecated Tools)

Tools in this section are no longer recommended for new work but may be referenced in legacy projects.

hpa_densenet

  • Status: 🔴 Deprecated
  • Developed by: Casper Winsnes, Frederic Ballllosera
  • Description: DenseNet-based model for protein localization prediction in HPA images. Implements the winning solution from the HPA Kaggle Image Classification Challenge. Provides pipeline for image preprocessing, model inference, feature extraction, and UMAP-based visualization of latent features.
  • Link: https://github.com/CellProfiling/hpa_densenet
  • Key Features: 4-channel (RGBY) image processing, DPN-UNet architecture, PyTorch 2.2.1

    Note: Deprecated. For new projects, use SubCell models for more modern architectures and broader capabilities. Last updated March 2024.