Skip to content

dew.figures

SVG figures for notebooks and docs, in colors that follow the page’s light or dark theme.

A Figure is plain SVG. Its colors are CSS variables that the figure defines twice, for a light and a dark page, and it picks one from where it is shown: the docs site’s data-theme, Colab’s output frames, JupyterLab and VS Code, and otherwise the reader’s system setting. A notebook shows a figure through _repr_html_; the docs and the tutorials’ concept figures are the same markup in files (save), embedded as images. Animations are CSS keyframes inside the SVG, so they play with no script, in an <img> too. Each one loops: it builds the picture, holds it, and eases back to the start. With reduced motion asked for, only the held picture shows.

curve, bars, heatmap, images, points and tokens draw the charts the tutorials make from their own runs.

NameSummary
THEMESEach theme’s color for each role a figure draws with.
FigureAn SVG drawing, width by height, whose animations loop every seconds.
ShapeOne SVG element: its tag, attributes, style, text, children and, once animated, its keyframes.
barsBars that move from frame to frame: frames[t][k] is bar k’s height in frame t.
curveLines over steps that draw themselves, one per entry of series, the first in the accent color.
heatmapA grid whose cells fade from frame to frame: frames[t][r][c], from 0 to 1, is cell (r, c)‘s strength in frame t.
imagesA grid of photographs that changes from frame to frame: frames[t] is frame t’s images, uint8 [N, H, W, C], drawn size wide in rows of columns.
pointsDots, one series per entry of series, the first in the accent color and the others neutral, as curve colors them.
tokensRows of token boxes, each as wide as its text and at least cell, fills[i][j] filling token j of row i (“none” leaves it an outline), with notes[i] beside row i.

attribute source

THEMES: dict[str, dict[str, str]]

Each theme’s color for each role a figure draws with.

class source

class Figure(
width: float,
height: float,
*,
seconds: float = 0.0,
label: str = '',
palette: Mapping[str, str] = VARIABLES,
)

An SVG drawing, width by height, whose animations loop every seconds.

Each drawing method adds a shape and returns it, for animate. Colors are roles (Role), which palette turns into CSS: by default the theme variables, or one theme’s colors from THEMES for a figure drawn once per theme. label is what a screen reader says.

def add(
tag: str,
attributes: Mapping[str, float | str],
style: Mapping[str, str] | None = None,
text: str = '',
) -> Shape

Add an element with these attributes (numbers rounded to hundredths) and this text, which the markup escapes, to the open group.

def rect(
x: float,
y: float,
w: float,
h: float,
*,
fill: Role = 'surface',
stroke: Role = 'rule',
rx: float = 6,
width: float = 1,
) -> Shape

A rectangle with corners rounded by rx, outlined width wide.

def circle(
cx: float,
cy: float,
r: float,
*,
fill: Role = 'accent',
stroke: Role = 'none',
) -> Shape

A circle of radius r centred on (cx, cy).

def line(
x1: float,
y1: float,
x2: float,
y2: float,
*,
color: Role = 'muted',
width: float = 1.25,
dash: str | None = None,
) -> Shape

A straight line, dashed by the SVG dash pattern dash when given.

def polyline(
points: Sequence[tuple[float, float]],
*,
color: Role = 'accent',
width: float = 1.75,
dash: str | None = None,
) -> Shape

A line through points, as a path, which draw can trace.

def arrow(
x1: float,
y1: float,
x2: float,
y2: float,
*,
color: Role = 'muted',
width: float = 1.25,
) -> Shape

A line from (x1, y1) with a filled head at (x2, y2).

def text(
x: float,
y: float,
words: str,
*,
size: float = 13,
color: Role = 'text',
mono: bool = False,
anchor: str = 'start',
weight: int = 400,
) -> Shape

words on one line, anchored at (x, y) by anchor: “start”, “middle” or “end”.

def image(
x: float,
y: float,
size: float,
pixels: np.ndarray,
*,
photo: bool = False,
) -> Shape

A uint8 image, [H, W] or [H, W, C], drawn size wide: a PNG with its pixels kept sharp, or with photo a WebP at quality 90 and smoothed, a fraction of a photograph’s PNG.

def group(x: float = 0, y: float = 0) -> Iterator[Shape]

Draw the block’s shapes into one group, moved by (x, y). Animate the shapes inside, or the group when it is not moved: a CSS transform replaces the group’s own.

def animate(
shape: Shape,
keys: Mapping[float, Mapping[str, str | float]],
*,
origin: str = '',
) -> Shape

Give shape these CSS properties at these seconds of the loop, eased in between.

