Inconsistency of `basis` argument in plotting functions

Please make sure these conditions are met

• I have checked that this issue has not already been reported.
• I have confirmed this bug exists on the latest version of scanpy.
• (optional) I have confirmed this bug exists on the main branch of scanpy.

What happened?

The definition and usage of the basis argument is inconsistent between plotting functions. In sc.pl.embedding() it can be the name of any item in obsm and is used directly but in sc.pl.scatter() it is supposed to be one of a given list (but anything works) and X_ is prepended when the item is accessed. This means there is no way to plot adata.osbm["umap"] in sc.pl.scatter() because it tries to access adata.obsm["X_umap"].

I guess this is a hangover from when plotting was more closely linked to specific tools but I think it makes sense for sc.pl.scatter() to work more generally.

There is a related but more specific issue in #3642.

Minimal code sample

import scanpy as sc
adata = sc.datasets.pbmc3k_processed()
# Add non-standard obsm
adata.obsm["umap"] = adata.obsm["X_tsne"].copy()
adata.obsm["custom"] = adata.obsm["X_pca"].copy()

sc.pl.embedding(adata, basis="X_umap") # Correctly plots X_umap
sc.pl.embedding(adata, basis="umap") # Correctly plots umap
sc.pl.embedding(adata, basis="custom") # Correclty plots custom

sc.pl.scatter(adata, basis="X_umap") # Fails trying to plot X_X_umap
# KeyError: 'compute coordinates using visualization tool X_umap first'
sc.pl.scatter(adata, basis="umap") # Works but plots X_umap
sc.pl.scatter(adata, basis="custom") # Fails to plot X_custom
# KeyError: 'compute coordinates using visualization tool custom first'
adata.obsm["X_custom"] = adata.obsm["custom"].copy()
sc.pl.scatter(adata, basis="custom") # Works but plots X_custom

Error output

Versions

anndata	0.12.2
scanpy	1.11.4
----	----
stack_data	0.6.3
pyparsing	3.2.3
numba	0.61.2
decorator	5.2.1
jedi	0.19.2
scikit-learn	1.7.1
traitlets	5.14.3
typing_extensions	4.15.0
llvmlite	0.44.0
colorama	0.4.6
crc32c	2.7.1
Pygments	2.19.2
six	1.17.0
natsort	8.4.0
matplotlib	3.10.5
ipython	9.4.0
cycler	0.12.1
pillow	11.3.0
PyYAML	6.0.2
msgpack	1.1.1
legacy-api-wrap	1.4.1
h5py	3.14.0
pytz	2025.2
parso	0.8.5
tqdm	4.67.1
prompt_toolkit	3.0.52
numpy	2.2.6
executing	2.2.0
session-info2	0.2.1
pure_eval	0.2.3
setuptools	80.9.0
joblib	1.5.2
threadpoolctl	3.6.0
donfig	0.8.1.post1
numcodecs	0.16.1
zarr	3.1.2
wcwidth	0.2.13
packaging	25.0
python-dateutil	2.9.0.post0
asttokens	3.0.0
scipy	1.16.1
kiwisolver	1.4.9
pandas	2.3.2
----	----
Python	3.13.5 | packaged by conda-forge | (main, Jun 16 2025, 08:27:50) [GCC 13.3.0]
OS	Linux-6.14.0-29-generic-x86_64-with-glibc2.39
CPU	16 logical CPU cores, x86_64
GPU	No GPU found
Updated	2025-09-18 05:45

Start by comparing the basis handling in sc.pl.embedding() and sc.pl.scatter(), using the minimal code sample with custom obsm entries to reproduce the inconsistent lookups. Trace how each function resolves obsm keys, then add regression coverage showing that standard and non-standard basis names behave consistently. Done means sc.pl.scatter() can plot entries such as umap and custom without requiring an X_-prefixed duplicate.