class AlluvialPlot(clusters, axes, y_pos='overwrite', cluster_w_spacing=1, cluster_kwargs={}, flux_kwargs={}, label_kwargs={}, **kwargs)[source]

Bases: object

  • clusters (dict[str, dict], dict[float, list] or list[list]) –

    You have 2 options to create an Alluvial diagram:

    raw data: dict[str, dict]

    Provide for each cluster (key) a dictionary specifying the out-fluxes in the form of a dictionary (key: cluster, value: flux).


    The key None can hold a dictionary specifying fluxes from/to outside the system. If is present in the provided dictionary it allows to specify in-fluxes, i.e. data source that were not present at the previous slice.

    If it is present in the out-fluxes of a cluster, the specified amount simply vanishes and will not lead to a flux.

    collections of Cluster: dict[float, list] and list[list]
    If a list is provided each element must be a list of Cluster objects. A dictionary must provide a list of Cluster (value) for a horizontal position (key), e.g. {1.0: [c11, c12, ...], 2.0: [c21, c22, ...], ...}.
  • axes (matplotlib.axes.Axes) – Axes to draw an Alluvial diagram on.
  • y_pos (str) –

    options: 'overwrite', 'keep', 'complement', 'sorted'

    Ignore existing y coordinates for a cluster and set the vertical position to minimize the vertical displacements of all fluxes.
    use the cluster’s y_pos. If a cluster has no y position set this raises an exception.
    use the cluster’s y_pos if set. Cluster without y position are positioned relative to the other clusters by minimizing the vertical displacements of all fluxes.
  • cluster_w_spacing (float, int (default=1)) – Vertical spacing between clusters
  • cluster_kwargs (dict (default={})) –

    dictionary styling the Path elements of clusters.

    facecolor, edgecolor, alpha, linewidth, …
  • cluster_kwargs

    dictionary styling the PathPatch of clusters.

    for a list of available options see PathPatch

  • flux_kwargs (dict (default={})) –

    dictionary styling the PathPatch of fluxes.

    for a list of available options see PathPatch


    Passing a string to facecolor and/or edgecolor allows to color fluxes relative to the color of their source or target clusters.

    'source_cluster' or 'target_cluster':
    will set the facecolor equal to the color of the respective cluster.

    'cluster' and 'source_cluster' are equivalent.

    '<cluster>_reside' or '<cluster>_migration':
    set the color based on whether source and target cluster have the same color or not. '<cluster>' should be either 'source_cluster' or 'target_cluster' and determines the cluster from which the color is taken.


    set facecolor to the color of the source cluster if both source and target cluster are of the same color.
    set edgecolor to the color of the source cluster if source and target cluster are of different colors.
  • optional parameter (**kwargs) –
    x_lim: tuple
    the horizontal limit values for the Axes.
    y_lim: tuple
    the vertical limit values for the Axes.
    set_x_pos: bool
    if clusters is a dict then the key is set for all clusters
    cluster_width: float
    (NOT IMPLEMENTED) overwrites width of all clusters
    format_xaxis: bool (default=True)
    If set to True the axes is formatted according to the data provided. For now, this is only relevant if the horizontal positions are datetime objects. See set_dates_xaxis() for further informations.
    x_axis_offset: float
    how much space (relative to total height) should be reserved for the x_axis. If set to 0.0, then the x labels will not be visible.
    fill_figure: bool
    indicating whether or not set the axis dimension to fill up the entire figure
    invisible_x/invisible_y: bool
    whether or not to draw these axis.
    y_fix: dict
    with x_pos as keys and a list of tuples (cluster labels) as values. The position of clusters (tuples) are swapped.
    redistribute_vertically: int (default=4)
    how often the vertical pairwise swapping of clusters at a given time point should be performed.
    y_offset: float
    offsets the vertical position of each cluster by this amount.


    This ca be used to draw multiple alluvial diagrams on the same Axes by simply calling AlluvialPlot repeatedly with changing offset value, thus stacking alluvial diagrams.


Holds for each vertical position a list of Cluster objects.

color_clusters(patches, colormap=<matplotlib.colors.LinearSegmentedColormap object>)[source]


  • patches (list[PathPatch]) – Cluster patches to color.
  • colormap ( (default=’rainbow’)) – See the matplotlib tutorial for colormaps (link) for details.

Distribute the clusters for a given x_position vertically

Parameters:x_pos (float) – The horizontal position at which the clusters should be distributed. This must be a key of the clusters attribute.
get_labelcollection(*args, **kwargs)[source]
get_patchcollection(match_original=True, cluster_kwargs={}, flux_kwargs={}, *args, **kwargs)[source]

Gather the patchcollection to add to the axes

Parameters:kwargs – Options:
set_dates_xaxis(ax, resolution='months')[source]

Format the x axis in case datetime objects are provide for the horizontal placement of clusters.

  • ax (Axes) – Object to plot the alluvial diagram on.
  • resolution (str (default='months')) –

    Possible values are 'months' and 'weeks'. This determines the resolution of the minor ticks via set_minor_formatter. The major tick is then either given in years or months.


    Include further options or allow passing parameters directly to set_minor_formatter() and set_major_formatter().