A Sankey diagram is a visual representation that illustrates the flow of resources, quantities, or values between different entities or stages in a system. The diagram uses varying widths of connected arrows or lines to show the proportional relationships between these entities. Typical use cases are:

Energy Flows: Displaying the distribution and transformation of energy sources within a system, such as electricity generation or consumption.
Material Flows: Showing how materials move through different processes in manufacturing, supply chains, or recycling systems.

Starting the Control

To start the control click on the “Assets” button in the upper left corner of the PI Vision display. In the upper part select “weruSankey” by clicking on it.

Afterwards drag and drop any attribute on the Display. The Sankey Chart can now be used.

Configuration

With a right click on the control it is possible to press "Configure".

Thereby the configuration tile appears.

Check the checkbox Use AF.

Now you can configure what and where the Sankey Chart will scan in AF.

With the option AF Path you set the path to the AF Database that should be scanned for data.

With the option Medium you set the name of the attribute which is holding the data that should be visualized. This attribute needs to be in a certain Category, that can be configured with the option Category Name.

With the option Template Name you set what AF Object should be scanned.

Only AF Objects with one of the template names configured in this option will be looked at.

You can configure more than one template name. Just separate the template names with a “;” (see picture above)

If you changed any options, click on the blue button labeled “Load data” above the Sankey Chart to refresh it.

We highly recommend setting up the chart with an AF-Structure suitable for this. When you are not using AF, the Sankey Chart will show the standard Sankey, which is configured statically on the Server.

Change Standard Sankey

This can and should only be done by advanced users which are allowed to change files on the PI Vision server.

Ideally this was set up when installing the Werusys PI Vision Suite.

You need to edit the “weruPIVisionSuiteConfig.js” under “\PIVision\Scripts\app\editor\symbols\ext\libraries\”.

Then add or change like this:

var SankeyData = {

links: [

{target: "Energy Generation", value: 100.0},

{source: "Energy Generation", target: "Engine 1", value: 60.5},

{source: "Energy Generation", target: "Engine 2", value: 34.5},

{source: "Energy Generation", target: "Loss", value: "\\\\PI Vision Server\\cdt158"},

{source: "Engine 1", target: "Engine 1 heat", value: "AF Database\\Attribute"},

{source: "Engine 2", target: "Engine 2 heat", value: "8.42"}

]

};

This can only be changed by an admin!

Changing the Size of the Control

In case that the legend or some part of the control is not visible, it is necessary to adjust the size of the control. To do so, the first step is to change into edit mode (Icon in the upper right corner) and in a second step to click on the control. The eight appearing dots around the control can be used to adjust the size that everything is visible.

Removing the Control

Before removing the control it is necessary to switch into edit mode (Icon in the upper right corner). Thereafter it is possible to click on the control and press the delete key to remove the control.

Tutorial: Create an exemplary AF Database and display it in a Sankey diagram

Tutorial: A simple AF-Database for the Sankey diagram

We start in the PI System Explorer.

First, we create a new AF Database by clicking on “Database” in the top left corner.

In the pop-up window, we choose “New Database”.

We will name our Database “Sankey Demo Database” and click “OK”.

We choose our Database “Sankey Demo Database” from the list and click “OK” to open it.

Configuring the templates

Next, we will configure the templates. We first click on “Library” in the bottom left corner.

We click on “Element Templates” in the “Templates”-Tree.

We click on "New Template” to create a new element template.

We name the template “Structure Element” and give it an appropriate description.

Next, we will give it an attribute by clicking on “Attribute Templates” and “New Attribute Template”.

We name our attribute “Electricity Consumption” and associate it with the “Sankey”-Category. In the resulting pop-up, we choose “Yes” to create said category. In this example we will not use a designated Data Reference like a PI-Tag for our AF-attributes, as we merely want to set up an AF Database that will work as a basis for the Sankey diagram. In a productive environment, you might wish to configure the Data Reference as PI-Tags to save historical data.

Next, we will configure a rollup analysis template that will be used to sum up the consumption data from the lower levels upwards. We click on “Analysis Templates” and “Create a new analysis template”.

We name our analysis template “Electricity Consumption Rollup”, choose “Rollup” as our analysis type. We choose “Electricity Consumption” as the attribute we want to rollup from, choose “Sum” as the function and map the output to the attribute “Electricity Consumption”.

We choose a 5-minute-interval as our scheduling. In a productive environment, you might wish to choose different settings here.

Next, we will create an element template for the electricity meters. We click on “New Template” again and, under “General”, name it “Electricity Meter” and give it a description.

Under “Attribute Templates”, we choose “New Attribute Template” again and name the attribute “Electricity Consumption”. Yet again, we will not use a PI-Tag as a Data Reference but a Default Value of 5. In a productive environment, the Data Reference would likely be a PI-Tag that stores the consumption data. Note that we do not need to set the Category to “Sankey” as we will not use the Electricity Meter elements for our Sankey diagram. Our Sankey diagram will only show the flow through the Structure Elements that in turn will get their consumption data from the lower hierarchy level Structure Elements or Electricity Meters.

Building the organisational tree

Next, we will create elements from our templates. For that, we click on “Elements” in the bottom left corner. Then we click on “New Element”. In the pop-up, we choose “Structure Element” as our template.

We name our element “Site: Cologne” and give it a description.

Next, we click on “Child Elements” and “New Element”. We choose Structure Element as our template again. We give the element a name and description.

We repeat this process until we have our desired organisational tree.

After that, we add the electricity meters associated with the structure elements as new child elements. They need to be created from template “Electricity Meter”.

Lastly, we check in the changes.

Creating a Sankey diagram

Next, we navigate to our PI Vision website and create a new Display.

We choose the Sankey diagram symbol and add it to our display. It does not matter which Tag/Attribute we use as a DataSource as we will configure the Sankey diagram via its own configuration page. We will use the SINUSOID PI-Tag as a DataSource in our example, but again, this has no effect at all.

Next, we right click on the Sankey diagram and choose “Configure”. We tick the check box “Use AF”.

In the Settings page, we enter the following information: AF Database as “Sankey Demo Database”, Attribute Name as “Electricity Consumption”, Element Template Name as “Structure Element” and Category Name as “Sankey”.

Note that the elements created from the template “Electricity Meter” will not be scanned by the Sankey diagram as the configuration Element Template Name only reads “Structure Element”. If we wanted to scan elements from multiple templates, we could list multiple template names by separating them with a semicolon and no white space, eg. “Structure Element;Electricity Meter”.

We then click the button “Load data” above the Sankey diagram and see our hierarchical structure with the added-up consumption data.

Sankey