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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document the size and layout options #1545

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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/plot_options/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -59,4 +61,5 @@ See [this page](./data) for more information on these options.

All Options <self>
Data Options <data>
Size and Layout Options <size>
```
262 changes: 262 additions & 0 deletions doc/ref/plot_options/size.ipynb
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

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

Should the file be named size_and_layout?

Original file line number Diff line number Diff line change
@@ -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."
Copy link
Member

Choose a reason for hiding this comment

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

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.

]
},
{
"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",
Copy link
Member

Choose a reason for hiding this comment

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

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

"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",
Copy link
Member

Choose a reason for hiding this comment

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

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

"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",
Copy link
Member

Choose a reason for hiding this comment

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

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

"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."
Copy link
Member

Choose a reason for hiding this comment

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

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))

image

]
},
{
"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
}
Loading