Adding plotting specific documentation

[LucaMarconato]

Comment originally from @MeyerBender, thanks for the feedback!

documentation: in general, I think it would be good to have one or two notebooks that exclusively focus on visualization. Right now, it is very hard to find this in the spatialdata docs. Maybe something similar to this, which shows off the most important plotting functions in spatialproteomics.

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.

[timtreis]

Documentation Audit (April 2026)

Underdocumented Features & Behaviors

Color handling

• Color resolution pipeline: literal color > column name > adata.uns stored colors
• groups now hides NAs by default (v0.3.0 behavior change) unless na_color explicitly set
• make_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; scale param 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=None broadcasts params to all elements; invalid params silently ignored
• show() auto-detects context: calls plt.show() in scripts, suppresses in Jupyter; user-provided axes suppress it

Labels

• contour_px=None fills segments vs integer draws contour of that width
• outline_color=None uses per-label data-driven colors when color is 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_extent for consistent bounds across CS panels
• Deferred colorbar rendering (after canvas drawn); identical mappables de-duplicated
• pad_extent for padding around computed extent

Breaking changes across versions (no migration guide exists)

• v0.3.0: groups hides 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 sim
P1	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