Created by: gwideman, Jan 8, 2012 11:56 pm
Revised by: gwideman, Jan 12, 2012 2:14 am (9 revisions)


Work in progress
This article captures notes and specs for a Sankey diagram shape implemented in Visio. Sankey diagrams show lines ("ribbons") representing flows , where the magnitude of a flow is shown by the width of its ribbon.


[to do]

Shape features

The following features of the shape are of interest:
The width of the ribbon is to be proportional to the magnitude of the flow.
Ribbons can be straight, or have bends. Corners can be smooth curves or sharp angles.
Flows may combine or split. If a single shape can't manage this, then at least shapes for the individual flow segments should be readily combinable.
Lines for different flows should be set to different colors so that the eye can readily distinguish their paths in a complicated diagram.
Some Sankey users like to set a gradient fill on their flows. This can look attractive, but rather defeats the purpose of using color to distinguish one flow from another. So this features is "nice to have" but not essential.
Lines need labels. Ideally the text should conform to the path of the line. If the text contains a number showing magnitude, it should be linked to the actual magnitude which specifies line width, to avoid these two magnitudes getting out of sync.
The ribbons can be drawn without borders or with.
Ribbon ends may be drawn with a border, or without a border to suggest continuation beyond the diagram
It is often helpful to provide an indication of direction. This could be shown at the ribbon end, or using a pattern or indication along the length of the ribbon.


The shape structure consists of a Visio group shape, and several subsidiary shapes.
Main ribbon
Main (group) shape
A line (2D shape) the displays as the main ribbon of the Sankey shape. Color and general appearance of the ribbon are implemented by the main shape's line-style and line color. (Fill is not involved as this is a 2D shape.)

Ribbon border
Ribbon border can be set by creating and setting an appropriate custom line-style.

Ribbon ends
Ribbon ends can be set to a variety of different closed or open appearances, possibly with some indication of direction.
A series of individual one-character shapes.
Visio has no built-in feature to fit text to a curve. Instead, in this shape, text fitting the ribbon is implemented as a series of small text-only shapes (say 10 or 20), each containing one character. These are appropriately positioned and angled along the ribbon, vertically centered on it, or positioned above it or below it. Position along the line is implemented with a Control.

Caption background
Because the text is implemented as a series of individual single characters, it's not possible to use the text shapes' background fill, as that would appear disjointed. Instead, a separate multi-segment line shape is included which, if enabled, will be sized and position behind the text characters to form a single contiguous background fill for them.

The behavior of the shape itself is implemented entirely using the ShapeSheet. No VBA is involved.
However, there is some associated VBA that can be used to construct an initial version of the shape in the first place, as this is a more reliable way to set all of the formulas involved, especially in the repetitive character shapes. This code is useful for a user who might wish to create a variation of the shape.


Set using
Implications or comments


Use any 1D or 2D shape with a suitable path (in section Geometry1)
Moves on the main shape:
Drag endpoints and/or control points of main line shape. Select curved or straight settings.
Need to allow general editing of main line shape's characteristics, except for those set from properties or formulas.

See Magnitude
Line weight, set by formula from a quantitative Property field.
Guard LineWeight against direct editing.

Main shape > line color

Main > line pattern

Main > line ends

Main > line transparency


Use ### to insert the number from the Magnitude field
Lock all group and children against normal text edit.

Text position
Control point
Positions text along the path
Slide control point to position text.

Caption Enable
(also right-click menu)
Disable speeds rendering
When manipulating the overall shape, Visio redraws extremely slowly, apparently due to recalculating the character positions. So disable the caption while positioning the shape.

Caption Vert Align
Positions text above the path, centered on the path, or below the path.

Char spread
Spreads characters out
1 = normal, >1 to spread, <1 to compress

Value that will be inserted in text, and which will also control line width.

Scaling factor by which Magnitude should transform to LineWeight in pts
MagPerLineWeightpt could be set to a fixed value in the ShapeSheet for a shape that will be used many times with the same value.

Live Dynamics
Disable for minor speed up
This can disable the shape's live dynamics, most notably the live update of character position following movement of the control point.

Font name
Main > Font name

Guard all children against normal font setting [2]

Font size
Main > Font size

Font color
Main > Font color

Font spacing
[to do]

Caption background

Caption background enable
Shows a fill behind the caption text
Only available when caption text is centered on a broad line, and mainly useful when the line pattern is visually distracting.

Line weight (vertical size)
Calculated from font size

"Fill" (line) color
Main > font background color

Linked to Main > line transparency



Implementation notes:
  1. "Property" means a row in the Prop section, which appears as an item in the "Shape Data" panel.
  2. Prohibit group-shape formatting from flowing to children.
  3. Prohibit selection of children.

Line patterns


  • Color ("Fill", but actually line color)
  • Gradient "fill"
  • Directional: Shows flow all along the ribbon
  • Borders: A ribbon may benefit from having sharply drawn borders

Line ends

  • Open or closed?
    • When a line has borders, we may want the ends to be borderless to convey flow to or from beyond the diagram
  • Directional, arbitrarily torn, or plain?