Skip to content
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.

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

Improve the experience of users coming from Pandas #1488

Open
maximlt opened this issue Feb 5, 2025 · 1 comment
Open

Improve the experience of users coming from Pandas #1488

maximlt opened this issue Feb 5, 2025 · 1 comment
Assignees

Comments

@maximlt
Copy link
Member

maximlt commented Feb 5, 2025

Pandas users are likely to be an important fraction of hvPlot users and are probably already used to the Pandas .plot API, having built some expectations on how it is supposed to work. I suggest we try to better document how these users can migrate to hvPlot's API.

Here are some of the key bits I wish were documented explicitly:

  • Getting started/entry point for Pandas users specifically
  • Enabling hvPlot via setting the Pandas plotting backend or hvplot.pandas import with pros and cons (see Orient Pandas users more towards .plot or .hvplot? #1485 for a more extended discussion)
  • Supported plot methods (e.g. pie not available in hvPlot)
  • Important API differences. For example, hvPlot has no figsize but width/height, no ax but +/* for composability (see

    hvplot/hvplot/converter.py

    Lines 1550 to 1566 in d2bce93

    if 'ax' in mismatches:
    mismatches.pop(mismatches.index('ax'))
    param.main.param.warning(
    'hvPlot does not have the concept of axes, '
    'and the ax keyword will be ignored. Compose '
    'plots with the * operator to overlay plots or the '
    '+ operator to lay out plots beside each other '
    'instead.'
    )
    if 'figsize' in mismatches:
    mismatches.pop(mismatches.index('figsize'))
    param.main.param.warning(
    'hvPlot does not have the concept of a figure, '
    'and the figsize keyword will be ignored. The '
    'size of each subplot in a layout is set '
    'individually using the width and height options.'
    )
    ). There are for sure more important differences to document.
  • Important Pandas features not yet available in hvPlot's API but via HoloViews directly (e.g. dual axis)
  • Saving a plot

The website currently has the Pandas API guide that is a slightly modified and extended version of the Pandas Visualization Guide. I quite like the concept of this page, trying to replicate Pandas' docs using hvPlot directly (serving both as a test for us and as "migration/compatibility" guide for users. @Azaya89 has opened #1482 to update it based on the latest changes in Pandas docs.

@Azaya89, based on my suggestions above, can you brainstorm and suggest how this content should be organized based on the Diataxis framework (tutorial/how-to/reference/explanation)?

@maximlt maximlt added NF SDG 2025 NumFocus Software Development Grant 2025 type: docs labels Feb 5, 2025
@maximlt maximlt removed the NF SDG 2025 NumFocus Software Development Grant 2025 label Feb 5, 2025
@maximlt maximlt changed the title doc: improve the experience of users coming from Pandas Improve the experience of users coming from Pandas Feb 5, 2025
@maximlt
Copy link
Member Author

maximlt commented Feb 5, 2025

A small thing; Pandas' users calling .plot in a Jupyter notebook got used to add ; to their call to hide the not-very-useful Matplotlib repr:

Image

When migrating to hvPlot, users should remove ending ; as that would completely hide the hvplot output.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: In Progress
Development

No branches or pull requests

2 participants