Improve documentation of Plot methods #1548

Azaya89 · 2025-04-17T12:28:57Z

This PR adds API reference examples to the following plot methods:

Azaya89 · 2025-04-17T15:55:10Z

The signature defs in the scatter plot method still needs to be updated I think, as well as adding some more examples to it.

maximlt · 2025-04-29T08:09:26Z

doc/ref/api/hvplot_api/hvplot.hvPlot.bar.ipynb

+    "\n",
+    "df = hvsampledata.penguins(\"pandas\")\n",
+    "\n",
+    "stacked_df = df.groupby(\"species\")[[\"bill_length_mm\", \"bill_depth_mm\"]].mean().reset_index()\n",


I don't think calling reset_index() is required?

maximlt · 2025-04-29T08:14:06Z

doc/ref/api/hvplot_api/hvplot.hvPlot.bar.ipynb

+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Simple vertical bar plot"


If possible, it'd be nice if the first example could be independent of hvsampledata (e.g. with dummy data generated with pandas/numpy), so users who don't have it installed have one chance to run this one easily.

maximlt · 2025-04-29T08:27:40Z

doc/ref/api/hvplot_api/hvplot.hvPlot.bar.ipynb

I think you can borrow a bit more from https://hvplot.holoviz.org/reference/tabular/bar.html:

multi-index

wide vs long data

I also like the short sentences that precede the plots.

maximlt · 2025-04-29T08:29:18Z

doc/ref/api/hvplot_api/hvplot.hvPlot.bar.ipynb

It would be nice to show at least in one cell the .head() of the penguins dataset. Also I think I'd be in favor of showing at least in one cell the content of stacked_df. Pandas users wouldn't struggle too much understanding the shape of this dataframe but it's still cognitive load we can avoid.

maximlt · 2025-04-29T08:30:45Z

doc/ref/api/hvplot_api/hvplot.hvPlot.scatter.ipynb

+    "df = hvsampledata.earthquakes(\"pandas\")\n",
    "\n",
-    "TBD"
+    "df.hvplot.scatter(\n",


It seems to me this is a bit of a too "complicated" example (tiles) for the first one on this page.

OK. Will change it.

maximlt · 2025-04-29T08:39:55Z

hvplot/plotting/core.py

            A color or a Field name to draw the color of the marker from
        s : int, optional, also available as 'size'
            The size of the marker
-        by : string, optional


I think these options were added by Marc when he improved all the docstrings. I understand why he did that, to make them available in VS Code when you use hvPlot as follows:

