Repository navigation
Adding plotting specific documentation #463
Description
Activity
Documentation Audit (April 2026)
Underdocumented Features & Behaviors
Color handling
- Color resolution pipeline: literal color > column name >
adata.unsstored colors groupsnow hides NAs by default (v0.3.0 behavior change) unlessna_colorexplicitly setmake_palette()/make_palette_from_data()with spaco spatial interlacement, colorblind simulation (new)- String column names in [0,1] range no longer misinterpreted as colors (v0.2.5 fix)
Image rendering
- RGB auto-detection when channels named {r,g,b} — no cmap needed, but channel order matters
- Multi-channel additive blending: per-channel cmaps blended additively; cmaps going to white occlude lower layers
transfunc: single callable gets(c,y,x), list of callables each get(y,x)— different signatures- Multiscale auto-selection based on figure DPI/size;
scaleparam controls rasterization - Grayscale conversion (Rec. 601 weights) applied after transfunc
Datashader integration
- Auto-dispatches when >10k elements; override with
method= - Different default reductions per element type: "max" for shapes, "sum" for points
- Outline rendering supported for shapes but behavior differs from matplotlib
Rendering pipeline
- Declarative plotting tree:
render_*()stores commands,show()executes in insertion order → z-order = call order - Broadcasting:
element=Nonebroadcasts params to all elements; invalid params silently ignored show()auto-detects context: callsplt.show()in scripts, suppresses in Jupyter; user-provided axes suppress it
Labels
contour_px=Nonefills segments vs integer draws contour of that widthoutline_color=Noneuses per-label data-driven colors whencoloris a column
Shapes
- Shape conversion:
shape="hex"/"circle"/"square"/"visium_hex"(visium_hex sizes for adjacency) - Double outline via tuple params:
outline_width=(1.5, 0.5),outline_color=("#000", "#fff") - Polygons with holes auto-converted to MultiPolygon
Figure/axes
share_extentfor consistent bounds across CS panels- Deferred colorbar rendering (after canvas drawn); identical mappables de-duplicated
pad_extentfor padding around computed extent
Breaking changes across versions (no migration guide exists)
- v0.3.0:
groupshides NAs, uniform color handling, keyword-only params (v0.2.14)
Colorbar and legend options
- Bunch of different options exist but are not explicitly explained
Proposed Notebook TODOs
Priority Notebook Scope P1 Getting Started Load SpatialData → render all 4 element types → show. Minimal entry point. P1 Color & Palette Color pipeline, categorical/continuous, groups+NA, make_palette, spaco, colorblind simP1 Multi-element Overlay Stacking render calls, z-ordering, transparency, combining images+labels+shapes+points P2 Image Rendering Single/multi-channel, RGB detection, additive blending, transfunc, grayscale, multiscale P2 Datashader Auto-dispatch, reductions, matplotlib vs datashader differences, performance P2 Coordinate Systems Multi-CS plots, share_extent, pad_extent, transformations P2 Figure Customization figsize/dpi, ncols, own axes, show param, frameon, save, return_ax P3 Labels Rendering contour_px, outline styling, data-driven outline colors P3 Shapes Rendering Shape conversion, double outlines, polygon holes, scaling P3 Colorbar & Legend colorbar_params, legend_loc, fontoutline, na_in_legend P3 Gene Symbols & Tables gene_symbols param, table_name/table_layer, multi-table P4 Performance Tips Datashader thresholds, rasterization, multiscale Reacted by LucaMarconato- Color resolution pipeline: literal color > column name >
- added a commit that references this issue
on Apr 6, 2026 - added a commit that references this issue
on May 12, 2026 - added a commit that references this issue
on Aug 13, 2026
Comment originally from @MeyerBender, thanks for the feedback!
Currently we have plotting notebooks but hidden under the "Technology-specific" section in the docs. And we have another notebook in a separate repo (=not really discoverable).
Improving the docs with a visualization-specific notebook that is easily discoverable would be valuable.