Adding plotting specific documentation #463

Activity

1. LucaMarconato

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   spatialproteomics

   on May 13, 2025
2. timtreis commented on Apr 6, 2026

   

   timtreis

   on Apr 6, 2026

   Last edited by timtreis

   Member

   More actions

   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

   👍React with 👍1Reacted by LucaMarconato
3. timtreis

   added a commit that references this issue on Apr 6, 2026

   Fix docstrings and remove dead code across public API

   ...

   480eb5a
4. timtreis

   added a commit that references this issue on May 12, 2026

   Add Colour and palettes card and refresh Visium thumbnail

   ...

   3d2f30b
5. timtreis

   added a commit that references this issue on Aug 13, 2026

   docs: add a Scalebars tutorial (#12)

   ...

   afa4056