DOCSEARCHbyAlgolia
Submit Docs

hvPlot Documentation

repository·main·Indexed 23 days ago

https://github.com/holoviz/hvplot

A high-level plotting API for the PyData ecosystem built on HoloViews. hvPlot provides a familiar interface similar to Pandas .plot and supports data sources including Pandas, Polars, XArray, Dask, and GeoPandas, with backends such as Bokeh, Matplotlib, and Plotly. It includes features for creating interactive data apps via .interactive() and supports various chart types including line, scatter, bar, area, box, and heatmaps.

Tokens
111.6K
Snippets
358
Records
532
Agent score
78%

What's inside hvPlot

  1. Overview of hvPlot capabilities and data types

    main

    hvPlot is a high-level plotting API designed for data exploration, reporting, and building interactive data applications. It integrates with popular data analysis libraries and supports various data structures and visualization backends.

    Supported Data Types:

    • Tabular Data: Standard plotting for dataframes.
    • Gridded Data: Specialized support for Xarray-based gridded datasets.
    • Network Graphs: Integration with NetworkX for graph visualization.
    • Geographic Data: Support for spatial data using GeoViews, Cartopy, GeoPandas, and spatialpandas.
    • Timeseries Data: Optimized plotting for time-based datasets, including handling for large-scale timeseries.
    • Statistical Plots: Specialized plot types modeled after the pandas.plotting module.

    Key Features:

    • Interactive Exploration: Use widgets in place of constant arguments to create interactive analysis pipelines.
    • Custom Interactivity: Add and customize UI elements using Panel widgets.
    • Multiple Backends: Switch between different plotting engines like Bokeh, Matplotlib, and Plotly.
    • Subplots: Generate complex grids and subplots from your data.
    • Viewing Options: Display and save plots in notebooks, via the command line, or from scripts.

  2. Upcoming features in hvPlot 1.0 and beyond

    main

    The hvPlot roadmap outlines several key development goals aimed at improving stability, documentation, and feature completeness.

    Planned for hvPlot 1.0:

    • Enhanced Documentation: Transitioning user guides into structured How-To guides, Tutorials, and Explanation pages, alongside a new Reference section for plotting options.
    • Test Suite Refactor: Improving the test suite to catch regressions and bugs more effectively.
    • Donut and Pie Charts: Adding donut and pie methods to hvPlot (implemented via HoloViews).
    • Native DataFrame Support: Leveraging Narwhals (via HoloViews) to provide native support for libraries like Polars without requiring upfront casting to Pandas.

    Post-1.0 Goals:

    • .interactive API Evolution: Evaluating whether to deprecate or update the .interactive() API to align with Param 2.0's reactive expressions.
    • Explorer Improvements: Enhancing the Explorer's UX and integration to support all hvPlot data types and serve as a tool for API exploration.

  3. Understand generic vs. specific plotting options

    main

    hvPlot options are categorized into two main groups:

    1. Generic Options: These are available to almost all plot types (e.g., hvplot.hvPlot.scatter, hvplot.hvPlot.line) regardless of the backend (Bokeh, Matplotlib, etc.). They cover fundamental aspects like data organization, axis scaling, and layout.
    2. Specific Options: These depend on the specific plot type (e.g., marker for scatter plots) or the specific plotting backend (e.g., line_width for Bokeh).

    Generic options are documented in the main plotting options reference, while specific options are found on the reference page for that particular plotting method.

  4. Understand hvPlot data source accessors

    main

    hvPlot uses different internal classes to handle different data source types. Tabular-like sources use hvPlotTabular, while gridded-like sources use hvPlot (a subclass of hvPlotTabular with extra methods like .image()).

    Supported mappings:

    • hvPlotTabular: cuDF, Dask, Fugue, Ibis, Pandas
    • hvPlotTabularDuckDB: DuckDB
    • hvPlotTabularPolars: Polars
    • hvPlot: Xarray

  5. How to layout and overlay hvPlot figures

    main

    hvPlot integrates with the HoloViz ecosystem (specifically HoloViews) to allow for easy composition of plots:

    • Layout: Use the + operator to arrange multiple plots in a layout (e.g., side-by-side or stacked).
    • Overlay: Use the * operator to overlay one plot on top of another.

    Example of overlaying a scatter plot with error bars:

    import hvplot.pandas
import pandas
from bokeh.sampledata.penguins import data

df = data.groupby('species')['bill_length_mm'].describe().sort_values('mean')
df.hvplot.scatter(y='mean') * df.hvplot.errorbars(y='mean', yerr1='std')

  8. Switch between Bokeh, Matplotlib, and Plotly backends

    main

    By default, hvPlot uses Bokeh for interactive plots. You can switch to Matplotlib or Plotly by using the hvplot.extension() method. This allows you to use the same .hvplot() API while changing the underlying rendering engine.

    import hvplot.pandas
from bokeh.sampledata.penguins import data as df

# Use Bokeh (default)
df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', by='species')

# Use Matplotlib
hvplot.extension('matplotlib')
df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', by='species')

# Use Plotly
hvplot.extension('plotly')
df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', by='species')

  9. Use the hvPlot accessor for plotting

    main

    The most common way to use hvPlot is by installing the hvplot namespace on a data source via a special import. This enables the .hvplot accessor on compatible data objects (like Pandas DataFrames). Alternatively, you can use the hvPlot() function to wrap a data source and call plotting methods directly.

    import pandas as pd
import hvplot.pandas  # noqa
df = pd.DataFrame()

# Using the accessor
df.hvplot.scatter()
# or
df.hvplot(kind='scatter')

# Using the hvPlot function directly
from hvplot import hvPlot
hvPlot(df).scatter()
# or
hvPlot(df)(kind='scatter')

  10. Use the hvPlot Explorer interface

    main
    The Explorer interface provides an interactive way to explore data. It can be accessed via the .explorer method on the hvPlot namespace or via the top-level explorer function from hvplot.ui. Calling it returns an hvPlotExplorer object.

  11. Install hvPlot via conda, mamba, or pixi

    main

    hvPlot is available on several Anaconda channels. For stable releases, it is recommended to use conda-forge or defaults. Pre-releases are only available via the pyviz/label/dev subchannel.

    You can use conda, pixi, mamba, or micromamba to perform these installations.

  12. Set up the hvPlot development environment

    main

    To start developing hvPlot, you need to fork and clone the repository, install Pixi, and then initialize your environment. Running the setup-dev task creates a default environment, installs hvPlot in editable mode, downloads test datasets, and installs pre-commit.

    git clone https://github.com/<Your Username Here>/hvplot
cd hvplot
pixi run setup-dev