Document the size and layout options #1545

Azaya89 · 2025-04-14T11:05:29Z

This PR adds the Size and Layout options to the reference docs.

Copilot

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (1)

doc/ref/plot_options/size.ipynb:12

[nitpick] Consider standardizing the capitalization for consistency; the notebook header uses 'Size and Layout Options' while this directive uses 'Size And Layout Options'.

.. plotting-options-table:: Size And Layout Options

maximlt

A few quick questions on the options:

Should fontsize and fontscale be in the same option group?
Should aspect and data_aspect be in this size and layout group?

maximlt · 2025-04-29T00:25:02Z

doc/ref/plot_options/size.ipynb

+   "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."


Oh cool, I had never really thought about this (or forgot!). Like in HoloViews docs, it could be nice to show two plots with frame_height/width set, one without a legend or colorbar and one with, to see the inner plots have the same dimension.

maximlt · 2025-04-29T00:25:35Z

doc/ref/plot_options/size.ipynb

+    "import hvplot.xarray  # noqa\n",
+    "import hvsampledata\n",
+    "\n",
+    "df = hvsampledata.air_temperature(\"xarray\")\n",


Pick just one timestamp to avoid the non-interactive widgets.

maximlt · 2025-04-29T00:26:05Z

doc/ref/plot_options/size.ipynb

+    "import hvplot.xarray  # noqa\n",
+    "import hvsampledata\n",
+    "\n",
+    "df = hvsampledata.air_temperature(\"xarray\")\n",


Pick just one timestamp to avoid the non-interactive widgets.

maximlt · 2025-04-29T00:26:39Z

doc/ref/plot_options/size.ipynb

+    "import hvplot.xarray  # noqa\n",
+    "import hvsampledata\n",
+    "\n",
+    "df = hvsampledata.air_temperature(\"xarray\")\n",


Pick just one timestamp to avoid the non-interactive widgets.

maximlt · 2025-04-29T00:34:17Z

doc/ref/plot_options/size.ipynb

+   "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."


I'm not sure it's a good idea to set tiles=True in this example (the axes are distributed differently). Might be best to use a simpler dummy and more geometric dataset in this case.

Something like this maybe:

import pandas as pd df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]}) df.hvplot.scatter(x='x', y='y', padding=(0.5, 0.1))

maximlt · 2025-04-29T00:36:38Z

doc/ref/plot_options/size.ipynb

Should the file be named size_and_layout?

Seems unnecessarily long IMO.

How about size_layout? More descriptive URL helps with SEO I think.

Azaya89 · 2025-04-30T14:56:47Z

Should fontsize and fontscale be in the same option group?

Yeah, I think so. I'll move fontscale to Styling Options then.

Should aspect and data_aspect be in this size and layout group?

Hmm, I think so.

Copilot

Pull Request Overview

This PR documents the new Size and Layout options for plots and updates internal option categorizations accordingly.

Introduces the new options “aspect” and “data_aspect” with detailed documentation.
Reassigns the “fontscale” option from the Size and Layout section to the Axis Options.
Updates the documentation index and adds a new notebook detailing these changes.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
hvplot/converter.py	Updates docstrings and internal option lists to reclassify axis and size/layout options.
doc/ref/plotting_options/size_layout.ipynb	Adds a comprehensive notebook demonstrating the new size and layout options.
doc/ref/plotting_options/index.md	Links the new size/layout documentation for easier navigation.

Comments suppressed due to low confidence (1)

hvplot/converter.py:378

Since 'fontscale' has been reclassified to the Axis Options, ensure the accompanying documentation consistently reflects its new categorization and rationale for the change.

    fontscale : number

hvplot/converter.py

@@ -511,7 +511,8 @@ class HoloViewsConverter:
    ]



maximlt

I've pushed a few minor changes and left some comments that are mostly about aspect.

maximlt · 2025-05-13T11:51:56Z

doc/ref/plotting_options/size_layout.ipynb

+    "\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",


I tried setting aspect='auto' and got an error. It's important that we try the options we document to make sure they work and do what we expect.

File [~/dev/hvplot/.pixi/envs/docs/lib/python3.11/site-packages/holoviews/plotting/plot.py:1376](http://localhost:8889/lab/workspaces/auto-h/tree/~/dev/hvplot/.pixi/envs/docs/lib/python3.11/site-packages/holoviews/plotting/plot.py#line=1375), in GenericElementPlot.get_padding(self, obj, extents) 1374 yspan = y1-y0 if util.is_number(y0) and util.is_number(y1) else None 1375 aspect = self.get_aspect(xspan, yspan) -> 1376 if aspect > 1: 1377 xpad = tuple(xp[/](http://localhost:8889/aspect)[aspect](http://localhost:8889/aspect) for xp in xpad) if isinstance(xpad, tuple) else xpad[/](http://localhost:8889/aspect)[aspect](http://localhost:8889/aspect) 1378 else: TypeError: '>' not supported between instances of 'str' and 'int'

maximlt · 2025-05-13T12:10:08Z

doc/ref/plotting_options/size_layout.ipynb

+    "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",


What do you mean with for square plots?

In fact, I tried passing down aspect='square' and that worked too.

Maybe in a case like that where the argument accepts a few values, it's good to show them all. Let me know what you think.

( df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', frame_width=200) + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', frame_width=200, aspect=0.6) + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', frame_width=200, aspect='square') + df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', frame_width=200, aspect='equal') ).cols(2)

This is a better example. I've used it in the notebook instead of the former one.

maximlt · 2025-05-13T12:48:02Z

doc/ref/plotting_options/size_layout.ipynb

+   "id": "c99dceda-b76f-450a-90ac-06735a1b001c",
+   "metadata": {},
+   "source": [
+    "## `frame_width / frame_height`\n",


Interestingly HoloViews seems to align well plots in a layout by default, without having to set frame_width explicitly:

I've updated the notebook with a different approach.

maximlt · 2025-05-13T12:52:14Z

doc/ref/plotting_options/size_layout.ipynb

+   "id": "de030cee-46a2-4d8d-b12a-e685bd616e27",
+   "metadata": {},
+   "source": [
+    "## `data_aspect`\n",


It'd be nice to write which option takes precedence between aspect and data_aspect.

AFAICT, aspect and data_aspect do different things. aspect controls the shape of the plot i.e, ratio of frame_width to frame_height while data_aspect controls the scaling of the data units i.e, ratio of the unit on the x-axis to the unit on the y-axis.

I've modified the documentation to be more explanatory.

doc/ref/plotting_options/size_layout.ipynb

maximlt · 2025-05-19T16:29:18Z

doc/ref/plotting_options/size_layout.ipynb

+    "(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",


To understand, what do you mean with HoloViews choosing an appropriate ratio automatically?

It means the ratio used is either the default or the specified frame width/height. I think I'll have to rewrite that as it is a bit vague.

doc/ref/plotting_options/size_layout.ipynb

add size and layout options notebook

f23fb02

Azaya89 self-assigned this Apr 14, 2025

Azaya89 added the NF SDG 2025 NumFocus Software Development Grant 2025 label Apr 14, 2025

Azaya89 requested a review from Copilot April 14, 2025 11:22

Copilot AI reviewed Apr 14, 2025

View reviewed changes

maximlt reviewed Apr 29, 2025

View reviewed changes

Azaya89 added 2 commits April 29, 2025 19:29

Merge branch 'main' into size-op

6f9db86

rename notebook

719bb19

Azaya89 added 5 commits April 30, 2025 17:31

Merge branch 'main' into size-op

d1c302f

move 'fontscale' to styling options

f5e10a2

delete redundant dir

6b1ea5f

move aspect and data aspect to size_layout options

75c1386

update notebook

6f94f29

Azaya89 requested a review from Copilot April 30, 2025 18:43

Copilot AI reviewed Apr 30, 2025

View reviewed changes

hvplot/converter.py

@@ -511,7 +511,8 @@ class HoloViewsConverter:

]

This comment was marked as resolved.

Sign in to view

various minor updates

d8f576c

maximlt reviewed May 13, 2025

View reviewed changes

Azaya89 added 2 commits May 13, 2025 17:11

update notebook

2a0eb32

update docstring

c7ac0c2

Azaya89 requested a review from maximlt May 19, 2025 11:49

maximlt requested changes May 19, 2025

View reviewed changes

Azaya89 added 2 commits May 20, 2025 09:23

Merge branch 'main' into size-op

3394f15

post-review

3b49191

maximlt approved these changes May 21, 2025

View reviewed changes

maximlt merged commit 7ef626b into holoviz:main May 21, 2025
11 checks passed

Uh oh!

Document the size and layout options #1545

Document the size and layout options #1545

Uh oh!

Conversation

Azaya89 commented Apr 14, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

maximlt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Azaya89 commented Apr 30, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

This comment was marked as resolved.

Uh oh!

maximlt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!