Sankey

Sankey

Sankey(
    *,
    series_name: str = "series",
    nodes: Nodes,
    connections: Connections,
    widget_id: str | None = None,
    formatting: NumberFormatting | None = None,
    title: WidgetTitleType = "",
)

Spec for Sankey widget.

Construct spec for Sankey widget.

Parameters:

Name	Type	Description	Default
series_name	str	name shown next to values in nodes and connections.	'series'
nodes	Nodes	spec for nodes.	required
connections	Connections	spec for connections.	required
widget_id	str | None	unique widget id in a dashboard.	None
formatting	NumberFormatting | None	formatting spec for value associated with nodes and connections.	None
title	WidgetTitleType	title of widget can be either a string (fixed value) or determined by a value from another widget using a WidgetLink.	''

Example:

Create a minimal Sankey widget

import pandas as pd
from engineai.sdk.dashboard.dashboard import Dashboard
from engineai.sdk.dashboard.widgets import sankey

nodes = pd.DataFrame({"id": ["company", "imports", "exports"]})
connections = pd.DataFrame(
    [
        {
            "from": "company",
            "to": "imports",
            "volume": 0.76,
        },
        {
            "from": "company",
            "to": "exports",
            "volume": 0.24,
        },
        {
            "from": "imports",
            "to": "exports",
            "volume": 0.23,
        },
    ]
)

sankey_widget = sankey.Sankey(
    series_name="Traded Volume",
    title="Sankey Widget",
    nodes=sankey.Nodes(
        data=nodes,
    ),
    connections=sankey.Connections(data_column="volume", data=connections),
)

Dashboard(
    workspace_slug="my-workspace",
    app_slug="my-app",
    slug="first-dashboard",
    content=sankey_widget,
)

Components

BaseConnections

BaseConnections(
    data: DataType | T,
    *,
    from_column: TemplatedStringItem = "from",
    to_column: TemplatedStringItem = "to",
    data_column: TemplatedStringItem = "value",
    styling: Palette | ConnectionsStyling | None = None,
    tooltips: TooltipItems | None = None,
)

Spec for Sankey connections.

Construct spec for connections in Sankey widget.

Parameters:

Name	Type	Description	Default
from_column	TemplatedStringItem	name of column in pandas dataframe with id for source node. Id needs to match one of the ids provided in the node dataframe.	'from'
to_column	TemplatedStringItem	name of column in pandas dataframe with id for destination node. Id needs to match one of the ids provided in the node dataframe.	'to'
data_column	TemplatedStringItem	name of column in pandas dataframe with value for connection.	'value'
data	DataType | T	data for the widget. Can be a pandas dataframe, a dictionary or Storage object if the data is to be retrieved from a storage.	required
styling	Palette | ConnectionsStyling | None	styling spec.	None
tooltips	TooltipItems | None	list of tooltip items.	None

ConnectionsStyling

ConnectionsStyling(
    *,
    color_spec: ColorSpec | None = None,
    data_column: TemplatedStringItem | None = None,
)

Spec to style connections in a Sankey widget.

Construct style spec for a node.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec | None	spec for coloring a node.	None
data_column	TemplatedStringItem | None	name of column in pandas dataframe(s) used for color spec if a gradient is used.	None

Raises:

Type	Description
SankeyDataColumnMissingError	if color_spec is DiscreteMap/Gradient and data_column has not been specified

BaseNodes

BaseNodes(
    data: DataType | T,
    *,
    id_column: TemplatedStringItem = "id",
    label_column: TemplatedStringItem | None = None,
    styling: Palette | NodesStyling | None = None,
    tooltips: TooltipItems | None = None,
)

Spec for Sankey nodes.

Construct spec for nodes in Sankey widget.

Parameters:

Name	Type	Description	Default
id_column	TemplatedStringItem	name of column in pandas dataframe with id of each node.	'id'
label_column	TemplatedStringItem | None	name of column in pandas dataframe with label for each node.	None
data	DataType | T	data for the widget. Can be a pandas dataframe, a dictionary or Storage object if the data is to be retrieved from a storage.	required
styling	Palette | NodesStyling | None	styling spec.	None
tooltips	TooltipItems | None	list of tooltip items.	None

NodesStyling

NodesStyling(
    *,
    color_spec: ColorSpec | None = None,
    data_column: TemplatedStringItem | None = None,
    width: int = 8,
)

Spec to style nodes in a Sankey widget.

Construct style spec for a node.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec | None	spec for coloring a node.	None
data_column	TemplatedStringItem | None	name of column in pandas dataframe(s) used for color spec if a gradient is used.	None
width	int	width of nodes in pixels.	8

Raises:

Type	Description
SankeyDataColumnMissingError	if color_spec is DiscreteMap/Gradient and data_column has not been specified

Types

Connections module-attribute

Connections = BaseConnections[DataFrame]

Nodes module-attribute

Nodes = BaseNodes[DataFrame]