Add example of forwards-backwards flows.

docs/cookbook/forwards-backwards.ipynb

@@ -0,0 +1,133 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Forwards & backwards flows\n",
+    "\n",
+    "This recipe demonstrates how forwards and backwards flows work.\n",
+    "\n",
+    "For demonstration, the CSV data is written directly in the cell below -- in practice you would want to load data a file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "from io import StringIO\n",
+    "\n",
+    "flows = pd.read_csv(StringIO(\"\"\"\n",
+    "source,target,type,value\n",
+    "a,b,main,2\n",
+    "a,c,main,1\n",
+    "c,d,main,3\n",
+    "b,c,back,2\n",
+    "\"\"\"))\n",
+    "\n",
+    "flows"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here is one structure, with nodes `b` and `c` both in the same vertical slice:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from floweaver import *\n",
+    "\n",
+    "# Set the default size to fit the documentation better.\n",
+    "size = dict(width=570, height=300)\n",
+    "\n",
+    "nodes = {\n",
+    "    'a': ProcessGroup(['a']),\n",
+    "    'b': ProcessGroup(['b']),\n",
+    "    'c': ProcessGroup(['c']),\n",
+    "    'd': ProcessGroup(['d']),\n",
+    "    'back': Waypoint(direction='L'),\n",
+    "}\n",
+    "\n",
+    "bundles = [\n",
+    "    Bundle('a', 'b'),\n",
+    "    Bundle('a', 'c'),\n",
+    "    Bundle('b', 'c', waypoints=['back']),\n",
+    "    Bundle('c', 'd'),\n",
+    "    Bundle('c', 'b'),\n",
+    "]\n",
+    "\n",
+    "ordering = [\n",
+    "    [['a'], []],\n",
+    "    [['b', 'c'], ['back']],\n",
+    "    [['d'], []],\n",
+    "]\n",
+    "\n",
+    "sdd = SankeyDefinition(nodes, bundles, ordering)\n",
+    "\n",
+    "weave(sdd, flows).to_widget(**size)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Alternatively, if `b` is moved to the right, extra hidden waypoints are automatically added to get the `b--c` flow back to the left of `c`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bundles = [\n",
+    "    Bundle('a', 'b'),\n",
+    "    Bundle('a', 'c'),\n",
+    "    Bundle('b', 'c'),\n",
+    "    Bundle('c', 'd'),\n",
+    "    Bundle('c', 'b'),\n",
+    "]\n",
+    "\n",
+    "ordering = [\n",
+    "    [['a'], []],\n",
+    "    [['c'], ['back']],\n",
+    "    [['b', 'd'], []],\n",
+    "]\n",
+    "\n",
+    "sdd = SankeyDefinition(nodes, bundles, ordering)\n",
+    "\n",
+    "weave(sdd, flows).to_widget(**size)"
+   ]
+  }
+ ],
+ "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.6.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/index.rst

@@ -51,6 +51,7 @@ Shorter examples of how to do common tasks:
    :titlesonly:
 
    cookbook/imports-exports
+   cookbook/forwards-backwards
 
 API Documentation
 -----------------