Skip to content

Document the size and layout options #1545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
May 21, 2025
Merged

Document the size and layout options #1545

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
f23fb02
add size and layout options notebook
Azaya89 Apr 14, 2025
6f9db86
Merge branch 'main' into size-op
Azaya89 Apr 29, 2025
719bb19
rename notebook
Azaya89 Apr 30, 2025
d1c302f
Merge branch 'main' into size-op
Azaya89 Apr 30, 2025
f5e10a2
move 'fontscale' to styling options
Azaya89 Apr 30, 2025
6b1ea5f
delete redundant dir
Azaya89 Apr 30, 2025
75c1386
move aspect and data aspect to size_layout options
Azaya89 Apr 30, 2025
6f94f29
update notebook
Azaya89 Apr 30, 2025
d8f576c
various minor updates
maximlt May 13, 2025
2a0eb32
update notebook
Azaya89 May 13, 2025
c7ac0c2
update docstring
Azaya89 May 13, 2025
3394f15
Merge branch 'main' into size-op
Azaya89 May 20, 2025
3b49191
post-review
Azaya89 May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions doc/ref/plotting_options/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -103,4 +105,5 @@ Options for handling live data streams:

All Options <self>
Data Options <data>
Size And Layout Options <size_layout>
```
366 changes: 366 additions & 0 deletions doc/ref/plotting_options/size_layout.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,366 @@
{
"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": "c20d146d-c67f-40be-b505-edadc4e94bd7",
"metadata": {},
"source": [
"(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",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

"\n",
"- `'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. "
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "fe824752-06d2-43f3-aa49-770a118c2222",
"metadata": {},
"outputs": [],
"source": [
"import hvplot.pandas # noqa\n",
"import hvsampledata\n",
"\n",
"df = hvsampledata.penguins(\"pandas\")\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",
").cols(2)"
]
},
{
"cell_type": "markdown",
"id": "24837128-7483-4a70-9fa0-011dc1d73606",
"metadata": {},
"source": [
":::{seealso}\n",
"[`frame_width/frame_height`](option-frame_width__frame_height)"
]
},
{
"cell_type": "markdown",
"id": "de030cee-46a2-4d8d-b12a-e685bd616e27",
"metadata": {},
"source": [
"(option-data_aspect)=\n",
"## `data_aspect`\n",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

"\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`](option-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)"
]
},
{
"cell_type": "markdown",
"id": "c99dceda-b76f-450a-90ac-06735a1b001c",
"metadata": {},
"source": [
"(option-frame_width__frame_height)=\n",
"## `frame_width / frame_height`\n",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the notebook with a different approach.

image

"\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": "de201f6b-0f7c-431a-8141-b86828068548",
"metadata": {},
"outputs": [],
"source": [
"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)"
]
},
{
"cell_type": "markdown",
"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 one above, as `width` and `height` affect the whole plot area."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7254e255-2232-4f0b-a9be-d7520aed2821",
"metadata": {},
"outputs": [],
"source": [
"df.hvplot.scatter(\"bill_length_mm\", \"bill_depth_mm\", by=\"species\", width=300, height=200)"
]
},
{
"cell_type": "markdown",
"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."
]
},
{
"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\").sel(time=\"2014-02-25 12:00\")\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": "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`](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."
]
},
{
"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\").sel(time=\"2014-02-25 12:00\")\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": "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."
]
},
{
"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\").sel(time=\"2014-02-25 12:00\")\n",
"df.hvplot.image(height=300, width=600)"
]
},
{
"cell_type": "markdown",
"id": "71fda055-de30-4d01-b2b3-3c0887403f7e",
"metadata": {},
"source": [
"(option-width)=\n",
"## `width`\n",
"\n",
"See [`height`](option-height) option above."
]
},
{
"cell_type": "markdown",
"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."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4371a176-ef4e-483c-a7e3-5cfb77c5d51f",
"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% extra space around the auto-determined axis ranges\n",
"df.hvplot.scatter(x='x', y='y', padding=0.2, height=200)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "091b16fc-608a-46ac-8c55-154bf9989871",
"metadata": {},
"outputs": [],
"source": [
"# 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)"
]
},
{
"cell_type": "markdown",
"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."
]
},
{
"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(\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",
":::"
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
Loading
Loading