From 93bcef93ad637d731561dd00cb83ad060dd068f2 Mon Sep 17 00:00:00 2001
From: jlstevens <jlrstevens@gmail.com>
Date: Thu, 20 Jul 2023 13:45:24 +0200
Subject: [PATCH] Added twin axis section to Customizing Plots user guide

---
 examples/user_guide/Customizing_Plots.ipynb | 85 ++++++++++++++++++++-
 1 file changed, 84 insertions(+), 1 deletion(-)

diff --git a/examples/user_guide/Customizing_Plots.ipynb b/examples/user_guide/Customizing_Plots.ipynb
index e8bd59e536..6007aa78a5 100644
--- a/examples/user_guide/Customizing_Plots.ipynb
+++ b/examples/user_guide/Customizing_Plots.ipynb
@@ -44,7 +44,8 @@
     "    - [Inverting axes](#inverting-axes): Flipping the x-/y-axes and inverting an axis\n",
     "    - [Axis labels](#axis-labels): Setting axis labels using dimensions and options\n",
     "    - [Axis ranges](#axis-ranges): Controlling axes ranges using dimensions, padding and options\n",
-    "    - [Axis ticks](#axis-ticks): Controlling axis tick locations, labels and formatting"
+    "    - [Axis ticks](#axis-ticks): Controlling axis tick locations, labels and formatting\n",
+    "    - [Twin axes](#twin-axes): Enabling twin axes"
    ]
   },
   {
@@ -689,6 +690,88 @@
    "source": [
     "bars.opts(xrotation=45)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Twin axes\n",
+    "*(Available in HoloViews > 1.17)*\n",
+    "\n",
+    "HoloViews now supports displaying overlays containing two different value dimensions as twin axes for chart elements. To maintain backwards compatibility, this feature is only enabled by setting the `multi_y=True` option on the overlay:\n",
+    "\n",
+    "To illustrate, here is an overlay containing three curves with two value dimensions ('A' and 'B'). The following shows the default, backwards compatible behavior:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "overlay = hv.Curve([1, 2, 3], vdims=['A']) * hv.Curve([2, 3, 4], vdims=['A']) * hv.Curve([3, 2, 1], vdims=['B'])\n",
+    "overlay"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "Additional value dimensions do map to additional axes but be aware that support of multi axes beyond twin axes is currently considered experimental.\n",
+    "\n",
+    "#### Setting `multi_y=True`\n",
+    "\n",
+    "We can now enable twin axes by setting `multi_y=True` on the overlay:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "overlay.opts(multi_y=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The first value dimension is mapped to the left-hand axis and the second value dimension maps to the right axis. Note that the two axes are individually zoomable by hovering over them and using the Bokeh wheelzoom tool.\n",
+    "\n",
+    "\n",
+    "#### Supported `multi_y` options\n",
+    "\n",
+    "When `multi_y` is enabled, you can set individual axis options on the elements of the overlay.\n",
+    "\n",
+    "In this example, the left axis uses the default options while the right axis is an inverted, autoranged, log axis with a set `ylim`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "(hv.Curve([1, 2, 3], vdims=['A']) * hv.Curve([2, 3, 4], vdims=['B']).opts(autorange='y', invert_yaxis=True, logy=True, ylim=(1,10))).opts(multi_y=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Supported options for customizing individual axes are `apply_ranges`, `autorange='y'`, `invert_yaxis`, `logy` and `ylim`.\n",
+    "\n",
+    "Note that as of HoloViews 1.17.0, `multi_y` does not have streaming plot support"
+   ]
   }
  ],
  "metadata": {