Merge branch 'sankey-customdata'

Author: nicolaskruchten

doc/python/sankey-diagram.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.1
+      format_version: '1.2'
+      jupytext_version: 1.3.1
   kernel_info:
     name: python2
   kernelspec:
@@ -22,7 +22,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.6.8
   plotly:
     description: How to make Sankey Diagrams in Python with Plotly.
     display_as: basic
@@ -143,6 +143,38 @@ fig.update_layout(
 fig.show()
 ```
 
+### Hovertemplate and customdata of Sankey diagrams
+
+Links and nodes have their own hovertemplate, in which link- or node-specific attributes can be displayed. To add more data to links and nodes, it is possible to use the `customdata` attribute of `link` and `nodes`, as in the following example. For more information about hovertemplate and customdata, please see the [tutorial on hover text](/python/hover-text-and-formatting/).
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(data=[go.Sankey(
+    node = dict(
+      pad = 15,
+      thickness = 20,
+      line = dict(color = "black", width = 0.5),
+      label = ["A1", "A2", "B1", "B2", "C1", "C2"],
+      customdata = ["Long name A1", "Long name A2", "Long name B1", "Long name B2",
+                    "Long name C1", "Long name C2"],
+      hovertemplate='Node %{customdata} has total value %{value}<extra></extra>',  
+      color = "blue"
+    ),
+    link = dict(
+      source = [0, 1, 0, 2, 3, 3], # indices correspond to labels, eg A1, A2, A2, B1, ...
+      target = [2, 3, 3, 4, 4, 5],
+      value = [8, 4, 2, 8, 4, 2],
+      customdata = ["q","r","s","t","u","v"],
+      hovertemplate='Link from node %{source.customdata}<br />'+
+        'to node%{target.customdata}<br />has value %{value}'+
+        '<br />and data %{customdata}<extra></extra>',  
+  ))])
+
+fig.update_layout(title_text="Basic Sankey Diagram", font_size=10)
+fig.show()
+```
+
 ### Define Node Position
 
 The following example sets [node.x](https://plotly.com/python/reference/#sankey-node-x) and `node.y` to place nodes in the specified locations, except in the `snap arrangement` (default behaviour when `node.x` and `node.y` are not defined) to avoid overlapping of the nodes, therefore, an automatic snapping of elements will be set to define the padding between nodes via [nodepad](https://plotly.com/python/reference/#sankey-node-pad). The other possible arrangements are:<font color='blue'> 1)</font> perpendicular <font color='blue'>2)</font> freeform <font color='blue'>3)</font> fixed