Scanpy 1.12.4 review and representation boundaries

Reviewed 2026-10-01. Local tests use Python 3.13, Scanpy 1.12.4 and AnnData 0.13.4. Official stable docs and the installed release source were inspected for every Scanpy API family used by the toolkit, assets and references. There are no remote analysis/authentication/pagination endpoints in these scripts. Package installation and fetching example datasets can use the network; the tests use local synthetic inputs and no patient data or atlas downloads.

Invariants to preserve

.raw snapshots X and var, not layers, and does not mean raw counts. Cell slices subset .raw cells; gene slices leave its original gene axis. The scripts use adata.raw = adata.copy() before scaling to prevent shared-array mutation. AnnData 0.13 includes the unnamed X key (None) when iterating layers; filter for named strings where listing extra layers. A view is not an independent copy. Backed r+ persists supported X changes only, not arbitrary annotation edits; write a new file after deliberate .to_memory() conversion and close the backing file.

The full pipeline computes on an HVG copy but transfers aligned PCA loadings, embeddings, graph and parameters to the full-gene object. --subset-hvg explicitly shrinks all layers: keep the full-gene checkpoint for pseudobulk. Never reconstruct missing raw counts from .raw or normalized values. CSV/Matrix Market readers need known orientation and cell/gene identifiers; bare MTX carries neither identifier list. .h5 is assumed 10x HDF5, not arbitrary HDF5. Loom needs loompy.

Statistical and plotting interpretation

rank_genes_groups defaults to reference='rest'; named reference groups and groups control the comparison, not the donor dependence. BH adjustment is over tested genes per contrast. t/Wilcoxon p-values do not account for selection of clusters from the same data or donor-level dependence. Logistic regression is a marker ranking without equivalent p-values or log fold changes. Scanpy log-fold changes are approximations computed from mean log expression, not a pseudobulk negative-binomial model. Do not rank scaled residuals or corrected expression as if it were log-normalized expression.

The pseudobulk CLI requires the count layer, rejects missing grouping values, keeps stable opaque profile IDs to prevent underscore collisions, and checks that transferred condition/donor covariates are constant within each profile. It exports genes x profiles; transpose for PyDESeq2's samples x genes API. Preserve identifiers as strings when reading CSV and align rows by IDs. Fit each cell type separately with adequate independent biological replicates and a full-rank design; a sample x cell-type table does not multiply the donor count. Missing cell types are not zero-count biological replicates. Cell-count and library-size filtering decisions need study-specific justification.

Scanpy 1.12 deprecates plotting save= but still supports it; toolkit suffixes retain distinct filenames. Global autosave alone can overwrite repeated plots. For exact exported figures use return_fig=True for embedding plots, then Figure.savefig; composite DotPlot/MatrixPlot/StackedViolin instead return plot objects with their own .savefig() when return_fig=True. show=False alone has function-specific return types, not a universal Figure contract. Dot size is detection fraction; dot color is mean expression; standard_scale rescales for display and changes the interpretation. Neighbor edges are not a PAGA partition graph, and cluster heatmaps are not automatically ordered by pseudotime.

Optional branches and current upstream references

• Release notes: 1.12.4 released 2026-08-27; Python >=3.12; deprecated Louvain/plot save remain.
• HVG, PCA, neighbors, Leiden.
• Marker ranking, aggregation, gene scoring.
• AnnData raw, backed I/O, released source.
• Harmony changes X_pca_harmony, not X. Scanpy 1.12.4 still transposes Z_corr, but harmonypy 2.0.2 returns cells x PCs. The wrapper failed a native shape check; toolkit integration calls harmonypy.run_harmony directly, validates shape/finiteness, and stores Z_corr without transposition. Rebuild neighbors explicitly on it. BBKNN replaces the neighbor graph; running ordinary neighbors afterward discards it. The CLI explicitly selects exact cKDTree (approx=False, use_faiss=False): native Annoy 1.17.3 returned too few neighbors on the tested macOS ARM/NumPy 2.5 fixture. This is an observed backend limitation, not a universal BBKNN failure. ComBat changes X, may densify, and needs >=2 cells per batch; retain uncorrected log expression/raw counts for markers/DE. Integration cannot resolve perfectly confounded batch and condition. Optional Harmony/BBKNN runtime validation is separately reported; ordinary native tests do not establish integration quality.
• DPT requires neighbors, diffusion components and a justified biological root. An arbitrary cluster zero is only an illustrative placeholder; pseudotime is not elapsed time.
• ingest requires the same ordered gene axis and compatible preprocessing in query and reference, with reference neighbors/PCA/UMAP as requested. No atlas mapping was executed in this refresh.
• R conversion: official signatures were checked, but R system installation/Seurat/zellkonverter/SeuratDisk conversions were not run. zellkonverter manages its own supported Python environment; do not assume the local Scanpy environment is used. An unspecified X_name selects the first assay, not necessarily counts, so the example now requires a counts assay explicitly.

Dask, alternative file formats, optional integrations and trajectories each need representative-data checks before production use. Small synthetic native tests validate software contracts; they establish no biological annotation, batch correction quality, calibrated DE error rate or cross-tool statistical equivalence.