[sylvesterkaczmarek]

Closes #3803.

Use the existing exact-key-first resolver in legacy sc.pl.scatter, then fall back to X_ when the requested embedding key is absent. This supports custom and explicitly prefixed keys and prevents silently selecting the prefixed coordinates when both keys exist.

Keep lookup separate from display names. diffmap and X_diffmap retain the trivial-component offset and component labels, while the original argument remains available for save naming. No changes to embeddings, expression data, colorbar placement or the shared resolver. The signature/docstring and a release-note fragment describe the supported key lookup.

Validation

• Nineteen rendered-coordinate regression cases pass. Sixteen fail against the original implementation; three unchanged controls pass.
• Final host run with default pytest plugins: 65 plotting/raw/accessor checks passed, no skips or failures. Candidate hashes remained unchanged throughout.
• Independent automated review reran the 19 cases and passed 109 additional bounded checks, including coordinate equivalence with embedding, labels, key conflicts, diffusion components and original/candidate error boundaries. No actionable findings.
• Ruff lint, formatting and git diff --check pass.

Tests used synthetic arrays and bundled fixtures on macOS with Agg. The complete repository suite, documentation-site build, whole-project type checks and upstream CI were not run. Sparse/DataFrame coordinate containers are not added to the supported scope.

LLM usage

• LLM or coding agent used: GPT-6 via ChatGPT and Codex CLI v0.166.0 assisted with code, tests, documentation, and review. The Codex model version used for the original implementation was not independently recorded.

• If one was used, I, a human, have reviewed, understood and tested every changed line.

• Closes Inconsistency of basis argument in plotting functions #3803.

• Tests included.

• Release notes not necessary because:

Release note included as 4494.fix.md.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.37%. Comparing base (117682e) to head (7d5a694).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4494      +/-   ##
==========================================
+ Coverage   85.13%   85.37%   +0.23%     
==========================================
  Files         138      138              
  Lines       12247    12244       -3     
==========================================
+ Hits        10427    10453      +26     
+ Misses       1820     1791      -29     

Flag	Coverage Δ
hatch-test.low-vers	78.89% <100.00%> (+0.23%)	⬆️
hatch-test.pre	85.16% <100.00%> (+0.23%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/scanpy/plotting/legacy/_anndata.py	87.86% <100.00%> (+2.13%)	⬆️

... and 2 files with indirect coverage changes

[read-the-docs-business]

Documentation build overview

📚 scanpy | 🛠️ Build #4691397 | 📁 Comparing 7d5a694 against latest (117682e)

  🔍 Preview build  

4 files changed

± release-notes/index.html
± api/generated/scanpy.pl.scatter.html
± api/generated/scanpy.pp.calculate_qc_metrics.html
± api/generated/scanpy.settings.html

[sylvesterkaczmarek]

I updated the PR metadata to match Scanpy's checks: a semantic fix title, the numbered release-note fragment (4494.fix.md), and the LLM usage disclosure. The human-review declaration remains unchecked for manual confirmation. The stable, few-extras and lowest-version tests, build, docs and pre-commit had passed on the previous head. Could a maintainer assign the appropriate milestone or apply the 'no milestone' label when convenient? That is currently blocking the title/milestone check.