matplotlib.sankey
#
Module for creating Sankey diagrams using Matplotlib.
- class matplotlib.sankey.Sankey(ax=None, scale=1.0, unit='', format='%G', gap=0.25, radius=0.1, shoulder=0.03, offset=0.15, head_angle=100, margin=0.4, tolerance=1e-06, **kwargs)[source]#
Bases:
object
Sankey diagram.
Sankey diagrams are a specific type of flow diagram, in which the width of the arrows is shown proportionally to the flow quantity. They are typically used to visualize energy or material or cost transfers between processes. Wikipedia (6/1/2011)
Create a new Sankey instance.
The optional arguments listed below are applied to all subdiagrams so that there is consistent alignment and formatting.
In order to draw a complex Sankey diagram, create an instance of
Sankey
by calling it without any kwargs:sankey = Sankey()
Then add simple Sankey sub-diagrams:
sankey.add() # 1 sankey.add() # 2 #... sankey.add() # n
Finally, create the full diagram:
sankey.finish()
Or, instead, simply daisy-chain those calls:
Sankey().add().add... .add().finish()
- Other Parameters:
- ax
Axes
Axes onto which the data should be plotted. If ax isn't provided, new Axes will be created.
- scalefloat
Scaling factor for the flows. scale sizes the width of the paths in order to maintain proper layout. The same scale is applied to all subdiagrams. The value should be chosen such that the product of the scale and the sum of the inputs is approximately 1.0 (and the product of the scale and the sum of the outputs is approximately -1.0).
- unitstr
The physical unit associated with the flow quantities. If unit is None, then none of the quantities are labeled.
- formatstr or callable
A Python number formatting string or callable used to label the flows with their quantities (i.e., a number times a unit, where the unit is given). If a format string is given, the label will be
format % quantity
. If a callable is given, it will be called withquantity
as an argument.- gapfloat
Space between paths that break in/break away to/from the top or bottom.
- radiusfloat
Inner radius of the vertical paths.
- shoulderfloat
Size of the shoulders of output arrows.
- offsetfloat
Text offset (from the dip or tip of the arrow).
- head_anglefloat
Angle, in degrees, of the arrow heads (and negative of the angle of the tails).
- marginfloat
Minimum space between Sankey outlines and the edge of the plot area.
- tolerancefloat
Acceptable maximum of the magnitude of the sum of flows. The magnitude of the sum of connected flows cannot be greater than tolerance.
- **kwargs
Any additional keyword arguments will be passed to
add
, which will create the first subdiagram.
- ax
See also
Examples
- add(patchlabel='', flows=None, orientations=None, labels='', trunklength=1.0, pathlengths=0.25, prior=None, connect=(0, 0), rotation=0, **kwargs)[source]#
Add a simple Sankey diagram with flows at the same hierarchical level.
- Parameters:
- patchlabelstr
Label to be placed at the center of the diagram. Note that label (not patchlabel) can be passed as keyword argument to create an entry in the legend.
- flowslist of float
Array of flow values. By convention, inputs are positive and outputs are negative.
Flows are placed along the top of the diagram from the inside out in order of their index within flows. They are placed along the sides of the diagram from the top down and along the bottom from the outside in.
If the sum of the inputs and outputs is nonzero, the discrepancy will appear as a cubic Bézier curve along the top and bottom edges of the trunk.
- orientationslist of {-1, 0, 1}
List of orientations of the flows (or a single orientation to be used for all flows). Valid values are 0 (inputs from the left, outputs to the right), 1 (from and to the top) or -1 (from and to the bottom).
- labelslist of (str or None)
List of labels for the flows (or a single label to be used for all flows). Each label may be None (no label), or a labeling string. If an entry is a (possibly empty) string, then the quantity for the corresponding flow will be shown below the string. However, if the unit of the main diagram is None, then quantities are never shown, regardless of the value of this argument.
- trunklengthfloat
Length between the bases of the input and output groups (in data-space units).
- pathlengthslist of float
List of lengths of the vertical arrows before break-in or after break-away. If a single value is given, then it will be applied to the first (inside) paths on the top and bottom, and the length of all other arrows will be justified accordingly. The pathlengths are not applied to the horizontal inputs and outputs.
- priorint
Index of the prior diagram to which this diagram should be connected.
- connect(int, int)
A (prior, this) tuple indexing the flow of the prior diagram and the flow of this diagram which should be connected. If this is the first diagram or prior is None, connect will be ignored.
- rotationfloat
Angle of rotation of the diagram in degrees. The interpretation of the orientations argument will be rotated accordingly (e.g., if rotation == 90, an orientations entry of 1 means to/from the left). rotation is ignored if this diagram is connected to an existing one (using prior and connect).
- Returns:
- Sankey
The current
Sankey
instance.
- Other Parameters:
- **kwargs
Additional keyword arguments set
matplotlib.patches.PathPatch
properties, listed below. For example, one may want to usefill=False
orlabel="A legend entry"
.Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
unknown
bool
antialiased
or aabool or None
CapStyle
or {'butt', 'projecting', 'round'}BboxBase
or Nonebool
Patch or (Path, Transform) or None
color
edgecolor
or eccolor or None
facecolor
or fccolor or None
bool
str
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
bool
JoinStyle
or {'miter', 'round', 'bevel'}object
linestyle
or ls{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth
or lwfloat or None
bool
list of
AbstractPathEffect
None or bool or float or callable
bool
(scale: float, length: float, randomness: float)
bool or None
str
bool
float
See also
- finish()[source]#
Adjust the axes and return a list of information about the Sankey subdiagram(s).
Returns a list of subdiagrams with the following fields:
Field
Description
patch
Sankey outline (a
PathPatch
).flows
Flow values (positive for input, negative for output).
angles
List of angles of the arrows [deg/90]. For example, if the diagram has not been rotated, an input to the top side has an angle of 3 (DOWN), and an output from the top side has an angle of 1 (UP). If a flow has been skipped (because its magnitude is less than tolerance), then its angle will be None.
tips
(N, 2)-array of the (x, y) positions of the tips (or "dips") of the flow paths. If the magnitude of a flow is less the tolerance of this
Sankey
instance, the flow is skipped and its tip will be at the center of the diagram.text
Text
instance for the diagram label.texts
List of
Text
instances for the flow labels.See also