Hylograph.Flow.Render.Sankey
- Package
- purescript-hylograph-flow-render
- Repository
- afcondon/purescript-hylograph-flow-render
The Sankey engine: the layout this package has had since 0.1, as one
engine among those the renderer draws (Hylograph.Flow.Render.Engine).
Pure, so it runs in node.
Metrics and Widths are this engine's own configuration: sankey
metrics widths is the engine, and a Picture (words, open groups) is
what it is told as any engine is. It promises FlowsForward,
LayersAligned and WidthsConserved at its own scale; every route it
makes is a Ribbon, inked as a Band by quantity and as a Hairline
in a plain picture. It places no ports: it stacks the edges on a node's
side by where they go, so the edges of one port need not stand
together, and a port would have no one place.
One layout serves both pictures. Every edge has a width, in units; a
node is as tall as the wider of what enters it and what leaves it, and
its edges stack along its sides. A Sankey takes the widths from the
wires' payloads and draws each edge as wide as it is. A plain DAG gives
every edge one unit and draws each as a hairline down the middle of its
place. The positions come from the same code either way: the Sankey
layout in hylograph-layout, with its lanes for edges that span more
than one layer. The flow runs left to right.
That layout does the placing (DataViz.Layout.Sankey.Whole): the scale
is fixed (unit pixels to one unit of width, the layers a fixed
distance apart) and the picture is as large as that makes it; a node no
edge touches stands on a shelf under the picture; and an edge that
closes a cycle, an edge from a node to itself among them, leaves its
source below the edges that go forward, runs back under the picture in a
channel of its own, and enters its target likewise. The engine is the
translation and nothing more: from a projection to rows and names, and
from the layout's boxes and routes to placed nodes and centre lines, set
in from the left by a margin with room for an edge to turn.
Words, and open groups
Two things the Sankey layout cannot be asked for, and what is done here about each.
A node tall enough for its words. Told what is written in a node
(words), the layout wraps it to the node's breadth by an estimate of
each line's width (Hylograph.Flow.Render.Text, which says how the
estimate is made and how wrong it can be) and makes the node at least
tall enough for the lines; its edges stand in the middle of its sides.
The breadth is metrics.nodeBreadth, one for the picture, so a caller
with long labels may choose narrower and taller nodes.
An open group, outlined. Told the grouping and which groups are
closed (what collapse was told), the layout gives every open group
that holds a drawn node an outline: a box round its members, with a
strip for its name above them, the outline of a group inside it nested
in it. Nothing that is not a member is inside an outline, and the
outlines of two groups overlap only where one holds the other.
How, in three steps. (1) The Sankey layout runs once, to learn where it
would put everything. From that an order is made: at each level of the
grouping, the groups and the loose nodes by the mean height of what is
in them. (2) It runs again held to that order within every column
(nodeSort), so in each column a group's members stand together, the
members of a group inside it together among them, and the groups in the
same order in every column. A long edge's waypoints go with the
innermost group that holds both its ends. (3) Internal.Bands then
moves boxes down, never up and never past one another, until every
outline has its padding and its strip and no outline has anything else
in any column it spans; the same pass makes the room a taller node
needs. A member of an open group that no edge touches would be on the
shelf, far from its group: it stands in its group's first column
instead.
What hylograph-layout 0.6.0 lacks, exactly, which is why step 3 is
here and not there: a node's height is its value at the scale and
nothing else can be asked (no least height by node); the gap between
two nodes of a column is one number, nodePadding (no gap by pair, so
no room for a frame); and a node is in one column (no node that spans
columns, and no notion of a set of nodes to be kept clear of others
across columns). nodeSort is the one thing it offers, and it is used.
The cost of doing step 3 afterwards is that the Sankey relaxation does
not know of the moves, so edges into a group that was moved down slant
more than they would if the relaxation had made the room itself.
#Widths Source
data Widths wireHow wide an edge is. Plain: every edge one unit, drawn as a hairline.
Sankey: the caller reads the width from the edge, which carries what
its wires carry (wires: one for a wire, more where the edge crosses
undrawn elements, and which of them is the quantity is the domain's to
say). A width that is not a positive number is drawn as nothing.
Constructors
#Metrics Source
type Metrics = { hairline :: Number, layerGap :: Number, nodeBreadth :: Number, nodeGap :: Number, restHeight :: Number, unit :: Number }unit: pixels to one unit of width. hairline: the stroke of a plain
edge. nodeBreadth: a node's extent along the flow. layerGap: between
one layer and the next. nodeGap: between two nodes of a layer.
restHeight: how tall a node is that no edge gives a height.