KaroSpace: a rapid-access framework for interactive exploration of multi-sample spatial omics data

KaroSpace is a lightweight, flexible framework designed to overcome computational and proprietary barriers by enabling rapid, interactive exploration of multi-sample and multi-modality spatial omics data for hypothesis generation and collaborative analysis.

The Gist

Imagine you have a massive, incredibly detailed 3D map of a bustling city. But instead of streets and buildings, this map shows every single cell in a piece of tissue, along with the specific genes they are "speaking" (expressing) at that moment. This is what spatial omics data is: a high-resolution snapshot of life inside your body.

The problem? These maps are so huge and complex that they are like trying to navigate a city the size of the entire United States using a tiny, slow paper map. Scientists often get stuck because the software to look at these maps is either too expensive, locked behind paywalls, or requires a supercomputer just to open the file.

Enter KaroSpace.

What is KaroSpace?

Think of KaroSpace as a magic, portable "Google Earth" for your cells.

The researchers (from Karolinska Institutet in Sweden) built a tool that takes these massive, complicated datasets and compresses them into a single, self-contained file—like a digital postcard. You don't need a powerful computer, a special server, or an internet connection to view it. You just open the file in your web browser (like Chrome or Safari), and suddenly, you can zoom in, pan around, and click on individual cells to see what they are doing.

How Does It Work? (The Analogy)

1. The Raw Data (The Messy Warehouse): Scientists usually store their data in a format called .h5ad. Imagine this as a giant, locked warehouse full of crates (cells) and blueprints (genes). It's hard to get into and requires a forklift (complex coding) to move things around.
2. The KaroSpace Builder (The Packing Service): The team created a tool called KaroSpaceBuilder. You feed it the warehouse key (the .h5ad file), and it acts like a super-efficient packing service. It organizes the crates, labels them, and packs everything into a single, lightweight suitcase (an HTML file).
3. The Viewer (The Interactive Map): When you open that suitcase in a browser, it unfolds into an interactive map.
   • The "Magic Wand": You can draw a shape around a group of cells (like circling a neighborhood in a city), and the tool instantly tells you, "Hey, this neighborhood is full of immune cells!"
   • The "Time Slider": You can slide a bar back and forth to compare two different things at once. For example, you could look at where a specific gene is active on one side of the slider and where a specific protein is on the other, seeing how they overlap in the same tissue space.
   • The "Hop" Feature: If you click on one cell, you can see its neighbors, and then the neighbors of those neighbors, like tracing a conversation spreading through a crowd.

Why Is This a Big Deal?

Before KaroSpace, if a scientist wanted to share their findings, they might have to send a 500MB file that only a few people with expensive software could open. It was like sending a DVD that only works on one specific brand of player.

KaroSpace changes the game by making the data universal:

• No Gatekeepers: It works on Mac, Windows, and Linux.
• No Servers Needed: Because the file contains everything it needs, you can email it to a colleague, and they can open it immediately.
• Massive Scale: It can handle datasets with millions of cells (like a whole mouse brain or a human lung tumor) without crashing your computer.

The Trade-off

The authors are honest about the limits. Because they prioritized making the file easy to share and open anywhere, if you try to include every single gene in the world for a massive dataset, the file might get too big and load slowly. It's a deliberate choice: they'd rather have a slightly smaller file that everyone can use instantly than a perfect file that no one can open.

The Bottom Line

KaroSpace is like giving every scientist a universal remote control for the human body's cellular map. It removes the technical barriers, allowing researchers to focus on the biology—figuring out how diseases work or how tissues heal—rather than fighting with software. It turns a locked, heavy vault of data into an open, interactive playground for discovery.

Technical Summary

1. Problem Statement

Spatial omics technologies have advanced rapidly, enabling high-resolution mapping of molecular features (transcriptomics, proteomics, epigenomics) within native tissue contexts. However, the effective interactive exploration of these datasets faces significant bottlenecks:

• Data Complexity and Scale: Datasets are growing in size (spanning millions of cells), complexity (multi-sample, multi-modality), and diversity (various platforms like Visium, Xenium, CODEX, MERFISH).
• Software Limitations: Existing solutions often rely on proprietary software, tightly coupled infrastructures, or backend servers, which hinder portability and widespread accessibility.
• Multi-Sample Gaps: Current commercial viewers typically focus on deep inspection of single samples but lack native support for comparative, multi-sample, and multi-modality exploration.
• Collaboration Barriers: The reliance on restricted access or heavy infrastructure complicates transparent data sharing and collaborative hypothesis generation.

2. Methodology

