Skip to content

feat: box-and-arrow diagrams, profile bands and legend handles - #1

Merged
vitusbenson merged 2 commits into
mainfrom
flux-diagram
Nov 17, 2026
Merged

vitusbenson merged 2 commits into
mainfrom
flux-diagram

Conversation

@vitusbenson

Copy link
Copy Markdown
Collaborator

Adds box-and-arrow diagrams and two small helpers.

  • diagram_box, diagram_arrow (new module nicefigs.diagrams): a labelled rounded box, and a filled arrow whose shaft and head are sized in points, so drawings keep their shape on any aspect. Both are placed in data coordinates; arrows take a connectionstyle for curves and an optional midpoint label. These are the pieces for flowcharts and schematics.
  • flux_diagram: a box model's budget built from those pieces. It draws a grid of boxes (rows bottom first) coloured on a diverging norm. Fluxes are vertical, horizontal, lateral (drawn on both sides of a box, inward when positive) and ground. Each arrow is sign-aware and its width is proportional to √|value|, on one scale per kind. Two further options: parts splits the vertical flux, and notes adds a note to each box. Pass a shared norm and reference to compare panels. It returns (ax, FluxDiagram) with the mappable, the boxes and every arrow (tail, head, width).
  • flux_legend: explains a diagram's encoding.
  • profile(bands={name: (low, high)}): shades a range, such as an interquartile range, behind a profile in its colour.
  • legend_handle(label, kind, **style): builds a line, marker or band legend entry in the role_style vocabulary.
  • data.box_budget: a closed example budget. Also adds gallery example 33, guide sections (Box-and-arrow diagrams, profile bands, styling), a changelog entry under [Unreleased], and 24 new tests.

Motivation: torchtransport's CATRINE layer-budget figure and several schematics and flowcharts drew raw matplotlib patches. They will compose these primitives instead.

Checks: pytest (505 passed), ruff check/ruff format --check (v0.15.0), scripts/docs_examples.py (0 problems), and mkdocs build --strict.

No version bump and no tag. The release is cut separately.

- diagram_box, diagram_arrow: labelled boxes and point-width arrows for flowcharts
- flux_diagram, flux_legend: a box model's budget, arrows sign-aware and sqrt-scaled
- profile(bands=...): a shaded range behind a profile in its colour
- legend_handle: line, marker or band legend entries in the role_style vocabulary
- data.box_budget, gallery example 33, guide sections, changelog
@vitusbenson
vitusbenson merged commit b52a4b8 into main Nov 17, 2026
8 checks passed
@vitusbenson
vitusbenson deleted the flux-diagram branch November 17, 2026 21:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant