From f23fb022cca3889e2fb6545eeccaabbaabe9f878 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Mon, 14 Apr 2025 11:58:42 +0100 Subject: [PATCH 01/10] add size and layout options notebook --- doc/ref/plot_options/index.md | 3 + doc/ref/plot_options/size.ipynb | 262 ++++++++++++++++++++++++++++++++ 2 files changed, 265 insertions(+) create mode 100644 doc/ref/plot_options/size.ipynb diff --git a/doc/ref/plot_options/index.md b/doc/ref/plot_options/index.md index 5cb3f5fa1..9ee4e213e 100644 --- a/doc/ref/plot_options/index.md +++ b/doc/ref/plot_options/index.md @@ -16,6 +16,8 @@ See [this page](./data) for more information on these options. .. plotting-options-table:: Size And Layout Options ``` +See [this page](./size) for more information on these options. + ## Axis Options ```{eval-rst} @@ -59,4 +61,5 @@ See [this page](./data) for more information on these options. All Options Data Options +Size and Layout Options ``` diff --git a/doc/ref/plot_options/size.ipynb b/doc/ref/plot_options/size.ipynb new file mode 100644 index 000000000..787c179be --- /dev/null +++ b/doc/ref/plot_options/size.ipynb @@ -0,0 +1,262 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "2ae44fa2-2ef0-4204-b9bb-b6051dfefd7c", + "metadata": {}, + "source": [ + "# Size and Layout Options\n", + "\n", + "\n", + "```{eval-rst}\n", + ".. plotting-options-table:: Size And Layout Options\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "2acaf31a-0348-4c0e-a486-ab165e59725b", + "metadata": {}, + "source": [ + "## `fontscale`\n", + "\n", + "The `fontscale` option scales all the fonts in the plot by the provided numeric factor. For example, setting `fontscale=1.5` enlarges the title, tick labels, and axis labels by 50%. This is useful when you want to emphasize text for presentations or detailed viewing." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f04a7fc8-687b-4ad7-b01f-ac102e5a5a4e", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.penguins(\"pandas\")\n", + "df.hvplot.scatter(\n", + " x='bill_length_mm',\n", + " y='bill_depth_mm',\n", + " by='species',\n", + " fontscale=1.5,\n", + " title=\"Penguins Species\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "c99dceda-b76f-450a-90ac-06735a1b001c", + "metadata": {}, + "source": [ + "## `frame_width / frame_height`\n", + "\n", + "The `frame_width` and `frame_height` options determine the width and height of the data area within the plot. They define the size of the plot’s core region (excluding axes, legends, and margins), allowing precise control over how the data is displayed." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1e5090c0-4687-477e-9603-42065aaf2791", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.earthquakes(\"pandas\")\n", + "df.hvplot.scatter(\n", + " x='lon',\n", + " y='lat',\n", + " by='mag_class',\n", + " tiles=True,\n", + " title=\"Earthquakes in the pacific\",\n", + " frame_width=600,\n", + " frame_height=400\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "16e0b4c9-1648-4087-82b9-0f1e3b064cd0", + "metadata": {}, + "source": [ + "## `max_width / max_height`\n", + "\n", + "The `max_width` and `max_height` options set the maximum allowed dimensions for the plot. These options come into play in responsive or dynamic layouts to ensure that the plot does not grow beyond the specified limits when the browser window is resized." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a6fbe571-c429-496f-809d-9f304f4773f5", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.xarray # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.air_temperature(\"xarray\")\n", + "df.hvplot.image(max_width=600, max_height=400, height=400, responsive=True)" + ] + }, + { + "cell_type": "markdown", + "id": "6848e006-ff12-4ccb-b9bf-85f9b8a02615", + "metadata": {}, + "source": [ + "By setting `max_width=600`, the plot cannot extend beyond 600 pixel units horizontally no matter the screen size the plot is being viewed in.\n", + "\n", + ":::{tip}\n", + "Try to view this plot on the largest screen you can find and see if the plot width extends beyond 600 pixel units.\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "8b39ac83-1031-4e11-9d86-ee42c35b4156", + "metadata": {}, + "source": [ + "## `min_width / min_height`\n", + "\n", + "Similar to [`max_width` and `max_height`](#max-width-max-height), these options define the minimum width and height for the plot. They ensure that the plot will not shrink below the specified dimensions in responsive layouts, helping maintain legibility even on smaller screens." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e3e5dde3-1b2c-42e2-96f1-23e6c1d212ad", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.xarray # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.air_temperature(\"xarray\")\n", + "df.hvplot.image(min_width=300, min_height=200, height=400, responsive=True)" + ] + }, + { + "cell_type": "markdown", + "id": "5b9faf80-dc9b-4dd6-ae8d-f73518cfc697", + "metadata": {}, + "source": [ + ":::{tip}\n", + "View this plot using your phone screen to see how the plot resizes\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "e5540910-2fbf-4d82-9528-616cb9a11a29", + "metadata": {}, + "source": [ + "## `height`\n", + "\n", + "The `height` and `width` option sets the overall height and width of the plot in pixels. By default, this is usually set to 300 and 700 pixels respectively. This dimension includes all components of the plot such as titles, labels, and margins." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "515f003d-090c-4dde-b3de-7d1ddbc1f979", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.xarray # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.air_temperature(\"xarray\")\n", + "df.hvplot.image(height=300, width=600)" + ] + }, + { + "cell_type": "markdown", + "id": "71fda055-de30-4d01-b2b3-3c0887403f7e", + "metadata": {}, + "source": [ + "## `width`\n", + "\n", + "See [`height`](#height) option above." + ] + }, + { + "cell_type": "markdown", + "id": "52616cd0-101a-4a7f-89d0-0d9e2f93370a", + "metadata": {}, + "source": [ + "## `padding`\n", + "\n", + "The `padding` option expands the plot’s automatically computed axis limits by a given fraction. When hvPlot determines the x and y ranges based on your data, it finds the minimum and maximum values needed to display all points. With padding applied, these ranges are extended by the specified fraction so that data points near the edges have more space. The padding value can be given as a single number for uniform padding, a tuple to specify different padding for the x- and y-axes, or even a nested tuple to set distinct padding for the upper and lower bounds of each axis." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4371a176-ef4e-483c-a7e3-5cfb77c5d51f", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.earthquakes(\"pandas\")\n", + "df.hvplot.scatter(\n", + " x='lon',\n", + " y='lat',\n", + " padding=0.2, # Adds 20% extra space around the auto-determined axis ranges\n", + " title=\"Earthquakes with 20% padding applied on both axes\",\n", + " tiles=True,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "091b16fc-608a-46ac-8c55-154bf9989871", + "metadata": {}, + "outputs": [], + "source": [ + "df = hvsampledata.earthquakes(\"pandas\")\n", + "df.hvplot.scatter(\n", + " x='lon',\n", + " y='lat',\n", + " padding=(0.2, 0.1), # Adds 20% on the x-axis and 10% on the y-axis\n", + " title=\"Earthquakes with 20% padding on x-axis and 10% padding on y-axis\",\n", + " tiles=True,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "8c900e07-2108-4741-859b-12309b41d03a", + "metadata": {}, + "source": [ + "## `responsive`\n", + "\n", + "When set to `True`, the responsive option allows the plot to automatically adjust its size based on the browser window. Note that responsive mode works only if at least one dimension (`width` or `height`) is left undefined; otherwise, the plot size remains fixed." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "846fdde4-9983-4101-a112-b184fe3f4dc0", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.penguins(\"pandas\")\n", + "df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', by='species', height=400, responsive=True)" + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} From 719bb19e39d66cc5288e4f0cea75a7dfd47f5bf6 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 30 Apr 2025 15:02:56 +0100 Subject: [PATCH 02/10] rename notebook --- .../{size.ipynb => size_layout.ipynb} | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) rename doc/ref/plotting_options/{size.ipynb => size_layout.ipynb} (95%) diff --git a/doc/ref/plotting_options/size.ipynb b/doc/ref/plotting_options/size_layout.ipynb similarity index 95% rename from doc/ref/plotting_options/size.ipynb rename to doc/ref/plotting_options/size_layout.ipynb index 787c179be..767a1e290 100644 --- a/doc/ref/plotting_options/size.ipynb +++ b/doc/ref/plotting_options/size_layout.ipynb @@ -56,7 +56,7 @@ { "cell_type": "code", "execution_count": null, - "id": "1e5090c0-4687-477e-9603-42065aaf2791", + "id": "bc2a449d-2375-456e-bfc6-9a640681538f", "metadata": {}, "outputs": [], "source": [ @@ -64,7 +64,8 @@ "import hvsampledata\n", "\n", "df = hvsampledata.earthquakes(\"pandas\")\n", - "df.hvplot.scatter(\n", + "\n", + "plot1 = df.hvplot.scatter(\n", " x='lon',\n", " y='lat',\n", " by='mag_class',\n", @@ -72,7 +73,18 @@ " title=\"Earthquakes in the pacific\",\n", " frame_width=600,\n", " frame_height=400\n", - ")" + ")\n", + "\n", + "plot2 = df.hvplot.scatter(\n", + " x='lon',\n", + " y='lat',\n", + " tiles=True,\n", + " title=\"Earthquakes in the pacific\",\n", + " frame_width=600,\n", + " frame_height=400\n", + ")\n", + "\n", + "(plot1 + plot2).cols(1)" ] }, { From f5e10a27b523a4186bb57b52f0fda41e209f5beb Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 30 Apr 2025 18:06:44 +0100 Subject: [PATCH 03/10] move 'fontscale' to styling options --- hvplot/converter.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/hvplot/converter.py b/hvplot/converter.py index 3a53a54aa..99baa73af 100644 --- a/hvplot/converter.py +++ b/hvplot/converter.py @@ -227,9 +227,6 @@ class HoloViewsConverter: Size And Layout Options ----------------------- - fontscale : number - Scales the size of all fonts by the same amount, e.g. fontscale=1.5 - enlarges all fonts (title, xticks, labels etc.) by 50% frame_width/frame_height : int The width and height of the data area of the plot max_width/max_height : int @@ -378,6 +375,9 @@ class HoloViewsConverter: Lower and upper bound of the color scale cnorm : str, default='linear' Color scaling which must be one of 'linear', 'log' or 'eq_hist' + fontscale : number + Scales the size of all fonts by the same amount, e.g. fontscale=1.5 + enlarges all fonts (title, xticks, labels etc.) by 50% fontsize : number or dict or None, default=None Set title, label and legend text to the same fontsize. Finer control by using a dict: {'title': '15pt', 'ylabel': '5px', 'ticks': 20} @@ -511,7 +511,6 @@ class HoloViewsConverter: ] _size_layout_options = [ - 'fontscale', 'frame_height', 'frame_width', 'height', @@ -572,6 +571,7 @@ class HoloViewsConverter: 'clim', 'color', 'colormap', + 'fontscale', 'fontsize', 'c', 'cmap', From 6b1ea5fe50bc1df96895a6f45b8fb0f8fd79ad8e Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 30 Apr 2025 18:07:38 +0100 Subject: [PATCH 04/10] delete redundant dir --- doc/ref/plot_options/index.md | 65 ----------------------------------- 1 file changed, 65 deletions(-) delete mode 100644 doc/ref/plot_options/index.md diff --git a/doc/ref/plot_options/index.md b/doc/ref/plot_options/index.md deleted file mode 100644 index 9ee4e213e..000000000 --- a/doc/ref/plot_options/index.md +++ /dev/null @@ -1,65 +0,0 @@ -(plot-options)= - -# Plot Options - -## Data Options - -```{eval-rst} -.. plotting-options-table:: Data Options -``` - -See [this page](./data) for more information on these options. - -## Size And Layout Options - -```{eval-rst} -.. plotting-options-table:: Size And Layout Options -``` - -See [this page](./size) for more information on these options. - -## Axis Options - -```{eval-rst} -.. plotting-options-table:: Axis Options -``` - -## Grid And Legend Options - -```{eval-rst} -.. plotting-options-table:: Grid And Legend Options -``` - -## Style Options - -```{eval-rst} -.. plotting-options-table:: Style Options -``` - -## Resampling Options - -```{eval-rst} -.. plotting-options-table:: Resampling Options -``` - -## Geographic Options - -```{eval-rst} -.. plotting-options-table:: Geographic Options -``` - -## Streaming Options - -```{eval-rst} -.. plotting-options-table:: Streaming Options -``` - -```{toctree} -:titlesonly: -:hidden: -:maxdepth: 2 - -All Options -Data Options -Size and Layout Options -``` From 75c1386146450e5225a5f0b5725518c7d0c7caf5 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 30 Apr 2025 18:15:52 +0100 Subject: [PATCH 05/10] move aspect and data aspect to size_layout options --- hvplot/converter.py | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/hvplot/converter.py b/hvplot/converter.py index 99baa73af..55b25b327 100644 --- a/hvplot/converter.py +++ b/hvplot/converter.py @@ -227,6 +227,19 @@ class HoloViewsConverter: Size And Layout Options ----------------------- + aspect : str or float or None, default=None + The aspect ratio mode of the plot. By default, a plot may + select its own appropriate aspect ratio but sometimes it may + be necessary to force a square aspect ratio (e.g. to display + the plot as an element of a grid). The modes 'auto' and + 'equal' correspond to the axis modes of the same name in + matplotlib, a numeric value specifying the ratio between plot + width and height may also be passed. To control the aspect + ratio between the axis scales use the ``data_aspect`` option + instead. + data_aspect : float or None, default=None + Defines the aspect of the axis scaling, i.e. the ratio of + y-unit to x-unit. frame_width/frame_height : int The width and height of the data area of the plot max_width/max_height : int @@ -252,19 +265,6 @@ class HoloViewsConverter: Axis Options ------------ - aspect : str or float or None, default=None - The aspect ratio mode of the plot. By default, a plot may - select its own appropriate aspect ratio but sometimes it may - be necessary to force a square aspect ratio (e.g. to display - the plot as an element of a grid). The modes 'auto' and - 'equal' correspond to the axis modes of the same name in - matplotlib, a numeric value specifying the ratio between plot - width and height may also be passed. To control the aspect - ratio between the axis scales use the ``data_aspect`` option - instead. - data_aspect : float or None, default=None - Defines the aspect of the axis scaling, i.e. the ratio of - y-unit to x-unit. autorange : Literal['x', 'y'] or None, default=None Whether to enable auto-ranging along the x- or y-axis when zooming. Requires HoloViews >= 1.16. @@ -511,6 +511,8 @@ class HoloViewsConverter: ] _size_layout_options = [ + 'aspect', + 'data_aspect', 'frame_height', 'frame_width', 'height', @@ -524,8 +526,6 @@ class HoloViewsConverter: ] _axis_config_options = [ - 'aspect', - 'data_aspect', 'autorange', 'clabel', 'flip_xaxis', From 6f94f295cc3e6501292c0c0cdca3fb62a0f62296 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 30 Apr 2025 18:47:43 +0100 Subject: [PATCH 06/10] update notebook --- doc/ref/plotting_options/index.md | 3 + doc/ref/plotting_options/size_layout.ipynb | 99 ++++++++++++++-------- 2 files changed, 67 insertions(+), 35 deletions(-) diff --git a/doc/ref/plotting_options/index.md b/doc/ref/plotting_options/index.md index 872119d40..ca4c28afd 100644 --- a/doc/ref/plotting_options/index.md +++ b/doc/ref/plotting_options/index.md @@ -34,6 +34,8 @@ Customization options for plot sizes and overall layout, including responsive mo .. plotting-options-table:: Size And Layout Options ``` +See [this page](./size_layout) for more information on these options. + ## Axis Options Customization options for axis appearance and behavior, including labels, limits, tick formatting, and axis scaling: @@ -103,4 +105,5 @@ Options for handling live data streams: All Options Data Options +Size And Layout Options ``` diff --git a/doc/ref/plotting_options/size_layout.ipynb b/doc/ref/plotting_options/size_layout.ipynb index 767a1e290..56560a96d 100644 --- a/doc/ref/plotting_options/size_layout.ipynb +++ b/doc/ref/plotting_options/size_layout.ipynb @@ -5,7 +5,7 @@ "id": "2ae44fa2-2ef0-4204-b9bb-b6051dfefd7c", "metadata": {}, "source": [ - "# Size and Layout Options\n", + "# Size And Layout Options\n", "\n", "\n", "```{eval-rst}\n", @@ -15,18 +15,24 @@ }, { "cell_type": "markdown", - "id": "2acaf31a-0348-4c0e-a486-ab165e59725b", + "id": "c20d146d-c67f-40be-b505-edadc4e94bd7", "metadata": {}, "source": [ - "## `fontscale`\n", + "## `aspect`\n", "\n", - "The `fontscale` option scales all the fonts in the plot by the provided numeric factor. For example, setting `fontscale=1.5` enlarges the title, tick labels, and axis labels by 50%. This is useful when you want to emphasize text for presentations or detailed viewing." + "The `aspect` option controls the overall shape of the plot by setting the ratio of its width to its height.\n", + "You can specify 'auto', 'equal', or a numeric value:\n", + "- 'auto': The plot determines its own aspect ratio (default).\n", + "- 'equal': Ensures the axes have the same scaling (e.g. for square plots).\n", + "- A float like 2.0: Sets the width-to-height ratio directly.\n", + "\n", + "This option is useful when you want to maintain consistent plot proportions, especially in layouts or grid displays." ] }, { "cell_type": "code", "execution_count": null, - "id": "f04a7fc8-687b-4ad7-b01f-ac102e5a5a4e", + "id": "fe824752-06d2-43f3-aa49-770a118c2222", "metadata": {}, "outputs": [], "source": [ @@ -34,13 +40,34 @@ "import hvsampledata\n", "\n", "df = hvsampledata.penguins(\"pandas\")\n", - "df.hvplot.scatter(\n", - " x='bill_length_mm',\n", - " y='bill_depth_mm',\n", - " by='species',\n", - " fontscale=1.5,\n", - " title=\"Penguins Species\"\n", - ")" + "df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', aspect=1.5)" + ] + }, + { + "cell_type": "markdown", + "id": "de030cee-46a2-4d8d-b12a-e685bd616e27", + "metadata": {}, + "source": [ + "## `data_aspect`\n", + "\n", + "The `data_aspect` option sets the scaling between axis units, i.e., the ratio of the number of y-units per x-unit.\n", + "This is particularly useful for geographic or image data where you want equal distances on both axes (e.g., a degree of latitude and longitude should appear equal).\n", + "\n", + "Unlike `aspect` which controls **plot shape**, `data_aspect` affects the **visual scaling of the data itself**." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "eb20eb44-6216-4a94-94e7-1c50c2755eb0", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.xarray # noqa\n", + "import hvsampledata\n", + "\n", + "ds = hvsampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n", + "ds.hvplot.image(data_aspect=1)" ] }, { @@ -70,7 +97,7 @@ " y='lat',\n", " by='mag_class',\n", " tiles=True,\n", - " title=\"Earthquakes in the pacific\",\n", + " title=\"Earthquakes plot with legend\",\n", " frame_width=600,\n", " frame_height=400\n", ")\n", @@ -79,7 +106,7 @@ " x='lon',\n", " y='lat',\n", " tiles=True,\n", - " title=\"Earthquakes in the pacific\",\n", + " title=\"Earthquakes plot without legend\",\n", " frame_width=600,\n", " frame_height=400\n", ")\n", @@ -87,6 +114,14 @@ "(plot1 + plot2).cols(1)" ] }, + { + "cell_type": "markdown", + "id": "1fab0208-b888-4fbe-a365-6615411d604e", + "metadata": {}, + "source": [ + "Notice how both plots above have the same size in the core data area even though the first plot includes a legend." + ] + }, { "cell_type": "markdown", "id": "16e0b4c9-1648-4087-82b9-0f1e3b064cd0", @@ -107,7 +142,7 @@ "import hvplot.xarray # noqa\n", "import hvsampledata\n", "\n", - "df = hvsampledata.air_temperature(\"xarray\")\n", + "df = hvsampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n", "df.hvplot.image(max_width=600, max_height=400, height=400, responsive=True)" ] }, @@ -143,7 +178,7 @@ "import hvplot.xarray # noqa\n", "import hvsampledata\n", "\n", - "df = hvsampledata.air_temperature(\"xarray\")\n", + "df = hvsampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n", "df.hvplot.image(min_width=300, min_height=200, height=400, responsive=True)" ] }, @@ -177,7 +212,7 @@ "import hvplot.xarray # noqa\n", "import hvsampledata\n", "\n", - "df = hvsampledata.air_temperature(\"xarray\")\n", + "df = hvsampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n", "df.hvplot.image(height=300, width=600)" ] }, @@ -208,17 +243,12 @@ "metadata": {}, "outputs": [], "source": [ + "import pandas as pd\n", "import hvplot.pandas # noqa\n", - "import hvsampledata\n", "\n", - "df = hvsampledata.earthquakes(\"pandas\")\n", - "df.hvplot.scatter(\n", - " x='lon',\n", - " y='lat',\n", - " padding=0.2, # Adds 20% extra space around the auto-determined axis ranges\n", - " title=\"Earthquakes with 20% padding applied on both axes\",\n", - " tiles=True,\n", - ")" + "df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})\n", + "# Add 20% extra space around the auto-determined axis ranges\n", + "df.hvplot.scatter(x='x', y='y', padding=0.2)" ] }, { @@ -228,14 +258,12 @@ "metadata": {}, "outputs": [], "source": [ - "df = hvsampledata.earthquakes(\"pandas\")\n", - "df.hvplot.scatter(\n", - " x='lon',\n", - " y='lat',\n", - " padding=(0.2, 0.1), # Adds 20% on the x-axis and 10% on the y-axis\n", - " title=\"Earthquakes with 20% padding on x-axis and 10% padding on y-axis\",\n", - " tiles=True,\n", - ")" + "import pandas as pd\n", + "import hvplot.pandas # noqa\n", + "\n", + "df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})\n", + "# Add 20% on the x-axis and 10% on the y-axis\n", + "df.hvplot.scatter(x='x', y='y', padding=(0.2, 0.1))" ] }, { @@ -259,7 +287,8 @@ "import hvsampledata\n", "\n", "df = hvsampledata.penguins(\"pandas\")\n", - "df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', by='species', height=400, responsive=True)" + "df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', by='species',\n", + " height=400, responsive=True)" ] } ], From d8f576ca6b75840382b3e437adcbdb336f8175f0 Mon Sep 17 00:00:00 2001 From: maximlt Date: Tue, 13 May 2025 14:51:30 +0200 Subject: [PATCH 07/10] various minor updates --- doc/ref/plotting_options/size_layout.ipynb | 112 +++++++++++++-------- 1 file changed, 69 insertions(+), 43 deletions(-) diff --git a/doc/ref/plotting_options/size_layout.ipynb b/doc/ref/plotting_options/size_layout.ipynb index 56560a96d..f2c161010 100644 --- a/doc/ref/plotting_options/size_layout.ipynb +++ b/doc/ref/plotting_options/size_layout.ipynb @@ -18,12 +18,13 @@ "id": "c20d146d-c67f-40be-b505-edadc4e94bd7", "metadata": {}, "source": [ + "(option-aspect)=\n", "## `aspect`\n", "\n", "The `aspect` option controls the overall shape of the plot by setting the ratio of its width to its height.\n", - "You can specify 'auto', 'equal', or a numeric value:\n", - "- 'auto': The plot determines its own aspect ratio (default).\n", - "- 'equal': Ensures the axes have the same scaling (e.g. for square plots).\n", + "You can specify `'auto'`, `'equal'`, or a numeric value:\n", + "- `'auto'`: The plot determines its own aspect ratio (default).\n", + "- `'equal'`: Ensures the axes have the same scaling (e.g. for square plots).\n", "- A float like 2.0: Sets the width-to-height ratio directly.\n", "\n", "This option is useful when you want to maintain consistent plot proportions, especially in layouts or grid displays." @@ -48,12 +49,13 @@ "id": "de030cee-46a2-4d8d-b12a-e685bd616e27", "metadata": {}, "source": [ + "(option-data_aspect)=\n", "## `data_aspect`\n", "\n", "The `data_aspect` option sets the scaling between axis units, i.e., the ratio of the number of y-units per x-unit.\n", "This is particularly useful for geographic or image data where you want equal distances on both axes (e.g., a degree of latitude and longitude should appear equal).\n", "\n", - "Unlike `aspect` which controls **plot shape**, `data_aspect` affects the **visual scaling of the data itself**." + "Unlike [`aspect`](option-aspect) which controls **plot shape**, `data_aspect` affects the **visual scaling of the data itself**." ] }, { @@ -75,6 +77,7 @@ "id": "c99dceda-b76f-450a-90ac-06735a1b001c", "metadata": {}, "source": [ + "(option-frame_width__frame_height)=\n", "## `frame_width / frame_height`\n", "\n", "The `frame_width` and `frame_height` options determine the width and height of the data area within the plot. They define the size of the plot’s core region (excluding axes, legends, and margins), allowing precise control over how the data is displayed." @@ -83,43 +86,29 @@ { "cell_type": "code", "execution_count": null, - "id": "bc2a449d-2375-456e-bfc6-9a640681538f", + "id": "de201f6b-0f7c-431a-8141-b86828068548", "metadata": {}, "outputs": [], "source": [ - "import hvplot.pandas # noqa\n", - "import hvsampledata\n", - "\n", - "df = hvsampledata.earthquakes(\"pandas\")\n", - "\n", - "plot1 = df.hvplot.scatter(\n", - " x='lon',\n", - " y='lat',\n", - " by='mag_class',\n", - " tiles=True,\n", - " title=\"Earthquakes plot with legend\",\n", - " frame_width=600,\n", - " frame_height=400\n", - ")\n", - "\n", - "plot2 = df.hvplot.scatter(\n", - " x='lon',\n", - " y='lat',\n", - " tiles=True,\n", - " title=\"Earthquakes plot without legend\",\n", - " frame_width=600,\n", - " frame_height=400\n", - ")\n", - "\n", - "(plot1 + plot2).cols(1)" + "df.hvplot.scatter(\"bill_length_mm\", \"bill_depth_mm\", by=\"species\", frame_width=300, frame_height=200)" ] }, { "cell_type": "markdown", - "id": "1fab0208-b888-4fbe-a365-6615411d604e", + "id": "e7b0802b-ca6a-4da9-be28-93351e142475", + "metadata": {}, + "source": [ + "Setting `width` and `height` to the same values, notice how the plot below ends up much smaller than the above, as `width` and `height` affect for the whole plot area." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7254e255-2232-4f0b-a9be-d7520aed2821", "metadata": {}, + "outputs": [], "source": [ - "Notice how both plots above have the same size in the core data area even though the first plot includes a legend." + "df.hvplot.scatter(\"bill_length_mm\", \"bill_depth_mm\", by=\"species\", width=300, height=200)" ] }, { @@ -127,6 +116,7 @@ "id": "16e0b4c9-1648-4087-82b9-0f1e3b064cd0", "metadata": {}, "source": [ + "(option-max_width__max_height)=\n", "## `max_width / max_height`\n", "\n", "The `max_width` and `max_height` options set the maximum allowed dimensions for the plot. These options come into play in responsive or dynamic layouts to ensure that the plot does not grow beyond the specified limits when the browser window is resized." @@ -158,14 +148,26 @@ ":::" ] }, + { + "cell_type": "markdown", + "id": "6795d04b-e475-4b59-98d5-8afc7da4e6f0", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "- [`min_width / min_height`](option-min_width__min_height)\n", + "- [`responsive`](option-responsive)\n", + ":::" + ] + }, { "cell_type": "markdown", "id": "8b39ac83-1031-4e11-9d86-ee42c35b4156", "metadata": {}, "source": [ + "(option-min_width__min_height)=\n", "## `min_width / min_height`\n", "\n", - "Similar to [`max_width` and `max_height`](#max-width-max-height), these options define the minimum width and height for the plot. They ensure that the plot will not shrink below the specified dimensions in responsive layouts, helping maintain legibility even on smaller screens." + "Similar to [`max_width` and `max_height`](option-max_width__max_height), these options define the minimum width and height for the plot. They ensure that the plot will not shrink below the specified dimensions in responsive layouts, helping maintain legibility even on smaller screens." ] }, { @@ -192,11 +194,23 @@ ":::" ] }, + { + "cell_type": "markdown", + "id": "9c58154b-e379-4e7f-9c00-db60aa001629", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "- [`max_width / max_height`](option-max_width__max_height)\n", + "- [`responsive`](option-responsive)\n", + ":::" + ] + }, { "cell_type": "markdown", "id": "e5540910-2fbf-4d82-9528-616cb9a11a29", "metadata": {}, "source": [ + "(option-height)=\n", "## `height`\n", "\n", "The `height` and `width` option sets the overall height and width of the plot in pixels. By default, this is usually set to 300 and 700 pixels respectively. This dimension includes all components of the plot such as titles, labels, and margins." @@ -221,9 +235,10 @@ "id": "71fda055-de30-4d01-b2b3-3c0887403f7e", "metadata": {}, "source": [ + "(option-width)=\n", "## `width`\n", "\n", - "See [`height`](#height) option above." + "See [`height`](option-height) option above." ] }, { @@ -231,6 +246,7 @@ "id": "52616cd0-101a-4a7f-89d0-0d9e2f93370a", "metadata": {}, "source": [ + "(option-padding)=\n", "## `padding`\n", "\n", "The `padding` option expands the plot’s automatically computed axis limits by a given fraction. When hvPlot determines the x and y ranges based on your data, it finds the minimum and maximum values needed to display all points. With padding applied, these ranges are extended by the specified fraction so that data points near the edges have more space. The padding value can be given as a single number for uniform padding, a tuple to specify different padding for the x- and y-axes, or even a nested tuple to set distinct padding for the upper and lower bounds of each axis." @@ -248,7 +264,7 @@ "\n", "df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})\n", "# Add 20% extra space around the auto-determined axis ranges\n", - "df.hvplot.scatter(x='x', y='y', padding=0.2)" + "df.hvplot.scatter(x='x', y='y', padding=0.2, height=200)" ] }, { @@ -258,12 +274,8 @@ "metadata": {}, "outputs": [], "source": [ - "import pandas as pd\n", - "import hvplot.pandas # noqa\n", - "\n", - "df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})\n", - "# Add 20% on the x-axis and 10% on the y-axis\n", - "df.hvplot.scatter(x='x', y='y', padding=(0.2, 0.1))" + "# Add 20% on the x-axis and 5% on the y-axis\n", + "df.hvplot.scatter(x='x', y='y', padding=(0.2, 0.05), height=200)" ] }, { @@ -271,6 +283,7 @@ "id": "8c900e07-2108-4741-859b-12309b41d03a", "metadata": {}, "source": [ + "(option-responsive)=\n", "## `responsive`\n", "\n", "When set to `True`, the responsive option allows the plot to automatically adjust its size based on the browser window. Note that responsive mode works only if at least one dimension (`width` or `height`) is left undefined; otherwise, the plot size remains fixed." @@ -287,8 +300,21 @@ "import hvsampledata\n", "\n", "df = hvsampledata.penguins(\"pandas\")\n", - "df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', by='species',\n", - " height=400, responsive=True)" + "df.hvplot.scatter(\n", + " x='bill_length_mm', y='bill_depth_mm', by='species',\n", + " height=300, responsive=True\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "9a7924e9-b9f9-4238-a4cf-e8449cedb8cb", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "- [`min_width / min_height`](option-min_width__min_height)\n", + "- [`max_width / max_height`](option-max_width__max_height)\n", + ":::" ] } ], From 2a0eb322e063f5307e63b4813233b066830517d9 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Tue, 13 May 2025 17:11:52 +0100 Subject: [PATCH 08/10] update notebook --- doc/ref/plotting_options/size_layout.ipynb | 55 ++++++++++++++++++---- 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/doc/ref/plotting_options/size_layout.ipynb b/doc/ref/plotting_options/size_layout.ipynb index f2c161010..67b674ef5 100644 --- a/doc/ref/plotting_options/size_layout.ipynb +++ b/doc/ref/plotting_options/size_layout.ipynb @@ -21,13 +21,26 @@ "(option-aspect)=\n", "## `aspect`\n", "\n", - "The `aspect` option controls the overall shape of the plot by setting the ratio of its width to its height.\n", - "You can specify `'auto'`, `'equal'`, or a numeric value:\n", - "- `'auto'`: The plot determines its own aspect ratio (default).\n", - "- `'equal'`: Ensures the axes have the same scaling (e.g. for square plots).\n", - "- A float like 2.0: Sets the width-to-height ratio directly.\n", + "The `aspect` option controls the **frame** shape by setting the ratio of its width to its height. By default (`aspect=None`), HoloViews chooses an appropriate ratio automatically. Use:\n", "\n", - "This option is useful when you want to maintain consistent plot proportions, especially in layouts or grid displays." + "- `'square'` \n", + " Forces a square frame. \n", + " - If you set only `frame_width`, the height will be made equal to it. \n", + " - If you set only `frame_height`, the width will be matched to it. \n", + " - If you set both, the aspect value will be ignored with a warning displayed.\n", + "\n", + "- `'equal'` \n", + " Ensures the frame maintains the default height to width ratios (300:700). \n", + " - If you specify `frame_width` but omit `frame_height`, the height is re-computed to match the original ratios. \n", + " - If you specify `frame_height` but omit `frame_width`, the width is re-computed to match the original ratios. \n", + " - If you explicitly set both `frame_width` and `frame_height`, those values are respected and the aspect value ignored.\n", + "\n", + "- A float, e.g. `2.0` \n", + " Directly sets the width : height ratio (so `aspect=2.0` makes it twice as wide as it is tall).\n", + "\n", + "If you need to control the **data-unit** scaling (so that one y-unit equals one x-unit), use the [`data_aspect`](option-data_aspect) option instead. \n", + "\n", + "Keeping `aspect` and `data_aspect` distinct lets you manage both your plot’s **pixel proportions** and your **data-unit proportions** independently. " ] }, { @@ -41,7 +54,26 @@ "import hvsampledata\n", "\n", "df = hvsampledata.penguins(\"pandas\")\n", - "df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', aspect=1.5)" + "\n", + "(\n", + " df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", + " frame_width=200, title=\"Default aspect\")\n", + " + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", + " frame_width=200, aspect=0.6, title=\"3:5 ratio\")\n", + " + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", + " frame_width=200, aspect='square', title=\"Square plot (1:1 ratio)\")\n", + " + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", + " frame_width=200, aspect='equal', title=\"Re-computed frame_height\")\n", + ").cols(2)" + ] + }, + { + "cell_type": "markdown", + "id": "24837128-7483-4a70-9fa0-011dc1d73606", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "[`frame_width/frame_height`](option-frame_width__frame_height)" ] }, { @@ -90,7 +122,12 @@ "metadata": {}, "outputs": [], "source": [ - "df.hvplot.scatter(\"bill_length_mm\", \"bill_depth_mm\", by=\"species\", frame_width=300, frame_height=200)" + "import hvplot.pandas # noqa\n", + "import hvsampledata\n", + "\n", + "df = hvsampledata.penguins(\"pandas\")\n", + "df.hvplot.scatter(\"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n", + " frame_width=300, frame_height=200)" ] }, { @@ -98,7 +135,7 @@ "id": "e7b0802b-ca6a-4da9-be28-93351e142475", "metadata": {}, "source": [ - "Setting `width` and `height` to the same values, notice how the plot below ends up much smaller than the above, as `width` and `height` affect for the whole plot area." + "Setting `width` and `height` to the same values, notice how the plot below ends up much smaller than the one above, as `width` and `height` affect the whole plot area." ] }, { From c7ac0c2df0b6544395d213dbf6ae6fd6df8957b6 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Tue, 13 May 2025 17:12:20 +0100 Subject: [PATCH 09/10] update docstring --- hvplot/converter.py | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/hvplot/converter.py b/hvplot/converter.py index 55b25b327..5b92f83fd 100644 --- a/hvplot/converter.py +++ b/hvplot/converter.py @@ -227,16 +227,13 @@ class HoloViewsConverter: Size And Layout Options ----------------------- - aspect : str or float or None, default=None - The aspect ratio mode of the plot. By default, a plot may - select its own appropriate aspect ratio but sometimes it may - be necessary to force a square aspect ratio (e.g. to display - the plot as an element of a grid). The modes 'auto' and - 'equal' correspond to the axis modes of the same name in - matplotlib, a numeric value specifying the ratio between plot - width and height may also be passed. To control the aspect - ratio between the axis scales use the ``data_aspect`` option - instead. + aspect : float or {'equal', 'square'} or None, default=None + Sets the width-to-height ratio of the plot. When None (the default), + HoloViews chooses an appropriate aspect automatically. Use + 'equal' or 'square' to modify the unit ratio between axes, + or supply a numeric value (e.g. 2.0) for a custom ratio. + To control the scaling of individual axis units, use the + ``data_aspect`` option instead. data_aspect : float or None, default=None Defines the aspect of the axis scaling, i.e. the ratio of y-unit to x-unit. From 3b49191aec090833e0805733152b7eeb7801aef6 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Tue, 20 May 2025 09:48:58 +0100 Subject: [PATCH 10/10] post-review --- doc/ref/plotting_options/size_layout.ipynb | 42 ++++++++++++---------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/doc/ref/plotting_options/size_layout.ipynb b/doc/ref/plotting_options/size_layout.ipynb index 67b674ef5..8cc659943 100644 --- a/doc/ref/plotting_options/size_layout.ipynb +++ b/doc/ref/plotting_options/size_layout.ipynb @@ -21,22 +21,21 @@ "(option-aspect)=\n", "## `aspect`\n", "\n", - "The `aspect` option controls the **frame** shape by setting the ratio of its width to its height. By default (`aspect=None`), HoloViews chooses an appropriate ratio automatically. Use:\n", + "The `aspect` option controls the **frame** shape—that is, the rectangular drawing area that contains only the plotted data (excluding axes, labels, legends, and margins)—by setting the ratio of its width to its height. By default (`aspect=None`), HoloViews does not enforce any new ratio: it simply uses whatever `frame_height` and `frame_width` you’ve provided or falls back to its built-in defaults of 300 × 700 px if neither is set. \n", "\n", - "- `'square'` \n", - " Forces a square frame. \n", + "Use:\n", + "\n", + "- `'square'`: Forces a square frame. \n", " - If you set only `frame_width`, the height will be made equal to it. \n", " - If you set only `frame_height`, the width will be matched to it. \n", " - If you set both, the aspect value will be ignored with a warning displayed.\n", "\n", - "- `'equal'` \n", - " Ensures the frame maintains the default height to width ratios (300:700). \n", + "- `'equal'`: Ensures the frame maintains the default height to width ratios (300:700). \n", " - If you specify `frame_width` but omit `frame_height`, the height is re-computed to match the original ratios. \n", " - If you specify `frame_height` but omit `frame_width`, the width is re-computed to match the original ratios. \n", " - If you explicitly set both `frame_width` and `frame_height`, those values are respected and the aspect value ignored.\n", "\n", - "- A float, e.g. `2.0` \n", - " Directly sets the width : height ratio (so `aspect=2.0` makes it twice as wide as it is tall).\n", + "- A float, e.g. `2.0`: Directly sets the width : height ratio (so `aspect=2.0` makes it twice as wide as it is tall).\n", "\n", "If you need to control the **data-unit** scaling (so that one y-unit equals one x-unit), use the [`data_aspect`](option-data_aspect) option instead. \n", "\n", @@ -55,15 +54,17 @@ "\n", "df = hvsampledata.penguins(\"pandas\")\n", "\n", + "opts = dict(\n", + " x='bill_length_mm',\n", + " y='bill_depth_mm',\n", + " frame_width=200,\n", + ")\n", + "\n", "(\n", - " df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", - " frame_width=200, title=\"Default aspect\")\n", - " + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", - " frame_width=200, aspect=0.6, title=\"3:5 ratio\")\n", - " + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", - " frame_width=200, aspect='square', title=\"Square plot (1:1 ratio)\")\n", - " + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n", - " frame_width=200, aspect='equal', title=\"Re-computed frame_height\")\n", + " df.hvplot.scatter(aspect=None, title=\"Default aspect\", **opts)\n", + " + df.hvplot.scatter(aspect=0.6, title=\"3:5 ratio\", **opts)\n", + " + df.hvplot.scatter(aspect='square', title=\"Square plot (1:1 ratio)\", **opts)\n", + " + df.hvplot.scatter(aspect='equal', title=\"Re-computed frame_height\", **opts)\n", ").cols(2)" ] }, @@ -126,8 +127,10 @@ "import hvsampledata\n", "\n", "df = hvsampledata.penguins(\"pandas\")\n", - "df.hvplot.scatter(\"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n", - " frame_width=300, frame_height=200)" + "df.hvplot.scatter(\n", + " \"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n", + " frame_width=300, frame_height=200\n", + ")" ] }, { @@ -145,7 +148,10 @@ "metadata": {}, "outputs": [], "source": [ - "df.hvplot.scatter(\"bill_length_mm\", \"bill_depth_mm\", by=\"species\", width=300, height=200)" + "df.hvplot.scatter(\n", + " \"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n", + " width=300, height=200\n", + ")" ] }, {