An official website of the United States government
Sankey Diagram
Best Practices
Visit the new and updated Gallery!
Overview
A Sankey diagram shows the flow, movement, or change from one or more states or events to related states or events. In COVE the states are called nodes, and the paths between the nodes are called links. The two nodes connected by a link are its source node (left side) and target node (right side). In the Sankey diagram below, the source node on the far left has links to two target nodes: “Completed Protocol” and “Aborted Protocol.” The key story presented here is that, of 85,865 patients, the vast majority completed their treatment. The diagram completes with links from “Completed Protocol” to its three target nodes to show some after-treatment data.
The size of each node and the width of each link are proportional to the quantity represented. The total volume entering a node equals the total volume exiting the node.
Sankey diagrams can in effect show at a high level the key data points related to complex processes, such as capacity and distribution.
Data Requirements
Source data files for COVE Sankey diagrams must be in JSON format. View the source file for the example diagram above [JSON – 1 KB]. Note the following sections:
- links: This is the most critical section in the JSON file. From this section COVE generates the nodes and links. The screenshot below shows the definition of the two links from the far-left node in the diagram above to its target nodes “Completed Protocol” and “Aborted Protocol.” (The node label “In Treatment Protocol” does not display in the diagram because story text, as explained below, has been specified for the node to provide the year information.)
- storyNodeText: The source file can include specifications for extra node text to provide more context or to simply make the diagram easier to follow. You can include this text in the source file or enter it in the COVE editor. Either way, a maximum of 3 nodes can have story text. The screenshot below shows the story text specification for the far-left node “In Treatment Protocol.”
- tooltips: Sankey diagrams typically present high-level information, but you can add tooltips to the nodes. If you are not including tooltips, you should still include an empty tooltips section (as illustrated in the source file for the example at the top of the page [JSON – 1 KB]). To see another example diagram both with and without tooltips, along with its source file, go to the examples at the bottom of the page.
- tableData: To meet accessibility standards, each data visualization must have a supporting data table. Because of the unique structure of Sankey data, the data table contents must be specified in the source file. Make certain you include all key data points shown in the visualization. The screenshot below shows the first three rows of the data table for the example diagram at the top of the page. There are two columns: Protocol Status and Number of Patients.
Usage
In public health communications, Sankey diagrams are typically used to show the flow of patients through a healthcare system. But the Sankey is a very flexible visualization tool that can be used in a variety of ways as long as it shows flow, movement, or change.
It is best used when the following conditions apply:
- You are communicating an overall trend, not specific values.
- You have a small number of nodes and links to visualize. (If you have a large number of nodes, consider taking your visualization to a higher level.)
Keep in mind that even simpler Sankey diagrams can be hard to interpret for some viewers. Some of your viewers may not be familiar with the conventions of Sankey diagrams. Briefly explain to your readers how to read the diagram. (COVE currently requires a subtext / description for Sankey diagrams. You can use this text slot to explain the diagram.)
Note on Mobile Display:
In the smallest viewport, the visualization instructs the user to turn their phone to landscape because Sankey diagrams are not really built for vertical phone sizes.
Go to the example visualizations at the bottom of the page.
- Building in the WCMSSee key tips and guidelines for working with Sankey diagrams in the WCMS.
- TP4 UX Best Practices [PPT - 14 MB]For general guidance on colors, layouts, and overall presentation, see this overview of TP4 best practices.
Examples
A Sankey diagram is an interactive content type. Try selecting and deselecting “nodes” in the example diagrams below. (To deselect a node, click outside it.) For the first example, clicking a node displays the tooltip for the node (if provided in source file). For the second, the same source file is used, but tooltips are disabled in the COVE editor. When tooltips are turned off, clicking a node highlights its inflows.