single-to-spatial-mapping_skill

Overview

This skill maps single-cell RNA-seq atlases onto spatial transcriptomics slides using omicverse's Single2Spatial workflow. It trains a deep-forest mapper (or loads checkpoints) to reconstruct spot-level cell-type proportions and visualise marker expression on Visium-style spatial coordinates. The outcome is reconstructed spatial AnnData objects and spot-level QC summaries ready for downstream analysis and reporting.

How this skill works

The workflow takes a processed, log-normalised scRNA-seq reference and a spatial transcriptomics count matrix with x/y coordinates, then trains a deep-forest model to generate pseudo-spots and learn mapping from cell mixtures to spot profiles. Training produces reconstructed per-cell and per-spot AnnData outputs and aggregated spot-level proportions. The skill includes utilities for loading pretrained weights, performing spot-level assessment, plotting marker genes and cell-type proportion maps, and exporting results.

When to use it

• You have a quality-controlled, log-normalised single-cell reference and Visium-style spatial data to map cell types spatially.
• You want spot-level cell-type proportion estimates for integration with histology or downstream spatial analysis.
• You need to visualise marker genes or reconstructed cell assignments across spatial coordinates.
• You have pretrained Single2Spatial checkpoints to skip expensive retraining and quickly regenerate outputs.

Best practices

• Ensure scRNA-seq input is log-normalised; raw counts cause scale mismatches and poor predictions.
• Include accurate spatial coordinate columns (e.g., 'xcoord','ycoord') and set spot_key accordingly when initialising the model.
• Start with moderate predicted_size and learning rate; reduce predicted_size or learning_rate if training diverges.
• Save both reconstructed per-cell and aggregated per-spot AnnData (.h5ad) and export CSV summaries for reproducibility and reporting.
• When using GPU, verify availability; fallback to CPU by omitting gpu or setting gpu=-1.

Example use cases

• Train Single2Spatial on PDAC single-cell and Visium slides, then plot REG1A and CLDN1 spatial expression to compare with histology.
• Load a saved checkpoint to rapidly regenerate spot-level cell-type proportions for a manuscript figure or QC table.
• Produce reconstructed cell-type maps with omicverse palettes to evaluate deconvolution quality across tissue regions.
• Generate aggregated spot AnnData for downstream spatial statistics, spatially variable gene tests, or integration with image features.