diff --git a/evalhyd-python.ipynb b/evalhyd-python.ipynb
index 58a657a73a50de5d4cfa8adfd3a2e2f21db982ce..5b80a758c608de521b1a8706de79c396d87bf401 100644
--- a/evalhyd-python.ipynb
+++ b/evalhyd-python.ipynb
@@ -3,7 +3,7 @@
   {
    "cell_type": "markdown",
    "source": [
-    "### Deterministic evaluation"
+    "## `evalhyd-python` demonstration"
    ],
    "metadata": {
     "collapsed": false
@@ -15,15 +15,59 @@
    "outputs": [],
    "source": [
     "import numpy\n",
-    "\n",
-    "# define streamflow observations\n",
-    "#   > shape: {1, time: 4}\n",
+    "import evalhyd"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### Deterministic evaluation"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Define streamflow observations"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "# shape: {1, time: 4}\n",
     "obs = numpy.array(\n",
     "    [[4.7, 4.3, 5.5, 2.7]]\n",
-    ")\n",
-    "\n",
-    "# define streamflow predictions\n",
-    "#   > shape: {series: 1, time:4}\n",
+    ")"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Define streamflow predictions"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "# shape: {series: 1, time: 4}\n",
     "prd = numpy.array(\n",
     "    [[5.3, 4.2, 5.7, 2.3]]\n",
     ")"
@@ -32,16 +76,22 @@
     "collapsed": false
    }
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Compute Nash-Sutcliffe efficiency"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "import evalhyd\n",
-    "\n",
-    "# compute Nash-Sutcliffe efficiency\n",
-    "#   > shape: {series: 1, subsets: 1, samples: 1}\n",
+    "# shape: {series: 1, subsets: 1, samples: 1}\n",
     "evalhyd.evald(obs, prd, [\"NSE\"])"
    ]
   },
@@ -54,36 +104,84 @@
     "collapsed": false
    }
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Define streamflow observations"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "outputs": [],
    "source": [
-    "import numpy\n",
-    "\n",
-    "# define streamflow observations\n",
-    "#   > shape: {sites: 1, time: 5}\n",
+    "# shape: {sites: 1, time: 5}\n",
     "obs = numpy.array(\n",
     "    [[4.7, 4.3, 5.5, 2.7, 4.1]]\n",
-    ")\n",
-    "\n",
-    "# define streamflow predictions\n",
-    "#   > shape: {sites: 1, lead times: 1, members: 3, time: 5}\n",
+    ")"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Define streamflow predictions"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "# shape: {sites: 1, lead times: 1, members: 3, time: 5}\n",
     "prd = numpy.array(\n",
     "    [[[[5.3, 4.2, 5.7, 2.3, 3.1],\n",
     "       [4.3, 4.2, 4.7, 4.3, 3.3],\n",
     "       [5.3, 5.2, 5.7, 2.3, 3.9]]]]\n",
-    ")\n",
-    "\n",
-    "# define streamflow thresholds\n",
-    "#   > shape: {sites: 1, thresholds: 2}\n",
-    "thr = numpy.array([[4., 5.]])"
+    ")"
    ],
    "metadata": {
-    "collapsed": false,
-    "pycharm": {
-     "is_executing": true
-    }
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Define streamflow thresholds"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "# shape: {sites: 1, thresholds: 2}\n",
+    "thr = numpy.array(\n",
+    "    [[4., 5.]]\n",
+    ")"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Compute Brier score"
+   ],
+   "metadata": {
+    "collapsed": false
    }
   },
   {
@@ -91,10 +189,7 @@
    "execution_count": null,
    "outputs": [],
    "source": [
-    "import evalhyd\n",
-    "\n",
-    "# compute Brier score\n",
-    "#   > shape: {sites: 1, lead times: 1, subsets: 1, samples: 1, thresholds: 2}\n",
+    "# shape: {sites: 1, lead times: 1, subsets: 1, samples: 1, thresholds: 2}\n",
     "evalhyd.evalp(obs, prd, [\"BS\"], thr, events=\"high\")"
    ],
    "metadata": {