{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# The Sankey class\n\nDemonstrate the Sankey class by producing three basic diagrams.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\n\nfrom matplotlib.sankey import Sankey"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Example 1 -- Mostly defaults\n\nThis demonstrates how to create a simple diagram by implicitly calling the\nSankey.add() method and by appending finish() to the call to the class.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "Sankey(flows=[0.25, 0.15, 0.60, -0.20, -0.15, -0.05, -0.50, -0.10],\n       labels=['', '', '', 'First', 'Second', 'Third', 'Fourth', 'Fifth'],\n       orientations=[-1, 1, 0, 1, 1, 1, 0, -1]).finish()\nplt.title(\"The default settings produce a diagram like this.\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Notice:\n\n1. Axes weren't provided when Sankey() was instantiated, so they were\n   created automatically.\n2. The scale argument wasn't necessary since the data was already\n   normalized.\n3. By default, the lengths of the paths are justified.\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Example 2\n\nThis demonstrates:\n\n1. Setting one path longer than the others\n2. Placing a label in the middle of the diagram\n3. Using the scale argument to normalize the flows\n4. Implicitly passing keyword arguments to PathPatch()\n5. Changing the angle of the arrow heads\n6. Changing the offset between the tips of the paths and their labels\n7. Formatting the numbers in the path labels and the associated unit\n8. Changing the appearance of the patch and the labels after the figure is\n   created\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig = plt.figure()\nax = fig.add_subplot(1, 1, 1, xticks=[], yticks=[],\n                     title=\"Flow Diagram of a Widget\")\nsankey = Sankey(ax=ax, scale=0.01, offset=0.2, head_angle=180,\n                format='%.0f', unit='%')\nsankey.add(flows=[25, 0, 60, -10, -20, -5, -15, -10, -40],\n           labels=['', '', '', 'First', 'Second', 'Third', 'Fourth',\n                   'Fifth', 'Hurray!'],\n           orientations=[-1, 1, 0, 1, 1, 1, -1, -1, 0],\n           pathlengths=[0.25, 0.25, 0.25, 0.25, 0.25, 0.6, 0.25, 0.25,\n                        0.25],\n           patchlabel=\"Widget\\nA\")  # Arguments to matplotlib.patches.PathPatch\ndiagrams = sankey.finish()\ndiagrams[0].texts[-1].set_color('r')\ndiagrams[0].text.set_fontweight('bold')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Notice:\n\n1. Since the sum of the flows is nonzero, the width of the trunk isn't\n   uniform.  The matplotlib logging system logs this at the DEBUG level.\n2. The second flow doesn't appear because its value is zero.  Again, this is\n   logged at the DEBUG level.\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Example 3\n\nThis demonstrates:\n\n1. Connecting two systems\n2. Turning off the labels of the quantities\n3. Adding a legend\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig = plt.figure()\nax = fig.add_subplot(1, 1, 1, xticks=[], yticks=[], title=\"Two Systems\")\nflows = [0.25, 0.15, 0.60, -0.10, -0.05, -0.25, -0.15, -0.10, -0.35]\nsankey = Sankey(ax=ax, unit=None)\nsankey.add(flows=flows, label='one',\n           orientations=[-1, 1, 0, 1, 1, 1, -1, -1, 0])\nsankey.add(flows=[-0.25, 0.15, 0.1], label='two',\n           orientations=[-1, -1, -1], prior=0, connect=(0, 0))\ndiagrams = sankey.finish()\ndiagrams[-1].patch.set_hatch('/')\nplt.legend()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Notice that only one connection is specified, but the systems form a\ncircuit since: (1) the lengths of the paths are justified and (2) the\norientation and ordering of the flows is mirrored.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "plt.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. admonition:: References\n\n   The use of the following functions, methods, classes and modules is shown\n   in this example:\n\n   - `matplotlib.sankey`\n   - `matplotlib.sankey.Sankey`\n   - `matplotlib.sankey.Sankey.add`\n   - `matplotlib.sankey.Sankey.finish`\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.13.2"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}