CosMxScope: Scalable Reconstruction and Digital Pathology Integration of Imaging-Based Spatial Transcriptomics Data

This paper introduces CosMxScope, an open-source Python framework that bridges the gap between CosMx Spatial Molecular Imager data and digital pathology tools by stitching image tiles, converting spatial coordinates into GeoJSON for QuPath compatibility, and enabling interactive visualization of gene expression alongside cell morphology.

The Gist

Imagine you have a massive, incredibly detailed map of a bustling city. This map doesn't just show the streets; it tells you exactly what every single person in the city is thinking, what they are wearing, and where they are standing, down to the millimeter.

This is essentially what CosMx Spatial Transcriptomics does for biology. It looks at a tiny slice of tissue (like a piece of skin or a tumor) and maps out thousands of genes for every single cell, keeping track of exactly where they are located.

However, there's a problem. The data comes out in a format that looks like a giant puzzle made of thousands of tiny, disconnected square tiles. While scientists can read the data, it's very hard to look at it as a whole picture, especially for doctors (pathologists) who are used to looking at standard microscope slides of tissue. They can't easily put this "gene puzzle" on top of their usual tissue images to see how the biology matches the physical structure.

Enter "CosMxScope."

Think of CosMxScope as a magical digital glue and translator that solves this problem. Here is how it works, using some everyday analogies:

1. The Puzzle Solver (Image Reconstruction)

When you get the data from the machine, it's like having a jigsaw puzzle where the pieces are scattered in a box, and you don't know which piece goes where.

• What CosMxScope does: It acts like a super-fast robot that looks at the coordinates of every puzzle piece (the "Field of View" tiles) and snaps them together perfectly.
• The Result: It creates one giant, seamless, high-definition picture of the entire tissue sample, just like assembling a massive mural from thousands of small tiles.

2. The Universal Translator (GeoJSON Conversion)

The original data is written in a very specific, technical language that only the machine understands. Pathologists, however, use a different set of tools (like QuPath) that speak a different language (GeoJSON).

• What CosMxScope does: It acts as a translator. It takes the raw coordinates of the cells and the genes and converts them into a "universal language" (GeoJSON) that standard medical software can read.
• The Result: Now, the digital "outline" of every cell and the "dots" representing specific genes can be dropped directly onto the tissue image, just like putting a transparent sticker sheet over a photograph.

3. The Spotlight (Visualization)

Once the pieces are glued and translated, you need to see the story.

• What CosMxScope does: It acts like a spotlight operator in a theater. It can highlight specific areas.
  • Scenario A: "Show me where the 'cancer-fighting' immune cells are." (It lights up those specific cells).
  • Scenario B: "Show me which areas of the tissue are most active." (It creates a heat map).
• The Result: Doctors and researchers can now look at a single screen and see the tissue structure and the gene activity at the same time. They can zoom in to see if a specific gene is active right next to a specific type of cell.

Why is this a big deal?

Before this tool, looking at this kind of data was like trying to understand a movie by reading the script while the screen was turned off. You had all the information, but you couldn't see the scene.

CosMxScope turns the screen on. It allows researchers to:

• Connect the dots: See how the physical shape of a tumor relates to the genes inside it.
• Work together: Let computer scientists and medical doctors look at the exact same image and talk about it using the same visual tools.
• Find new clues: By seeing the spatial arrangement, they might discover that certain genes only turn on when cells are crowded together, a clue they would have missed if they just looked at a list of data.

In Summary

CosMxScope is a free, open-source tool that takes complex, fragmented biological data and turns it into a clear, interactive picture. It bridges the gap between high-tech gene sequencing and the traditional art of looking at tissue under a microscope, helping scientists and doctors solve the mystery of disease one cell at a time.

Technical Summary

1. Problem Statement

The CosMx Spatial Molecular Imager (SMI) is a leading platform for single-cell spatial multi-modal omics, capable of profiling thousands of RNA or protein targets at subcellular resolution across whole tissue sections. However, the data exported from the CosMx AtoMx analysis platform presents significant integration challenges:

• Format Incompatibility: The raw outputs consist of field-of-view (FOV) image tiles, subcellular transcript coordinates, and cell segmentation polygons. These are not natively compatible with widely used digital pathology tools (e.g., QuPath) used for histopathological annotation and analysis.
• Workflow Gap: While general spatial omics frameworks exist (e.g., Giotto, Seurat, Squidpy), there is a lack of lightweight, specialized tools that bridge CosMx-specific outputs directly into histopathology visualization environments.
• Scalability Issues: CosMx experiments generate massive datasets (millions of transcript coordinates and large image tiles), requiring efficient memory management and parallel processing that standard scripts often lack.

