Module

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 wire

How 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.

#defaultMetrics Source

#widthOf Source

widthOf :: forall wire. Widths wire -> Edge wire -> Number

An edge's width in units under a choice of widths.

#sankey Source

sankey :: forall wire. Metrics -> Widths wire -> Engine wire

The Sankey engine at a scale and a choice of widths.