Before the first key the shape holds the first key’s state; after the last it holds the last’s, which is also its state when animation is off. origin is the transform origin within the shape’s own box, as “50% 100%” to scale a bar from its foot.

def appear(shape: Shape, at: float, fade: float = 0.4) -> Shape

Hide shape until at seconds into the loop, then fade it in.

def draw(shape: Shape, start: float, end: float) -> Shape

Trace a polyline from its first point to its last between start and end seconds.

def show_in_turn(
shapes: Sequence[Shape],
times: Sequence[float],
fade: float = 0.15,
) -> None

Show each of shapes from its time in times until the next one’s, the last until the loop ends. One fades out before the next fades in, so shapes drawn in one place, such as a frame’s caption, never show together.

def svg() -> str

The figure as one SVG element, its stylesheet and keyframes inside.

def save(path: str | Path) -> None

Write the figure to path, as one line of SVG.

dataclass source

class Shape(
tag: str,
attributes: dict[str, str],
style: dict[str, str] = dict(),
text: str = '',
children: list[Shape] = list(),
keyframes: str = '',
)

One SVG element: its tag, attributes, style, text, children and, once animated, its keyframes.

function source

def bars(
frames: Sequence[Sequence[float]],
*,
labels: Sequence[str],
captions: Sequence[str] = (),
colors: Sequence[Role] = (),
y_max: float = 1.0,
y_label: str = '',
width: float = WIDE,
height: float = 260,
seconds: float = 8.0,
) -> Figure

Bars that move from frame to frame: frames[t][k] is bar k’s height in frame t.

captions[t] names frame t, and colors[k] colors bar k (accent by default). Each bar shows its value above it.

function source

def curve(
series: Mapping[str, Sequence[float]],
*,
x_label: str,
y_label: str,
x: Sequence[float] | Mapping[str, Sequence[float]] | None = None,
y_range: tuple[float, float] | None = None,
smooth: int = 1,
width: float = WIDE,
height: float = 290,
seconds: float = 8.0,
) -> Figure

Lines over steps that draw themselves, one per entry of series, the first in the accent color.

x holds each point’s step, as a tracker logged it: one sequence for every series, or a mapping from each series’ name to its own steps, as a run’s training and validation are logged at different steps. Without it the points are steps 0, 1, 2 and on. With smooth above 1 each line is drawn faint, and its running mean over smooth points over it. A nonfinite value (a journal keeps NaN and infinities) is left out of its line and of the axes, and the figure says how many were.

function source

def heatmap(
frames: Sequence[Sequence[Sequence[float]]],
*,
rows: Sequence[str],
columns: Sequence[str],
captions: Sequence[str] = (),
x_label: str = '',
y_label: str = '',
marks: Sequence[tuple[int, int]] = (),
cell: float = 28,
seconds: float = 8.0,
) -> Figure

A grid whose cells fade from frame to frame: frames[t][r][c], from 0 to 1, is cell (r, c)‘s strength in frame t. marks outlines cells, such as the ones the values should move to.

function source

def images(
frames: Sequence[np.ndarray],
*,
captions: Sequence[str] = (),
columns: int = 8,
size: float = 64,
rows: Sequence[str] = (),
seconds: float = 8.0,
) -> Figure

A grid of photographs that changes from frame to frame: frames[t] is frame t’s images, uint8 [N, H, W, C], drawn size wide in rows of columns. captions[t] names frame t, and rows[r] names row r at its left. One frame is a still grid.

function source

def points(
series: Mapping[str, Sequence[tuple[float, float]]],
*,
x_label: str,
y_label: str,
joined: bool = True,
moved: Mapping[str, Sequence[tuple[float, float]]] | None = None,
captions: Sequence[str] = (),
log_x: bool = False,
log_y: bool = False,
width: float = WIDE,
height: float = 300,
seconds: float = 8.0,
) -> Figure

Dots, one series per entry of series, the first in the accent color and the others neutral, as curve colors them. Joined, each series is a line through its dots in order, named beside its last dot, dashed past the third, and the series appear one after another. Not joined, the dots are a scatter with the names in a legend; with moved, each dot then slides to its place there, and captions name the two pictures. With log_x or log_y that axis is logarithmic.

function source

def tokens(
rows: Sequence[Sequence[str]],
*,
fills: Sequence[Sequence[Role]],
notes: Sequence[str] = (),
cell: float = 27,
seconds: float = 0.0,
) -> Figure

Rows of token boxes, each as wide as its text and at least cell, fills[i][j] filling token j of row i (“none” leaves it an outline), with notes[i] beside row i. With seconds, the rows appear one after another.