Single2Spatial spatial mapping

Overview

Apply this skill when converting single-cell references into spatially resolved profiles. It follows [tsingle2spatial.ipynb](../../omicverseguide/docs/Tutorials-bulk2single/t_single2spatial.ipynb), demonstrating how Single2Spatial trains on PDAC scRNA-seq and Visium data, reconstructs spot-level proportions, and visualises marker expression.

Instructions

1. Import dependencies and style

- Load omicverse as ov, scanpy as sc, anndata, pandas as pd, numpy as np, and matplotlib.pyplot as plt. - Call ov.utils.ovplotset() (or ov.plot_set() in older versions) to align plots with omicverse styling.

1. Load single-cell and spatial datasets

- Read processed matrices with pd.readcsv(...) then create AnnData objects (anndata.AnnData(rawdf.T)). - Attach metadata: singledata.obs = pd.readcsv(...)[['Celltype']] and spatialdata.obs = pd.read_csv(... ) containing coordinates and slide metadata.

1. Initialise Single2Spatial

- Instantiate ov.bulk2single.Single2Spatial(singledata=singledata, spatialdata=spatialdata, celltypekey='Celltype', spotkey=['xcoord','ycoord'], gpu=0). - Note that inputs should be normalised/log-scaled scRNA-seq matrices; ensure spotkey matches spatial coordinate columns.

1. Train the deep-forest model

- Execute stmodel.train(spotnum=500, cellnum=10, dfsavedir='...', dfsavename='pdacdf', k=10, numepochs=1000, batchsize=1000, predictedsize=32) to fit the mapper and generate reconstructed spatial AnnData (spadata). - Explain that spotnum defines sampled pseudo-spots per iteration and cellnum controls per-spot cell draws.

1. Load pretrained weights

- Use stmodel.load(modelsize=14478, dfloaddir='.../pdacdf.pth', k=10, predicted_size=32) when checkpoints already exist to skip training.

1. Assess spot-level outputs

- Call stmodel.spotassess() to compute aggregated spot AnnData (spadataspot) for QC. - Plot marker genes with sc.pl.embedding(spadata, basis='Xspatial', color=['REG1A', 'CLDN1', ...], frameon=False, ncols=4).

1. Visualise proportions and cell-type maps

- Use sc.pl.embedding(spadataspot, basis='Xspatial', color=['Acinar cells', ...], frameon=False) to highlight per-spot cell fractions. - Plot spadata coloured by Celltype with palette=ov.utils.ovpalette()[11:] to show reconstructed assignments.

1. Export results

- Encourage saving generated AnnData objects (spadata.writeh5ad(...), spadataspot.write_h5ad(...)) and derived CSV summaries for downstream reporting.

1. Defensive validation

``python # Before Single2Spatial: verify spatial coordinates exist for col in spotkey: assert col in spatialdata.obs.columns, f"Spatial coordinate column '{col}' not found in spatialdata.obs" # Verify scRNA-seq is log-normalized (max should be <~15, not hundreds/thousands) if singledata.X.max() > 50: print("WARNING: scRNA-seq data may not be log-normalized. Raw counts cause scale mismatches.") # Verify cell type column exists assert celltypekey in singledata.obs.columns, f"Cell type column '{celltype_key}' not found" ``

1. Troubleshooting tips

- If training diverges, reduce learningrate via keyword arguments or decrease predictedsize to stabilise the forest. - Ensure scRNA-seq inputs are log-normalised; raw counts can lead to scale mismatches and poor spatial predictions. - Verify GPU availability when gpu is non-zero; fallback to CPU by omitting the argument or setting gpu=-1.

Examples

• "Train Single2Spatial on PDAC scRNA-seq and Visium slides, then visualise REG1A and CLDN1 spatial expression."
• "Load a saved Single2Spatial checkpoint to regenerate spot-level cell-type proportions for reporting."
• "Plot reconstructed cell-type maps with omicverse palettes to compare against histology."

References

• Tutorial notebook: [tsingle2spatial.ipynb](../../omicverseguide/docs/Tutorials-bulk2single/t_single2spatial.ipynb)
• Example datasets and models: [omicverseguide/docs/Tutorials-bulk2single/data/pdac/](../../omicverseguide/docs/Tutorials-bulk2single/data/pdac/)
• Quick copy/paste commands: [reference.md](reference.md)