Perform SingleR in batch effect workflow

[synatkeamsk]

Dear Stereopy team,

Thanks for your recent help with analysis. I'm trying to annotate my cluster using singleR. You have a section on singleR, but based on single sample tutorial https://stereopy.readthedocs.io/en/latest/Tutorials/SingleR.html.

Given I am using batch effect totorial having several sample: https://stereopy.readthedocs.io/en/latest/Tutorials%28Multi-sample%29/Batch_Effect.html. I am wondering whether you could provide a brief code for annotation using SingleR based on Batch Effect tutorial because so far, I could not make it work properly.

Looking forward to hearing from you.

Kind Regards,

Synat

[wanruiwen-genomics-cn]

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

[synatkeamsk]

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