single R annotation with GPU lacking confidence scores

[vraghu90]

Are you able to generate confidence scores for the annotations generated using a reference as part of the output when using GPU mode?

[wanruiwen-genomics-cn]

Dear @vraghu90,

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

Short answer: Currently, neither the CPU nor GPU mode of SingleR in Stereopy exposes confidence scores in the annotation output. The result DataFrame only contains cell identifiers, the final annotation label, and the first-pass label — no numeric confidence or score column is included.

---

Assessment

• Type: feature request
• Severity: low
• Affected module: stereo/algorithm/single_r/single_r.py

What Is Happening

The SingleR implementation in Stereopy returns a pandas.DataFrame with exactly three columns: bins (cell/bin identifiers), group (final annotation label after fine-tuning), and first_labels (label from initial scoring). This is the same for both the CPU path (method='default') and the GPU path (method='rapids' using cusingler).

On the CPU path, the _score_test_data method internally computes per-cell Spearman correlation scores against each reference label (stored in a DataFrame called output), but only the argmax column name is retained as first_labels — the numeric scores are not carried forward into the final result. On the GPU path, Stereopy reads only three columns from the cusingler.run() output (res[:, 0], res[:, 1], res[:, 2]) corresponding to bins, first labels, and final labels; any additional data cusingler might compute is not consumed.

Is This Expected?

Yes. The current implementation was designed to return only the annotation labels. Confidence/score columns have not been implemented in either mode.

Recommended Workflow

Step 1: As a workaround on the CPU path, you could modify the main method locally to also return the score matrix from _score_test_data. The output variable (line 195 of single_r.py) contains per-cell Spearman-based scores for each reference label — you could attach these as additional columns or compute a delta-based confidence metric (e.g., difference between the top two scores).

Step 2: For the GPU path, check whether the cusingler library supports returning additional columns with scores. If cusingler.run() outputs more than 3 columns, the Stereopy wrapper would need to be updated to consume and expose them.

Step 3 (optional): If you need a quick confidence metric now, you can compare the first_labels and group columns — when they agree, the annotation is generally more reliable, though this is not a quantitative score.

Alternative Approaches

If you need confidence scores urgently:

• Option A: Use the R SingleR package directly (via rpy2 or standalone R), which provides scores and delta.next confidence metrics in its output.
• Option B: Run Stereopy's SingleR on CPU and modify the source locally to return the internal score matrix (the output DataFrame from _score_test_data).

Notes

• The GPU path (method='rapids') only works when cluster_res_key is not set. If you provide a cluster_res_key, the CPU path is used regardless of the method parameter.
• Adding confidence scores would be a valuable enhancement for both CPU and GPU modes. We encourage you to open a feature request if you would like this tracked as a planned improvement.

Please let us know if you have further questions!

Best regards,
Stereopy Maintainer