Perform SingleR in batch effect workflow #448

Activity

1. wanruiwen-genomics-cn

   added

   cursor-fixfix issue by cursor automations&agentfix issue by cursor automations&agent

   and removed

   cursor-fixfix issue by cursor automations&agentfix issue by cursor automations&agent

   on May 25, 2026
2. wanruiwen-genomics-cn commented on May 25, 2026

   

   wanruiwen-genomics-cn

   on May 25, 2026

   Collaborator

   More actions

   Dear @synatkeamsk,

   Thank you for reaching out and for your interest in Stereopy!

   Short answer: SingleR can be used in a batch effect (multi-sample) workflow by calling it on the integrated/merged data after batch correction, or by running it independently on each sample using the mode='isolated' parameter. Below are concrete code examples for both approaches.

   ---

   Assessment

   • Type: usage/question
   • Severity: low
   • Affected module: stereo/algorithm/single_r/single_r.py

   What Is Happening

   SingleR in Stereopy is implemented as a single-sample algorithm (it subclasses AlgorithmBase, not MSDataAlgorithmBase). However, the MSData pipeline has a generic fallback mechanism that allows you to call SingleR through ms_data.tl.single_r(...) in two modes:

   1. Integrate mode (default): merges all scoped samples into one combined dataset, then runs SingleR on the merged data. This is typically what you want after batch correction.
   2. Isolated mode: runs SingleR independently on each sample in parallel.

   Is This Expected?

   Yes. SingleR was designed and documented for single-sample use, but the MSData pipeline routing makes it accessible in multi-sample workflows through the generic fallback.

   Recommended Workflow

   Step 1: Complete your batch effect workflow as usual

   Follow the Batch Effect tutorial to load, integrate, and cluster your samples:

   # After batch correction and clustering on ms_data
   # e.g., ms_data.tl.pca(), ms_data.tl.neighbors(), ms_data.tl.leiden(), etc.

   Step 2: Prepare your reference data

   Load or create a reference StereoExpData object with known cell-type labels:

   import stereo as st
   
   # Load your reference data (e.g., from an H5AD file with known annotations)
   ref_data = st.io.read_h5ad(file_path='path/to/reference.h5ad', use_raw=False, use_result=True)

   Make sure the reference has cell-type labels stored in ref_data.tl.result under the key you specify in ref_use_col.

   Step 3 (Option A): Run SingleR on the merged/integrated data (recommended)

   After batch correction, the MSData object contains a merged dataset. You can run SingleR on it directly:

   # This uses integrate mode (default) - runs on the merged data
   ms_data.tl.single_r(
       ref_exp_data=ref_data,
       ref_use_col='celltype',       # column name in reference with cell-type labels
       cluster_res_key='leiden',      # optional: annotate at cluster level instead of cell level
       res_key='annotation'           # result key to store annotations
   )

   Alternatively, you can access the merged data directly:

   # Access the merged StereoExpData after integration
   merged_data = ms_data.integrate_data
   merged_data.tl.single_r(
       ref_exp_data=ref_data,
       ref_use_col='celltype',
       cluster_res_key='leiden',
       res_key='annotation'
   )

   Step 3 (Option B): Run SingleR on each sample independently

   If you prefer per-sample annotation:

   # This runs SingleR on each sample separately in parallel
   ms_data.tl.single_r(
       ref_exp_data=ref_data,
       ref_use_col='celltype',
       cluster_res_key='leiden',
       res_key='annotation',
       mode='isolated'
   )

   Step 4: Visualize the results

   # Plot the annotation results on UMAP
   ms_data.tl.umap()
   ms_data.plt.umap(res_key='annotation', title='SingleR Annotation')

   Useful References

   Resource	Purpose
   SingleR Tutorial	Single-sample SingleR usage
   Batch Effect Tutorial	Multi-sample batch correction workflow
   Cell Type Annotation	Alternative annotation method

   Alternative Approaches

   If SingleR does not give satisfactory results in the multi-sample context:

   • Option A: Use data.tl.annotation() for manual cluster-to-cell-type mapping after inspecting marker genes
   • Option B: Use the CellTypeAnno tool (data.tl.cell_type_anno()) which uses FANTOM5 reference data for annotation
   • Option C: Export the merged data to AnnData format and use scanpy/celltypist for annotation, then import labels back

   Notes

   • When using cluster_res_key, make sure clustering has been run first (e.g., leiden or louvain)
   • The reference data must share a common gene space with your test data for meaningful annotation
   • For large datasets, consider using cluster_res_key to annotate at the cluster level, which is significantly faster
   • If your reference data is in AnnData format with labels in .obs, you may need to load it appropriately and ensure labels are accessible via ref_data.tl.result[ref_use_col]

   Please let us know if you have further questions!

   Best regards,
   Stereopy Maintainer
3. synatkeamsk commented on Jun 11, 2026

   

   synatkeamsk

   on Jun 11, 2026

   Last edited by synatkeamsk

   Author

   More actions

   Hi Stereopy team,

   Could you help clarify whether MouseScRNAseqData.h5ad is the correct reference dataset for SingleR annotation for mouse tumor. http://upload.dcs.cloud:8090/share/bb6fab82-2c16-46b2-a95e-6931338f31bf

   I downloaded this data using the below command in Bash Shell.
   wget "http://upload.dcs.cloud:8090/share/bb6fab82-2c16-46b2-a95e-6931338f31bf/download?path=%2FDemo_SingleR%2FReference%2FMouseRNAseqData.h5ad" -O MouseRNAseqData.h5ad

   Kindly let me know whethe this is the correct dataset.

   Thanks,

   Synat