Spatial Transcriptomics Tutorials With Omicverse

Spatial transcriptomics tutorials with omicverse

Overview

Use this skill to navigate the spatial analysis tutorials located under Tutorials-space. The notebooks span preprocessing utilities (t_crop_rotate.ipynb, t_cellpose.ipynb), deconvolution frameworks (t_decov.ipynb, t_starfysh.ipynb), and downstream spatial modelling or integration tasks (t_cluster_space.ipynb, t_staligner.ipynb, t_spaceflow.ipynb, t_commot_flowsig.ipynb, t_gaston.ipynb, t_slat.ipynb, t_stt.ipynb). Follow the staged instructions below to match the "Preprocess", "Deconvolution", and "Downstream" groupings presented in the notebooks.

Instructions

Preprocess

1. Load spatial slides and manipulate coordinates
   • Import omicverse as ov, scanpy as sc, and enable plotting defaults with ov.plot_set() or ov.plot_set(font_path='Arial'). t_crop_rotate.ipynb
   • Fetch public Visium data via sc.datasets.visium_sge(...), inspect adata.obsm['spatial'], and respect uns['spatial'][library_id]['scalefactors'] when rescaling coordinates for high-resolution overlays.
   • Apply region selection and alignment helpers: ov.space.crop_space_visium(...) for bounding-box crops, ov.space.rotate_space_visium(...) followed by ov.space.map_spatial_auto(..., method='phase'), and refine offsets with ov.space.map_spatial_manual(...) before plotting using sc.pl.embedding(..., basis='spatial').
2. Segment Visium HD tiles into cells
   • Organise Visium HD outputs (binned parquet counts, .btf histology) and load them through ov.space.read_visium_10x(path, source_image_path=...). t_cellpose.ipynb
   • Filter sparse bins (ov.pp.filter_genes(..., min_cells=3) and ov.pp.filter_cells(..., min_counts=1)) prior to segmentation.
   • Run nucleus/cell segmentation variants: ov.space.visium_10x_hd_cellpose_he(...) for H&E, ov.space.visium_10x_hd_cellpose_expand(...) to grow labels across neighbouring bins, and ov.space.visium_10x_hd_cellpose_gex(...) for gene-expression driven seeds. Harmonise labels with ov.space.salvage_secondary_labels(...) and aggregate to cell-level AnnData using ov.space.bin2cell(..., labels_key='labels_joint').
3. Initial QC for downstream tasks
   • For Visium/DLPFC re-analyses, compute QC metrics (sc.pp.calculate_qc_metrics(adata, inplace=True)) and persist intermediate AnnData snapshots (adata.write('data/cluster_svg.h5ad', compression='gzip')) for reuse across tutorials. t_cluster_space.ipynb

Deconvolution

4. Configure single-cell references and spatial targets
   • Load scRNA-seq references (adata_sc = ov.read('data/sc.h5ad')) with harmonised gene IDs and spatial slides (adata_sp = sc.datasets.visium_sge(...)). t_decov.ipynb
   • Instantiate the unified wrapper ov.space.Deconvolution(...), passing shared keys like celltype_key, adata_sc, and adata_sp.
5. Execute Tangram and cell2location pipelines
   • Call decov_obj.preprocess_sc(...) / decov_obj.preprocess_sp(...) to align matrices, then run decov_obj.deconvolution(method='tangram', ...) and persist outputs with ov.utils.save(...) plus .write(...) hooks for AnnData members.
   • For cell2location, reinitialise ov.space.Deconvolution(..., method='cell2location'), train (decov_obj.deconvolution(max_epochs=...)), monitor via decov_obj.mod_sc.plot_history(...), and store models (decov_obj.save_model(...)).
   • Visualise inferred proportions using ov.space.plot_cell2location(...), sc.pl.spatial(..., color=list_of_celltypes), and ROI-focused pie charts after cropping (ov.space.crop_space_visium(...)).
6. Run Starfysh archetypal deconvolution
   • Import Starfysh utilities (from omicverse.external.starfysh import AA, utils, plot_utils, post_analysis) and prepare expression counts plus optional signature sets. t_starfysh.ipynb
   • Identify anchor spots with utils.prepare_data(...), optionally infer archetypes via AA.ArchetypalAnalysis(...), and refine signatures using utils.refine_anchors(...).
   • Train Starfysh models (utils.run_starfysh(poe=False, ...) or poe=True with histology) across multiple restarts, then parse outputs through post_analysis.load_model(...), plot_utils.pl_spatial_inf_feature(...), and cell2proportion(...) for per-cell-type maps.

Downstream

7. Spatial clustering and denoising
   • Generate embeddings using omicverse wrappers: ov.utils.cluster(..., use_rep='graphst|original|X_pca', method='mclust'), ov.space.merge_cluster(...), and evaluate ARI (adjusted_rand_score(...)). t_cluster_space.ipynb
   • Explore algorithm-specific toggles: GraphST/BINARY require precalculated latent spaces, STAGATE training (ov.utils.cluster(..., use_rep='STAGATE', ...)), and CAST for multi-slice single-cell resolution data.
8. Integrate multi-slice datasets
   • Concatenate Stereo-seq/Slide-seqV2 batches (ad.concat(Batch_list, label='slice_name', keys=section_ids)) and initialise ov.space.pySTAligner(...). t_staligner.ipynb
   • Train with STAligner_obj.train_STAligner_subgraph(...), call STAligner_obj.train(), and retrieve latent embeddings via STAligner_obj.predicted() before clustering (sc.pp.neighbors(..., use_rep='STAligner'), ov.utils.cluster(...)).
9. Model spatial gradients and trajectories
   • For pseudo-spatial maps, build sf_obj = ov.space.pySpaceFlow(adata) and train using sf_obj.train(spatial_regularization_strength=0.1, ...), then compute sf_obj.cal_pSM(...) to populate adata.obs['pSM_spaceflow']. t_spaceflow.ipynb
   • Analyse transition dynamics with STT_obj = ov.space.STT(adata, spatial_loc='xy_loc', region='Region'), followed by STT_obj.train(...), STT_obj.stage_estimate(), and downstream visualisations (STT_obj.plot_pathway(...), STT_obj.infer_lineage(...)). t_stt.ipynb
10. Infer communication and flow networks
    • Pull ligand–receptor resources via ov.external.commot.pp.ligand_receptor_database(species='human'), filter with filter_lr_database(...), and compute signaling using ov.external.commot.tl.spatial_communication(...). t_commot_flowsig.ipynb
    • Construct FlowSig inputs (adata.layers['normalized'] = adata.X.copy(), ov.external.flowsig.tl.construct_intercellular_flow_network(...)), retain spatially informative modules (Moran’s I filtering), and validate edges through bootstrapping thresholds (edge_threshold = 0.7).
11. Extract structural layers and align developmental slices
    • Train GASTON with gas_obj = ov.space.GASTON(adata), rescale GLM-PC matrices via gas_obj.load_rescale(A), and infer iso-depths using gas_obj.cal_iso_depth(n_layers). Visualise with gas_obj.plot_isodepth(...), gas_obj.plot_clusters_restrict(...), and probe continuous/discontinuous gene lists (gas_obj.cont_genes_layer). t_gaston.ipynb
    • For SLAT, construct spatial graphs (Cal_Spatial_Net(adata1, k_cutoff=20)), run alignment (run_SLAT(...), spatial_match(...)), and examine correspondences through Sankey diagrams (Sankey_multi(...)) and lineage-focused subsetting (cal_matching_cell(...)). t_slat.ipynb