Sankey diagram definitions

Sankey diagram definitions (SDDs) describe the structure of the Sankey diagram you want to end up with. They are declarative: you declare what you want up front, but the diagram isn’t created until later. This is useful if you want to use the same diagram structure for different data sources.

class SankeyDefinition(nodes: dict[str, ProcessGroup | Waypoint], bundles: Iterable[Bundle] | Mapping[Any, Bundle], ordering: Ordering | Iterable, flow_selection: str | None = None, flow_partition: Partition | None = None, time_partition: Partition | None = None)

class ProcessGroup(selection: Iterable[str] | str, partition: Partition | None = None, direction: Literal['R', 'L'] = 'R', title: str | None = None)

A ProcessGroup represents a group of processes from the underlying dataset.

The processes to include are defined by the selection. By default they are all lumped into one node in the diagram, but by defining a partition this can be controlled.

selection

If a list of strings, they are taken as process ids. If a single string, it is taken as a Pandas query string run against the process table.

Type:

list or string

partition

Defines how to split the ProcessGroup into subgroups.

Type:

Partition, optional

direction

Direction of flow, default ‘R’ (left-to-right).

Type:

‘R’ or ‘L’

title

Label for the ProcessGroup. If not set, the ProcessGroup id will be used.

Type:

string, optional

class Waypoint(partition: Partition | None = None, direction: Literal['R', 'L'] = 'R', title: str | None = None)

A Waypoint represents a control point along a Bundle of flows.

There are two reasons to define Waypoints: to control the routing of Bundle s of flows through the diagram, and to split flows according to some attributes by setting a partition.

partition

Defines how to split the Waypoint into subgroups.

Type:

Partition, optional

direction

Direction of flow, default ‘R’ (left-to-right).

Type:

‘R’ or ‘L’

title

Label for the Waypoint. If not set, the Waypoint id will be used.

Type:

string, optional

class Bundle(source: str | Elsewhere, target: str | Elsewhere, waypoints: Iterable[str] = (), flow_selection: list[str] | str | None = None, flow_partition: Partition | None = None, default_partition: Partition | None = None)

A Bundle represents a set of flows between two :class:`ProcessGroup`s.

source

The id of the ProcessGroup at the start of the Bundle.

Type:

string

target

The id of the ProcessGroup at the end of the Bundle.

Type:

string

waypoints

Optional list of ids of :class:`Waypoint`s the Bundle should pass through.

Type:

list of strings

flow_selection

Query string to filter the flows included in this Bundle.

Type:

string, optional

flow_partition

Defines how to split the flows in the Bundle into sub-flows. Often you want the same Partition for all the Bundles in the diagram, see SankeyDefinition.flow_partition.

Type:

Partition, optional

default_partition

Defines the Partition applied to any Waypoints automatically added to route the Bundle across layers of the diagram.

Type:

Partition, optional