Add legend_cols and legend_opts options (#1636)

Author: maximlt

doc/ref/plotting_options/legend.ipynb

@@ -82,6 +82,97 @@
    "source": [
     "plot7 + plot8"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e7f37498-781a-422b-9338-1b8d7d536076",
+   "metadata": {},
+   "source": [
+    "(option-legend_cols)=\n",
+    "## `legend_cols`\n",
+    "\n",
+    "The `legend_cols` option allows to define the number of columns of the legend grid."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c1e9c1dd-16fb-4685-b0be-619ce21227cd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hvplot.pandas  # noqa\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "df = pd.DataFrame({\"y\": np.random.random(20), \"cat\": list(map(chr, range(97, 117)))})\n",
+    "\n",
+    "df.hvplot.scatter(by=\"cat\", height=250, legend_cols=3, title=\"legend_cols=3\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "80cc2580-8c29-4fab-8947-8d3f3f937373",
+   "metadata": {},
+   "source": [
+    "(option-legend_opts)=\n",
+    "## `legend_opts`\n",
+    "\n",
+    "The `legend_opts` option allows to customize the legend styling. For the Bokeh plotting backend, the dictionary keys should be properties of its [`Legend` model](https://docs.bokeh.org/en/latest/docs/reference/models/annotations.html#bokeh.models.Legend), such as `background_fill_alpha`, `background_fill_color`, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0dafe596-72d3-4b6f-8484-ee3621bfb063",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hvplot.pandas  # noqa\n",
+    "\n",
+    "df = hvplot.sampledata.penguins(\"pandas\")\n",
+    "\n",
+    "df.hvplot.scatter(\n",
+    "    x=\"bill_length_mm\", y=\"bill_depth_mm\", by=\"species\",\n",
+    "    legend_opts={\"background_fill_alpha\": 0.2, \"background_fill_color\": \"grey\", \"spacing\": 20}\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4f2d87e8-8821-42d7-a71f-bb5daeaf0aed",
+   "metadata": {},
+   "source": [
+    "For the Matplotlib plotting backend, the keys should be keyword arguments of its [`Axes.legend` method](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html), such as `framealpha`, `facecolor`, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "739b34ee-ebf2-4acc-9a9b-3e659b1c6a74",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hvplot.pandas  # noqa\n",
+    "hvplot.extension(\"matplotlib\")\n",
+    "\n",
+    "df = hvplot.sampledata.penguins(\"pandas\")\n",
+    "\n",
+    "df.hvplot.scatter(\n",
+    "    x=\"bill_length_mm\", y=\"bill_depth_mm\", by=\"species\",\n",
+    "    legend_opts={\"framealpha\": 0.2, \"facecolor\": \"grey\", \"labelspacing\": 2}\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6296c0ce-f273-402e-8ff5-110b2d6c0a40",
+   "metadata": {},
+   "source": [
+    ":::{seealso}\n",
+    "The [`backend_opts`](option-backend_opts) option to customize even more the styling of a plot.\n",
+    ":::"
+   ]
   }
  ],
  "metadata": {

doc/ref/plotting_options/styling.ipynb

@@ -168,6 +168,16 @@
     "hv.renderer('matplotlib').get_plot(plot).handles['axis'].get_frame_on()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "adfa012f-a28c-4487-ad55-26fea7f38aa9",
+   "metadata": {},
+   "source": [
+    ":::{seealso}\n",
+    "The [`legend_opts`](option-legend_opts) option to customize specifically the styling of the legend.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "881751c3-4dc2-4027-9b7f-147fbe64a4f6",

hvplot/converter.py

@@ -343,6 +343,12 @@ class HoloViewsConverter:
         (``'top'``, ``'bottom'``, ``'left'``, ``'right'`` (default)) or a
         corner placement (``'top_left'``, ``'top_right'``, ``'bottom_left'``,
         ``'bottom_right'``).
+    legend_cols : int or None, default=None
+        Number of columns in the legend.
+    legend_opts : dict or None, default=None
+        Allows setting specific styling options for the legend. They keys
+        should be attributes of the ``Legend`` model for Bokeh and keyword
+        arguments of the ``Axes.legen`` method for Matplotlib.
 
     Interactivity Options
     ---------------------
@@ -630,6 +636,8 @@ class HoloViewsConverter:
 
     _legend_options = [
         'legend',
+        'legend_cols',
+        'legend_opts',
     ]
 
     _interactivity_options = [
@@ -835,6 +843,8 @@ def __init__(
         dynamic=True,
         grid=None,
         legend=None,
+        legend_cols=None,
+        legend_opts=None,
         rot=None,
         title=None,
         xlim=None,
@@ -1046,6 +1056,11 @@ def __init__(
                 'The legend option should be a boolean or '
                 f'a valid legend position (i.e. one of {list(self._legend_positions)}).'
             )
+        if legend_cols is not None:
+            plot_opts['legend_cols'] = legend_cols
+        if legend_opts is not None:
+            plot_opts['legend_opts'] = legend_opts
+
         if subcoordinate_y:
             plot_opts['subcoordinate_y'] = True
             if isinstance(subcoordinate_y, dict):

hvplot/tests/testoptions.py

@@ -596,6 +596,45 @@ def test_backend_opts(self, df, backend):
         opts = Store.lookup_options(backend, plot, 'plot')
         assert opts.kwargs['backend_opts'] == bo
 
+    @pytest.mark.parametrize(
+        'backend',
+        [
+            'bokeh',
+            'matplotlib',
+            pytest.param(
+                'plotly',
+                marks=pytest.mark.skip(reason='legend_cols not supported w/ plotly'),
+            ),
+        ],
+        indirect=True,
+    )
+    def test_legend_cols(self, df, backend):
+        plot = df.hvplot.scatter('x', 'y', by='category', legend_cols=2)
+        opts = Store.lookup_options(backend, plot, 'plot')
+        assert opts.kwargs['legend_cols'] == 2
+
+    @pytest.mark.parametrize(
+        'backend',
+        [
+            'bokeh',
+            'matplotlib',
+            pytest.param(
+                'plotly',
+                marks=pytest.mark.skip(reason='legend_opts not supported w/ plotly'),
+            ),
+        ],
+        indirect=True,
+    )
+    def test_legend_opts(self, df, backend):
+        if backend == 'bokeh':
+            lo = {'spacing': 20}
+        elif backend == 'matplotlib':
+            lo = {'labelspacing': 2}
+
+        plot = df.hvplot.scatter('x', 'y', by='category', legend_opts=lo)
+        opts = Store.lookup_options(backend, plot, 'plot')
+        assert opts.kwargs['legend_opts'] == lo
+
 
 @pytest.fixture(scope='module')
 def da():