KaroSpace is a lightweight, client-side framework designed to convert preprocessed spatial omics data into self-contained, interactive HTML reports.

• Input Data Model:

  • Accepts standard .h5ad (AnnData) files exported from popular pipelines like Scanpy or Seurat.
  • Requires 2D spatial coordinates (adata.obsm["spatial"]) and a tissue section identifier.
  • Supports optional UMAP embeddings (adata.obsm["X_umap"]) and metadata columns for filtering.

• Export Pipeline & Optimization:

  • Data Extraction: Extracts cellular coordinates, metadata, precomputed color layers (categorical/continuous), and gene expression vectors.
  • Compression & Encoding: To manage file size and browser parsing speed, large numeric arrays (coordinates, graph edges) are serialized as Base64-encoded typed arrays. Gene vectors are encoded as dense or sparse arrays (auto-selecting sparse for high zero-fraction genes).
  • Graph-Aware Analysis: If a neighborhood graph exists (adata.obsp['spatial_connectivities']), KaroSpace precomputes neighborhood composition statistics and enrichment scores (via permutation testing) and calculates optimal marker genes using scanpy.tl.rank_genes_groups.

• Deployment Options:

  • Python API: Programmatic generation of reports.
  • KaroSpaceBuilder: A cross-platform desktop GUI (macOS, Windows, Linux) that guides users through input selection, inspection, and export configuration without requiring coding skills.
  • Externalization: For very large payloads (>80MB), the system can split the viewer into a directory format with chunked data files and a manifest loader, rather than a single monolithic HTML file.

• Web Portal Architecture:

  • A static web application (HTML/CSS/JS) hosted on Cloudflare Pages serves as a registry.
  • Viewer assets are hosted on Cloudflare R2.
  • Search and filtering occur client-side using metadata JSON.

3. Key Contributions & Features

KaroSpace introduces a "cell-centric" design that supports various spatial resolutions (capture array or pixel-based) across multiple platforms.

• Multi-Sample & Multi-Modality Exploration:
  • Cohort View: Provides an overview of all samples, allowing users to filter by covariates and compare datasets.
  • Dual-Feature Visualization: A "Variable Slider" allows users to sweep across the tissue to compare two opposing variables simultaneously (e.g., Annotation vs. Gene Expression, Gene vs. Chromatin Accessibility).
• Interactive Analysis Tools:
  • Magic Wand: Polygon-based cell selection with automatic aggregation of cellular composition.
  • Hops Feature: Visualizes neighboring cells at three different hop levels to explore spatial neighborhoods.
  • Annotation: Users can manually delineate tissue regions; these annotations are exported as JSON and can be mapped back to the original AnnData object for downstream analysis.
  • Insights Tab: Summarizes metadata statistics, neighborhood enrichment scores, and marker dot plots.
• Portability:
  • Generates a single, self-contained HTML file (or a lightweight directory structure) that runs entirely in the browser without a backend server.
  • Eliminates the need for proprietary licenses or complex server setups.

4. Results

The authors demonstrated the framework's flexibility by generating KaroSpace viewers for a diverse set of datasets (Table 1), including:

• Platforms: DBiT (RNA/ATAC), CODEX (Protein), MERFISH, Xenium, CosMx, Visium HD, Open-ST, HybISS, and CARTANA.
• Scale: Datasets ranging from ~6,000 cells to over 6.8 million cells (MERFISH mouse brain).
• Performance:
  • Reports ranging from ~23 MB to ~497 MB were successfully generated.
  • The system handles millions of cells effectively, though file size and loading times increase with the number of genes displayed.
  • Browser Variance: Chrome renders reports efficiently; Safari showed slower performance due to heavy reliance on Canvas-based rendering.
• Accessibility: All generated reports are accessible via the public portal at https://karospace.se.

5. Significance

• Democratization of Spatial Omics: By removing backend dependencies and proprietary barriers, KaroSpace makes complex spatial datasets accessible to a broader scientific community, including those without extensive computational resources.
• Enhanced Collaboration: The self-contained nature of the HTML reports facilitates transparent data sharing and collaborative interpretation of biological mechanisms.
• Workflow Integration: It complements existing computational workflows (Scanpy/Seurat) by providing a rapid, interactive visualization layer for hypothesis generation.
• Scalability: The framework successfully bridges the gap between massive, multi-sample datasets and user-friendly exploration, addressing a critical need as spatial omics data continues to scale in size and complexity.

Limitations & Future Work:
The authors note trade-offs between file size (driven by gene count) and portability. Future optimizations aim to address interface latency in specific browsers (like Safari) and further reduce file sizes for datasets with high gene counts.