Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

From Samples to Knowledge 2025: QuPath Training Course

From Samples to Knowledge 2025 (FS2K) QuPath Training Course by Zbigniew Mikulski and Sara McArdle (La Jolla Institute for Immunology). A comprehensive hands-on workshop covering multiplex immunofluor

  • Instructors:

    • Zbigniew Mikulski, PhD (Director, Advanced Light Microscopy and Histology Core, La Jolla Institute for Immunology)

    • Sara McArdle, PhD (Image Analysis Specialist, Advanced Light Microscopy and Histology Core, La Jolla Institute for Immunology)

  • Institution: La Jolla Institute for Immunology (LJI), San Diego, CA

  • Format: 2-Day Hands-On Workshop Recordings (February 24–25, 2025)

  • YouTube Playlist: From Samples to Knowledge 2025: QuPath Training Course

  • Step-by-Step Training Book: saramcardle.github.io/FS2K

  • GitHub Repository: saramcardle/FS2K

  • Software Target: QuPath v0.6.0 or later (leveraging Deep Java Library / DJL, Extension Manager, and modern scripting engines)

  • Data & Backup Projects: Google Drive Training Assets (Featuring 18-plex single-scan RareCyte Orion immunofluorescence data and matched H&E tonsil sections)

Course Architecture & Core Philosophy

The From Samples to Knowledge 2025 (FS2K) workshop is a comprehensive practical curriculum designed to guide biomedical researchers and pathologists from raw whole-slide multiplexed microscopy through rigorous, publication-grade spatial analysis.

Foundational Principles

  1. Imaging is Not Flow Cytometry: High-plex imaging is fundamentally continuous, spatial, and optical. Unlike single-cell suspension cytometry, multiplex tissue imaging must account for partial-volume effects, out-of-plane fluorescence, lateral membrane bleed-through across tight tissue architectures, and physical pixel dimensions (325 nm pixel size vs. 10 nm cell membranes).

  2. Honesty as a Research Strategy: Active confrontation of autofluorescence, background binding, and non-specific antibody uptake rather than superficial post-hoc cosmetic clipping.

  3. Data Integrity & Project Hygiene: Separating temporary RAM objects from on-disk .qp-proj and classifiers/ state. Ensuring strict versioning and directory decoupling to allow team collaboration across workstations.

  4. The Automation Imperative: De-cluttering manual GUI workflows from the Workflow tab into modular, commented Groovy scripts executed via Run for Project for reproducible science.

  5. Avoiding Statistical Traps: Treating individual cells as technical measurements rather than biological replicates ($N=10,000$ cells from one mouse slide is still $N=1$). Utilizing SuperPlots and nested hierarchical modeling.

Complete Curriculum & Technical Modules

Module 1: Introduction to Multiplexed Bioimage Analysis

  • Video: Introduction (28 min)

  • Topics:

    • The RareCyte Orion platform: 18-channel single-scan whole-slide imaging.

    • Bioimage fundamentals: Images as multidimensional arrays of numbers.

    • Spatial constraints: 325 nm optical resolution vs. sub-cellular macromolecular structures.

    • Lookup Tables (LUTs): Mapping high-dynamic-range 16-bit sensor data onto standard 8-bit monitor color spaces using histogram windowing.

    • Addressing spectral bleed-through, tissue autofluorescence, and non-specific antibody binding.

Module 2: Visualizing and Managing Multiplex Immunofluorescence Data

  • Video: Visualizing and Managing Multiplex Immunofluorescence Data in QuPath (28 min)

  • Documentation: Session 01 - Visualization

  • Topics:

    • Setting up QuPath projects for high-plex pyramidal OME-TIFF images.

    • Brightness & Contrast (Shift + C) optimization: Finding the biological signal threshold in grayscale mode before assigning false-color channels.

    • Visual integrity: Why Rendered RGB is for slides/presentations, while Original Pixels / OME-TIFF preserves scientific validity for analysis.

    • Channel management: Reordering, renaming, and hiding unstained or noisy channels (e.g. PD-L1, LAG-3).

    • Automation: Groovy script execution to automatically stamp channel names and color legends onto exported figures.

Module 3: Tissue Detection and Manual Annotations

  • Video: Tissue Detection and Manual Annotations (17 min)

  • Documentation: Session 02 - Tissue Detection

  • Topics:

    • Automated Region of Interest (ROI) generation: Threshold-based Pixel Classifier on nuclear channels (Hoechst) to outline total tissue area.

    • Geometric refinement: Mastering Brush (B), Magic Wand (W), and Polygon tools.

    • Boolean annotation math: Holding Alt while drawing to erode edges, carve out background voids, or exclude necrotic/folded zones.

    • Object hierarchy: Naming objects, managing parent-child relationships, and calculating tumor burden area fractions ($\frac{\text{Tumor Area}}{\text{Total Tissue Area}}$).