2. Methodology: CosMxScope Framework

CosMxScope is a lightweight, open-source Python framework designed to transform AtoMx outputs into formats compatible with digital pathology workflows. It operates through three core functional modules:

A. Whole-Slide Image (WSI) Reconstruction

• Input: Individual multi-channel FOV image tiles (4256 × 4256 pixels) and a position file defining the top-left coordinates of each tile.
• Process:
  • Calculates the global bounding box based on minimum and maximum FOV coordinates.
  • Utilizes memory-mapped arrays to stitch tiles onto a common canvas without loading the entire dataset into RAM, ensuring scalability.
  • Employs joblib for parallel batch processing of tile assembly.
• Output: A full-resolution stitched image, a 20x downsampled overview image, and a "post-stitch" CSV file mapping FOV coordinates to the global image space.

B. GeoJSON Construction for Spatial Data

• Objective: Convert cell segmentation polygons and transcript coordinates into GeoJSON (a standard format for geometric objects) compatible with QuPath (v0.5+).
• Process:
  • Transforms local FOV pixel coordinates into global stitched image coordinates using the post-stitch position file.
  • Constructs a FeatureCollection where each cell is a polygon feature with properties (ID, cell type, lock status).
  • Optimization: Uses Polars with lazy query execution to handle massive transcript tables (millions of rows). It performs lazy joins between position and transcript tables, applies coordinate transformations as column expressions, and filters for genes of interest before materializing the data to minimize memory usage.
  • Transcript coordinates are converted into MultiPoint features associated with their parent cells.

C. Spatial Gene Expression Visualization

• Process:
  • Generates a background canvas from the downsampled stitched image.
  • Detects tissue regions using Gaussian blurring and Otsu thresholding.
  • Maps cell centroids and transcript locations to the downsampled resolution.
  • Supports Single-Gene Mode (one figure per gene) and Multi-Gene Mode (overlaying multiple genes with distinct colors).
• Visualization Levels:
  • Cell Level: Continuous color scales representing transcript signal intensity per cell.
  • FOV Level: Aggregates mean expression per FOV, rendered as color-coded tiles for rapid spatial overview.

3. Key Contributions

• Bridging the Gap: CosMxScope is the first dedicated tool to seamlessly integrate CosMx SMI data with digital pathology platforms like QuPath, enabling the overlay of molecular data on histological images.
• Scalability: The framework addresses the "big data" challenge of spatial transcriptomics through memory-mapped arrays, parallel processing (joblib), and lazy evaluation (Polars), allowing it to handle experiments with millions of transcripts without crashing.
• Interoperability: By outputting standard GeoJSON and CSV files, it allows researchers to perform iterative, human-in-the-loop analysis where pathologists can annotate, refine, and validate cell/tissue boundaries directly on the reconstructed images.
• Accessibility: Designed as a lightweight framework with a focus on simplicity, it is accessible to researchers without extensive computational expertise. It includes synthetic data generators and example notebooks for immediate testing.

4. Results

• Workflow Validation: The authors demonstrated a complete workflow where AtoMx exports were reconstructed into whole-slide images, and cell/transcript data was converted to GeoJSON.
• Application: The tool has been successfully deployed in multiple ongoing research projects involving human and mouse tissues, covering areas such as pre-malignancy, cancer metastasis, and immunotherapy biomarkers.
• Pathologist Integration: The ability to overlay GeoJSON annotations on histological images allowed for iterative expert assessment by pathologists, a capability previously unavailable for CosMx data.
• Visualization: The system successfully generated interpretable spatial expression patterns, including co-localization of transcripts and density maps at both cell and FOV levels.

5. Significance and Future Directions

• Translational Impact: CosMxScope facilitates the integration of molecular spatial data with traditional histopathology, a critical step for translational research and clinical diagnostics. It enables the validation of computational findings against morphological features.
• Human-in-the-Loop Analysis: Unlike purely computational pipelines, CosMxScope supports a workflow where domain experts (pathologists) can interactively inspect and refine spatial annotations, improving the accuracy of downstream analysis.
• Limitations: Currently tailored specifically to CosMx/AtoMx file structures and hardcoded tile dimensions. Visualization is primarily at downsampled resolution, which may obscure fine subcellular details in specific contexts.
• Future Work: Planned developments include expanding compatibility to other spatial omics platforms, adding a command-line interface (CLI), and creating interactive web-based visualization modules to further unify transcriptomic, proteomic, and imaging modalities.

In summary, CosMxScope solves a critical interoperability bottleneck in the spatial transcriptomics ecosystem, providing a scalable, open-source bridge between high-plex molecular imaging and standard digital pathology workflows.