Document the size and layout options #1545
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,372 @@ | ||
| { | ||
| "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—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", | ||
| "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'`: 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`: 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", | ||
| "opts = dict(\n", | ||
| " x='bill_length_mm',\n", | ||
| " y='bill_depth_mm',\n", | ||
| " frame_width=200,\n", | ||
| ")\n", | ||
| "\n", | ||
| "(\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)" | ||
| ] | ||
| }, | ||
| { | ||
| "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", | ||
| "\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", | ||
|
There was a problem hiding this comment. Interestingly HoloViews seems to align well plots in a layout by default, without having to set frame_width explicitly: There was a problem hiding this comment. I've updated the notebook with a different approach. 
|
||
| "\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(\n", | ||
| " \"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n", | ||
| " frame_width=300, frame_height=200\n", | ||
| ")" | ||
| ] | ||
| }, | ||
| { | ||
| "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(\n", | ||
| " \"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n", | ||
| " width=300, height=200\n", | ||
| ")" | ||
| ] | ||
| }, | ||
| { | ||
| "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 | ||
| } | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
AFAICT,
aspectanddata_aspectdo different things.aspectcontrols the shape of the plot i.e, ratio of frame_width to frame_height whiledata_aspectcontrols 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.