Module 4: Advanced Pixel Classification and Segmentation

  • Video: Advanced Pixel Classification and Segmentation in QuPath (36 min)

  • Documentation: Session 03 - Pixel Classifier

  • Topics:

    • Moving from manual heuristics to machine learning pixel segmentation.

    • Feature extraction kernels: Combining Gaussian blur, Laplacian of Gaussian (blob detection), and Gradient magnitude (edge detection) across spatial scales.

    • Live prediction & interactive training: Using sparse polylines and brushes to label positive/negative tissue domains.

    • Class balancing: Monitoring training pie charts to prevent classifier bias.

    • Multi-image training: Extrapolating classifiers across diverse slides to prevent batch overfitting.

    • Converting segmented pixel masks into discrete annotation objects with morphological noise filters (min object size, hole filling).

Module 5: Mastering Cell Detection: Standard Methods to Deep Learning

  • Video: Mastering Cell Detection in QuPath: From Standard Methods to Deep Learning (70 min)

  • Documentation: Session 04 - Cell Detection

  • Topics:

    • Deconstruction of QuPath internal project storage: .qpproj JSON structure, image URIs, and directory path re-linking.

    • Conventional cell detection: Classical optical watershed parameters (Sigma, threshold, min/max nuclear area, cell expansion radius).

    • Deep Learning in QuPath 0.6+: Integration with Deep Java Library (DJL) and PyTorch engines.

    • InstanSeg: State-of-the-art multi-channel boundary instance segmentation running natively without Python overhead.

    • Model benchmarking: Practical trade-offs between StarDist (star-convex nuclear models), Cellpose (gradient-flow generalised cell bodies), and Segment Anything Model (SAM) for atypical morphologies.

Module 6: Automating Workflows with Scripting

  • Video: Automating Workflows with Scripting (33 min)

  • Documentation: Session 05 - Workflows to Scripts

  • Topics:

    • The QuPath Workflow Tab: Translating user actions into an immutable command history.

    • Cleaning and structuring Groovy scripts: Removing interactive GUI redundancies, setting image types programmatically, and parameterizing paths.

    • Scripting AI detection (InstanSeg / StarDist) within target parent annotations.

    • Batch automation: Running Groovy pipelines over whole cohorts using Run for Project.

    • Memory management: Understanding JVM heap allocation, tile caching, and garbage collection during batch execution.

Module 7: Object Classification and Validation Strategies

  • Video: Object Classification and Validation Strategies (80 min)

  • Documentation: Session 06 - Classifying Cells pt1

  • Topics:

    • Adding multi-channel intensity measurements (mean, min, max, standard deviation) across nucleus, cytoplasm, and full cell compartments.

    • Single Measurement Classifier: Thresholding single channels to discard anuclear segmentation debris.

    • Machine learning object classifiers (Random Forests / RTrees): Training on cell detections using the Points and Brush tools.

    • Statistical validation: Building confusion matrices, evaluating sensitivity and specificity, and the crucial rule: Never report raw training accuracy as model performance.

Module 8: Optimizing Complex Phenotyping and Large Datasets

  • Video: Optimizing Complex Phenotyping and Large Datasets (60 min)

  • Documentation: Session 07 - More Difficult Classifiers

  • Topics:

    • Large dataset optimization: Removing irrelevant non-target detections (e.g., non-immune cells) to reduce multi-gigabyte project overhead.

    • Texture feature engineering: Calculating Haralick texture features (angular second moment, contrast, correlation, entropy) to capture chromatin distribution and membrane textures.

    • Variable Importance Logging: Inspecting the QuPath log to prune uninformative channels and prevent over-parameterization.

    • Hierarchical gating strategies: Isolating leukocytes ($CD45^+$) first, followed by sub-lineage classification ($CD4^+$ helper T-cells vs. $CD8^+$ cytotoxic T-cells vs. $FOXP3^+$ Tregs).

Module 9: Combining Classifiers into Multiplex Phenotypes

  • Video: Combining Classifiers (36 min)

  • Documentation: Session 08 - Creating Multiplex Classifiers

  • Topics:

    • Building Composite Classifiers: Stacking independent binary classifiers into combinatorial phenotypes (e.g., $CD45^+ : CD8^+ : PD\text{-}1^+$).

    • Managing exclusive vs. overlapping population counts.

    • Validating rare subsets: Identifying rare double-positive cells (such as $CD8^+ / FOXP3^+$) using the Channel Viewer and custom Class Visibility scripts.

    • Assembling complete automated phenotyping pipelines into 3-line Groovy scripts for project-wide execution.

