---

name: plotting-reporting description: "Use for Scanpy sc.pl plotting, figure saving, headless rendering, embedding/spatial/gene/QC/marker plots, Matplotlib object handling, palettes, and plotting troubleshooting after analysis outputs already exist in AnnData." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

Scanpy Plotting and Reporting

Use this sub-skill when a task is about rendering or exporting Scanpy figures from an existing anndata.AnnData object. It covers scanpy.pl APIs, figure settings, Matplotlib return objects, non-interactive execution, and common failures around colors, genes, raw/layers, spatial metadata, and saved paths.

Route by task

• Embedding and scatter panels: Use references/plotting-workflows.md for sc.pl.embedding, sc.pl.umap, sc.pl.tsne, sc.pl.pca, sc.pl.spatial, color keys, groups, mask_obs, gene_symbols, layer, use_raw, palettes, legends, axes, and multi-panel behavior.
• Grouped marker summaries: Use references/plotting-workflows.md for sc.pl.dotplot, sc.pl.matrixplot, sc.pl.stacked_violin, sc.pl.heatmap, sc.pl.tracksplot, sc.pl.dendrogram, and DotPlot/MatrixPlot/StackedViolin customization.
• Rank-gene and QC reports: Use references/plotting-workflows.md for sc.pl.rank_genes_groups*, sc.pl.highly_variable_genes, sc.pl.highest_expr_genes, sc.pl.violin, PCA variance/loadings, and other reports that visualize precomputed annotations.
• Saving, CI, and publication defaults: Use references/figure-settings.md for matplotlib.use("Agg"), show=False, return_fig, ax, explicit figure.savefig, sc.settings.figdir, sc.settings.autoshow, sc.settings.autosave, and sc.set_figure_params.
• Failure diagnosis: Use references/troubleshooting.md for missing .obsm bases, missing .obs/gene color keys, .raw versus .layers, categorical palettes, spatial image metadata, backend/display errors, and save= surprises.

Safe default workflow

1. Verify the plotted state already exists in adata: coordinates in .obsm, annotations in .obs, genes in the selected expression source, marker results in .uns, layers in .layers, spatial metadata in .uns['spatial'], or categorical colors in .uns.
2. In scripts, tests, servers, and CI, set the Matplotlib backend to Agg before importing matplotlib.pyplot, set sc.settings.autoshow = False, and pass show=False to every plotting call.
3. Prefer explicit saves from returned objects: ax = sc.pl.umap(adata, color='cluster', show=False) followed by ax.figure.savefig(path, dpi=200, bbox_inches='tight').
4. For class-backed grouped plots, pass return_fig=True, style the returned DotPlot, MatrixPlot, or StackedViolin object, call make_figure() when needed, then save plot.fig.
5. Close figures after saving in loops with matplotlib.pyplot.close(fig) or plt.close('all') to avoid memory growth and accidental figure reuse.

Bundled helper

• scripts/scanpy_headless_plot_smoke.py creates a tiny synthetic AnnData, uses the Agg backend, renders UMAP/embedding/PCA and optional dotplot outputs with show=False, saves PNGs, and prints JSON. Use it as a minimal headless plotting smoke test without relying on repository files.

Boundaries

• Do not compute upstream analysis artifacts here. Route PCA, neighbors, UMAP, clustering, PAGA, dendrogram creation, and rank-gene computation to graph/embedding or analysis sub-skills.
• Do not cover preprocessing/QC metric creation here. This sub-skill only plots those outputs when already present.
• Do not route optional external plotting such as PHATE, TriMap, SAM, Wishbone, or Squidpy-specific spatial plotting here; use external integration guidance when the user explicitly needs those APIs.
• Do not make public instructions depend on local checkout paths, repository tests, generated docs, or private output directories.