Inconsistency of `basis` argument in plotting functions

[lazappi]

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

[flying-sheep]

Yes, there’s too much guessing in scanpy. I’m working on a more explicit version in holoviz-topics/hv-anndata#87

That repo will eventually make its way into scanpy’s experimental API and then in 2.0 become the default (together with not adding the X_ in the first place)

I’m up for a PR that changes this so it’ll work more consistently!