Module 10: From Pixels to Publications—Exporting and Refining Data

  • Video: From Pixels to Publications—Exporting and Refining Data (28 min)

  • Documentation: Session 09 - Data Export and Simplification

  • Topics:

    • Selective measurement export: Exporting annotation summaries vs. single-cell detection TSV/CSV tables.

    • Calculating spatial density metrics: Normalizing cell counts to tissue surface area ($\text{cells}/\text{mm}^2$).

    • Avoiding the pseudo-replication trap: Explaining why $t$-tests on thousands of pooled single cells produce false-positive $p$-values.

    • Data presentation: Designing SuperPlots and nested hierarchical plots to communicate biological variance alongside technical variance.

    • Character encoding fixes: Preserving UTF-8 formatting (micrometer symbols $\mu\text{m}$, degree signs) in Microsoft Excel and statistical packages.

Module 11: Combining Images and Multimodal Image Registration

  • Video: Combining Images and Image Registration (55 min)

  • Documentation: Session 10 - Combining Images

  • Topics:

    • Multimodal slide alignment: Registering 18-plex fluorescence images with brightfield H&E on the same or adjacent tissue sections.

    • Warpy Extension: Installing and configuring qupath-extension-warpy via the QuPath Extension Manager.

    • The "Pseudo-H&E" transformation: Inverting fluorescence channels into synthetic brightfield H&E color vectors to drive cross-modal feature matching.

    • Affine transformation matrices: Coarse translation and rotation followed by fine iterative feature alignment down to 1-pixel tolerance.

    • Transforming and warping vector objects: Transferring cell boundaries and annotations seamlessly across modalities.

Module 12: Spatial Analysis and Quantifying Cell-to-Cell Interactions

  • Video: Spatial Analysis and Quantifying Cell-to-Cell Interactions (74 min)

  • Documentation: Session 12 - Spatial Analysis

  • Topics:

    • Moving beyond abundance to spatial architecture.

    • Smoothed Features: Incorporating neighborhood context into cell objects (distance-weighted averaging of neighboring phenotypes).

    • Proximity metrics: Running Signed Distance Transforms to measure the exact Euclidean distance ($\mu\text{m}$) from individual immune cells to tumor margins or blood vessels.

    • Hotspot mapping: Building spatial Density Maps with adjustable Gaussian smoothing radii.

    • Spatial statistics: Calculating cellular Enrichment Ratios to evaluate whether cell-cell proximity deviates from random spatial distribution.

Module 13: Exporting Data for Clustering, Python, and Spatial Modeling

  • Video: Exporting Data for Clustering, Python, and Spatial Modeling (42 min)

  • Documentation: Clustering using Python

  • Topics:

    • Bridging QuPath with the broader Python scientific stack (Scanpy, Squidpy, AnnData).

    • Exporting unique Object IDs and centroid coordinates to maintain bi-directional mapping.

    • QuBylab & Paquo: Connecting Jupyter notebooks directly to live QuPath sessions via local gateway socket ports.

    • Data preprocessing: Handling missing values, log-transforming intensities, and z-score normalization.

    • Unsupervised discovery: Dimensionality reduction via UMAP and Leiden/Louvain clustering to discover unannotated cell subsets.

    • Re-importing Python cluster assignments back into QuPath as new classification layers.

Module 14: Workshop Logistics & Advanced User Forum

Methodological Summary for Digital Pathology Workflows

Stage
QuPath Tool / Technique
Purpose / Impact

I/O & Setup

OME-TIFF / Project Directory

Native multi-channel pyramidal rendering; preserves 16-bit physical pixel depth

Tissue ROI

Pixel Classifier (Threshold)

Rapid whole-slide tissue segmentation, background exclusion, tumor burden quantification

Segmentation

InstanSeg / DJL / Watershed

State-of-the-art multi-channel boundary instance segmentation inside the JVM

Automation

Groovy Scripting / Run for Project

Headless, batch execution across multi-terabyte slide cohorts with audit histories

Phenotyping

Random Forest / Composite Classifiers

Hierarchical multi-marker gating ($CD45 \to CD8/CD4 \to \text{PD-1}$) with Haralick texture features

Registration

Warpy (qupath-extension-warpy)

Multi-modal alignment bridging multiplex IF and diagnostic H&E via pseudo-H&E transforms

Spatial Ecology

Smoothed Features & Distance Transforms

Microenvironmental cell-to-cell proximity, tumor infiltration margins, and density maps

External Interop

Paquo / QuBylab / GeoJSON / TSV

Seamless integration into Python single-cell and spatial transcriptomics pipelines

PreviousCognitive biases in AI-assisted medical decision making: A structured review as a primer for veterinary and human pathology
NextNavigating foundation model selection in digital pathology through performance evaluation and tradeoff analysis

Last updated