from hvplot import hvPlot hvPlot(df).scatter(...

It duplicates docstrings which isn't good. Removing them affects the UX in an IDE, which isn't good either. I'll open an issue to track this, I think we could define a subset of important options all methods should have (or have a way to declare which generic options a given method should be augmented with in its docstring), and have a pre-commit step that makes sure we don't have to manually duplicate docstrings.

Azaya89 · 2025-05-06T18:49:39Z

I just pushed 8878346 to reset this PR so i can figure out the directory tree much more easily. Still a WIP.

Azaya89 · 2025-05-26T17:55:28Z

doc/ref/api/manual/hvplot.hvPlot.area.ipynb

+    "    y=\"Apple\",\n",
+    "    y2=\"Microsoft\",\n",
+    "    alpha=0.4,\n",
+    "    line_color=\"#e87508\",\n",


It should be possible to set a different line_color for each individual line in the plot (y and y2) but right now it's not.

Azaya89 · 2025-06-12T16:55:57Z

doc/ref/api/manual/hvplot.hvPlot.contourf.ipynb

    "## Examples\n",
    "\n",
-    "TBD"
+    "### `Filled Contours for Temperature Regions`\n",


Why is there even a contourf element instead of just adding the filled paramater to the contour element?

I think that's why: https://docs.xarray.dev/en/latest/generated/xarray.plot.contourf.html

Azaya89 · 2025-06-12T16:58:27Z

doc/ref/api/manual/hvplot.hvPlot.dataset.ipynb

-   "id": "b27350ca",
   "metadata": {},
   "source": [
    "# hvPlot.dataset\n",


How many people actually use this element in real life? Is it necessary to continue maintaining it?

Probably very few. Might be good to ask Philipp for feedback.

maximlt

A while ago already I added some inline review comments. I've reviewed the documented notebooks, modified them a bit, and added the missing ones. This is good to go, thanks @Azaya89 !!!

maximlt · 2025-06-23T14:27:31Z

doc/conf.py

    'sphinxext.rediraffe',
    'numpydoc',
    'sphinxcontrib.mermaid',
+    'sphinx.ext.intersphinx',


Already added in nbsite.

maximlt · 2025-06-23T14:55:32Z

doc/ref/api/manual/hvplot.hvPlot.area.ipynb

+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### `Stacked Area for Multiple Series`\n",


I've removed the quotes in the headings.

maximlt · 2025-06-23T14:58:28Z

doc/ref/api/manual/hvplot.hvPlot.area.ipynb

+    "import hvplot.pandas # noqa\n",
+    "import hvsampledata\n",
+    "\n",
+    "df = hvsampledata.stocks(\"pandas\")\n",


Changed this example in favor of apple_stocks and display low/high prices area (I thought it was a more realistic use case).

maximlt · 2025-06-23T21:59:06Z

doc/ref/api/manual/hvplot.hvPlot.bar.ipynb

Reworked it a bit to use a dataset that makes a bit more sense when using stacked=True.

maximlt · 2025-06-28T07:46:43Z

doc/ref/api/manual/hvplot.hvPlot.contourf.ipynb

+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### `Combining contourf with Transparency`\n",


In general, in these pages the focus should be on documenting the plot-specific options, like levels in this case, which has no example on this page.

maximlt · 2025-06-28T22:44:17Z

doc/ref/api/manual/hvplot.hvPlot.hist.ipynb

+    "import numpy as np\n",
+    "\n",
+    "df = pd.DataFrame({'values': np.random.normal(loc=0, scale=1, size=1000)})\n",
+    "df.hvplot.hist(y='values', bin_range=(-1, 1), title='Histogram in Range -1 to 1') # Didn't work?"


Yep we broke it in https://github.com/holoviz/hvplot/pull/1523/files#diff-6fcc94abe23802d29dfb077516afd7d60aba62add0f905a6ada0884a3bd006b5R1418. Tracking this in #1623 (comment).

maximlt · 2025-06-28T22:55:57Z

doc/ref/api/manual/hvplot.hvPlot.hist.ipynb

+   "source": [
+    "### Basic Histogram with bins\n",
+    "\n",
+    "You can control the number of bins or specify bin edges."


In a reference document, we can add more examples that go beyond the simplest one.

maximlt · 2025-06-30T09:54:49Z

doc/ref/api/manual/hvplot.hvPlot.ohlc.ipynb

    ".. backend-styling-options:: ohlc\n",
    "```\n",
    "\n",
    "## Examples\n",


The gallery page (https://hvplot.holoviz.org/reference/tabular/ohlc.html) contains an example describing how neg_color, pos_color, line_color and bar_width can be used to control the plot display. These are keywords specific to this plot. I've documented them.

maximlt · 2025-06-30T10:56:29Z

doc/ref/api/manual/hvplot.hvPlot.paths.ipynb

    "## Examples\n",
    "\n",
-    "TBD"
+    "### `Lissajous Curve`\n",


Nice to have a non-geographic example but still I think that's likely to be the most common use case and why it was included in the reference gallery (https://hvplot.holoviz.org/reference/tabular/paths.html).

Azaya89 added 2 commits April 17, 2025 13:23

add bar examples

3c5f5ba

add barh examples

f1e67ee

Azaya89 assigned Azaya89 and maximlt Apr 17, 2025

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

Azaya89 added 2 commits April 17, 2025 16:50

add a scatter example

92c7757

remove redundant docstrings

b84b7bc

maximlt reviewed Apr 29, 2025

View reviewed changes

Azaya89 added 3 commits May 2, 2025 16:22

Merge branch 'main' into plot-methods

52d4f69

Merge branch 'main' into plot-methods

939cda7

re-write bar plot notebook

8878346

Azaya89 added 4 commits May 8, 2025 12:43

update barh

ec1be80

update scatter

c99b3b6

update hist

36ea65a

update heatmap

5375fd0

Azaya89 removed the NF SDG 2025 NumFocus Software Development Grant 2025 label May 9, 2025

Azaya89 added the NF SDG 2025 NumFocus Software Development Grant 2025 label May 16, 2025

Azaya89 added 5 commits May 26, 2025 12:42

Merge branch 'main' into plot-methods

6cb1450

update box example

09f879b

update labels example

4be71c8

update kde example

0384c67

update area example

64571a1

Azaya89 commented May 26, 2025

View reviewed changes

Azaya89 mentioned this pull request May 27, 2025

selectable=True on hv.Table enables row highlighting, but param.selection is not accessible holoviz/holoviews#6591

Open

Azaya89 added 4 commits May 27, 2025 20:03

Merge branch 'main' into plot-methods

3f4b251

make example self-contained

c7c4718

update ohlc example

0e3a3e1

update table example

3ca8383

Azaya89 added 14 commits June 5, 2025 15:56

Merge branch 'main' into plot-methods

7dd328d

Merge branch 'main' into plot-methods

a9f25e9

update violin example

1445535

update hexbin example

1c3b20f

update quadmesh example

bfcd009

update step example

77627ed

update bivariate example

2edef1a

update contour and contourf examples

bc67a5b

correct hexbin example

f3b8daa

update rgb example

8e25cf2

update paths example

a7b033f

update dataset example

054a329

resolve intersphinx mappings

c65893b

self review

46a0a6a

Azaya89 commented Jun 13, 2025

View reviewed changes

Azaya89 requested a review from maximlt June 13, 2025 16:47

maximlt added 4 commits July 28, 2025 22:18

updates

e4db8f6

Merge branch 'main' into plot-methods

0a67f1b

document more methods

4873b3a

remove bin_range passing

26656fe

maximlt marked this pull request as ready for review July 30, 2025 14:49

maximlt approved these changes Jul 30, 2025

View reviewed changes

maximlt merged commit 4deb1ae into main Jul 30, 2025
11 checks passed

maximlt deleted the plot-methods branch July 30, 2025 15:00

Uh oh!

Improve documentation of Plot methods #1548

Improve documentation of Plot methods #1548

Uh oh!

Conversation

Azaya89 commented Apr 17, 2025 • edited by maximlt Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Azaya89 commented Apr 17, 2025

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 May 6, 2025

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Azaya89 commented Apr 17, 2025 •

edited by maximlt

Loading