feat(python!): Use Altair in DataFrame.plot

py-polars/docs/source/reference/series/index.rst

@@ -20,7 +20,6 @@ This page gives an overview of all public Series methods.
    list
    modify_select
    miscellaneous
-   plot
    string
    struct
    temporal

py-polars/polars/dataframe/frame.py

@@ -66,6 +66,7 @@
 from polars._utils.wrap import wrap_expr, wrap_ldf, wrap_s
 from polars.dataframe._html import NotebookFormatter
 from polars.dataframe.group_by import DynamicGroupBy, GroupBy, RollingGroupBy
+from polars.dataframe.plotting import Plot
 from polars.datatypes import (
     N_INFER_DEFAULT,
     Boolean,
@@ -82,15 +83,15 @@
 )
 from polars.datatypes.group import INTEGER_DTYPES
 from polars.dependencies import (
+    _ALTAIR_AVAILABLE,
     _GREAT_TABLES_AVAILABLE,
-    _HVPLOT_AVAILABLE,
     _PANDAS_AVAILABLE,
     _PYARROW_AVAILABLE,
     _check_for_numpy,
     _check_for_pandas,
     _check_for_pyarrow,
+    altair,
     great_tables,
-    hvplot,
     import_optional,
 )
 from polars.dependencies import numpy as np
@@ -123,7 +124,6 @@
     import numpy.typing as npt
     import torch
     from great_tables import GT
-    from hvplot.plotting.core import hvPlotTabularPolars
     from xlsxwriter import Workbook
 
     from polars import DataType, Expr, LazyFrame, Series
@@ -603,17 +603,30 @@ def _replace(self, column: str, new_column: Series) -> DataFrame:
 
     @property
     @unstable()
-    def plot(self) -> hvPlotTabularPolars:
+    def plot(self) -> Plot:
         """
         Create a plot namespace.
 
         .. warning::
             This functionality is currently considered **unstable**. It may be
             changed at any point without it being considered a breaking change.
 
+        .. versionchanged:: 1.4.0
+            In prior versions of Polars, HvPlot was the plotting backend. If you would
+            like to restore the previous plotting functionality, all you need to do
+            add `import hvplot.polars` at the top of your script and replace
+            `df.plot` with `df.hvplot`.
+
         Polars does not implement plotting logic itself, but instead defers to
-        hvplot. Please see the `hvplot reference gallery <https://hvplot.holoviz.org/reference/index.html>`_
-        for more information and documentation.
+        Altair:
+
+        - `df.plot.line(*args, **kwargs)`
+          is shorthand for
+          `alt.Chart(df).mark_line().encode(*args, **kwargs).interactive()`
+        - `df.plot.point(*args, **kwargs)`
+          is shorthand for
+          `alt.Chart(df).mark_point().encode(*args, **kwargs).interactive()`
+        - ... (likewise, for any other attribute, e.g. `df.plot.bar`)
 
         Examples
         --------
@@ -626,32 +639,24 @@ def plot(self) -> hvPlotTabularPolars:
         ...         "species": ["setosa", "setosa", "versicolor"],
         ...     }
         ... )
-        >>> df.plot.scatter(x="length", y="width", by="species")  # doctest: +SKIP
+        >>> df.plot.point(x="length", y="width", color="species")  # doctest: +SKIP
 
         Line plot:
 
         >>> from datetime import date
         >>> df = pl.DataFrame(
         ...     {
-        ...         "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 4)],
-        ...         "stock_1": [1, 4, 6],
-        ...         "stock_2": [1, 5, 2],
+        ...         "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 4)] * 2,
+        ...         "price": [1, 4, 6, 1, 5, 2],
+        ...         "stock": ["a", "a", "a", "b", "b", "b"],
         ...     }
         ... )
-        >>> df.plot.line(x="date", y=["stock_1", "stock_2"])  # doctest: +SKIP
-
-        For more info on what you can pass, you can use ``hvplot.help``:
-
-        >>> import hvplot  # doctest: +SKIP
-        >>> hvplot.help("scatter")  # doctest: +SKIP
+        >>> df.plot.line(x="date", y="price", color="stock")  # doctest: +SKIP
         """
-        if not _HVPLOT_AVAILABLE or parse_version(hvplot.__version__) < parse_version(
-            "0.9.1"
-        ):
-            msg = "hvplot>=0.9.1 is required for `.plot`"
+        if not _ALTAIR_AVAILABLE or parse_version(altair.__version__) < (5, 3, 0):
+            msg = "altair>=5.3.0 is required for `.plot`"
             raise ModuleUpgradeRequiredError(msg)
-        hvplot.post_patch()
-        return hvplot.plotting.core.hvPlotTabularPolars(self)
+        return Plot(self)
 
     @property
     @unstable()

py-polars/polars/dataframe/plotting.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Mapping, Union
+
+if TYPE_CHECKING:
+    import sys
+
+    import altair as alt
+
+    from polars import DataFrame
+
+    if sys.version_info >= (3, 10):
+        from typing import TypeAlias
+    else:
+        from typing_extensions import TypeAlias
+
+    ChannelType: TypeAlias = Union[str, Mapping[str, Any], Any]
+
+
+class Plot:
+    """DataFrame.plot namespace."""
+
+    chart: alt.Chart
+
+    def __init__(self, df: DataFrame) -> None:
+        import altair as alt
+
+        self.chart = alt.Chart(df)
+
+    def bar(
+        self,
+        x: ChannelType | None = None,
+        y: ChannelType | None = None,
+        color: ChannelType | None = None,
+        tooltip: ChannelType | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> alt.Chart:
+        """
+        Draw bar plot.
+
+        Polars does not implement plottinng logic itself but instead defers to Altair.
+        `df.plot.bar(*args, **kwargs)` is shorthand for
+        `alt.Chart(df).mark_bar().encode(*args, **kwargs).interactive()`,
+        as is intended for convenience - for full customisatibility, use a plotting
+        library directly.
+
+        .. versionchanged:: 1.4.0
+            In prior versions of Polars, HvPlot was the plotting backend. If you would
+            like to restore the previous plotting functionality, all you need to do
+            add `import hvplot.polars` at the top of your script and replace
+            `df.plot` with `df.hvplot`.
+
+        Parameters
+        ----------
+        x
+            Column with x-coordinates of bars.
+        y
+            Column with y-coordinates of bars.
+        color
+            Column to color bars by.
+        tooltip
+            Columns to show values of when hovering over points with pointer.
+        *args, **kwargs
+            Additional arguments and keyword arguments passed to Altair.
+
+        Examples
+        --------
+        >>> from datetime import date
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 4)] * 2,
+        ...         "price": [1, 4, 6, 1, 5, 2],
+        ...         "stock": ["a", "a", "a", "b", "b", "b"],
+        ...     }
+        ... )
+        >>> df.plot.line(x="date", y="price", color="stock")  # doctest: +SKIP
+        """
+        encodings = {}
+        if x is not None:
+            encodings["x"] = x
+        if y is not None:
+            encodings["y"] = y
+        if color is not None:
+            encodings["color"] = color
+        if tooltip is not None:
+            encodings["tooltip"] = tooltip
+        return (
+            self.chart.mark_bar().encode(*args, **{**encodings, **kwargs}).interactive()
+        )
+
+    def line(
+        self,
+        x: ChannelType | None = None,
+        y: ChannelType | None = None,
+        color: ChannelType | None = None,
+        order: ChannelType | None = None,
+        tooltip: ChannelType | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> alt.Chart:
+        """
+        Draw line plot.
+
+        Polars does not implement plottinng logic itself but instead defers to Altair.
+        `df.plot.line(*args, **kwargs)` is shorthand for
+        `alt.Chart(df).mark_line().encode(*args, **kwargs).interactive()`,
+        as is intended for convenience - for full customisatibility, use a plotting
+        library directly.
+
+        .. versionchanged:: 1.4.0
+            In prior versions of Polars, HvPlot was the plotting backend. If you would
+            like to restore the previous plotting functionality, all you need to do
+            add `import hvplot.polars` at the top of your script and replace
+            `df.plot` with `df.hvplot`.
+
+        Parameters
+        ----------
+        x
+            Column with x-coordinates of lines.
+        y
+            Column with y-coordinates of lines.
+        color
+            Column to color lines by.
+        order
+            Column to use for order of data points in lines.
+        tooltip
+            Columns to show values of when hovering over points with pointer.
+        *args, **kwargs
+            Additional arguments and keyword arguments passed to Altair.
+
+        Examples
+        --------
+        >>> from datetime import date
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 4)] * 2,
+        ...         "price": [1, 4, 6, 1, 5, 2],
+        ...         "stock": ["a", "a", "a", "b", "b", "b"],
+        ...     }
+        ... )
+        >>> df.plot.line(x="date", y="price", color="stock")  # doctest: +SKIP
+        """
+        encodings = {}
+        if x is not None:
+            encodings["x"] = x
+        if y is not None:
+            encodings["y"] = y
+        if color is not None:
+            encodings["color"] = color
+        if order is not None:
+            encodings["order"] = order
+        if tooltip is not None:
+            encodings["tooltip"] = tooltip
+        return (
+            self.chart.mark_line()
+            .encode(*args, **{**encodings, **kwargs})
+            .interactive()
+        )
+
+    def point(
+        self,
+        x: ChannelType | None = None,
+        y: ChannelType | None = None,
+        color: ChannelType | None = None,
+        size: ChannelType | None = None,
+        tooltip: ChannelType | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> alt.Chart:
+        """
+        Draw scatter plot.
+
+        Polars does not implement plottinng logic itself but instead defers to Altair.
+        `df.plot.point(*args, **kwargs)` is shorthand for
+        `alt.Chart(df).mark_point().encode(*args, **kwargs).interactive()`,
+        as is intended for convenience - for full customisatibility, use a plotting
+        library directly.
+
+        .. versionchanged:: 1.4.0
+            In prior versions of Polars, HvPlot was the plotting backend. If you would
+            like to restore the previous plotting functionality, all you need to do
+            add `import hvplot.polars` at the top of your script and replace
+            `df.plot` with `df.hvplot`.
+
+        Parameters
+        ----------
+        x
+            Column with x-coordinates of points.
+        y
+            Column with y-coordinates of points.
+        color
+            Column to color points by.
+        size
+            Column which determines points' sizes.
+        tooltip
+            Columns to show values of when hovering over points with pointer.
+        *args, **kwargs
+            Additional arguments and keyword arguments passed to Altair.
+
+        Examples
+        --------
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "length": [1, 4, 6],
+        ...         "width": [4, 5, 6],
+        ...         "species": ["setosa", "setosa", "versicolor"],
+        ...     }
+        ... )
+        >>> df.plot.point(x="length", y="width", color="species")  # doctest: +SKIP
+        """
+        encodings = {}
+        if x is not None:
+            encodings["x"] = x
+        if y is not None:
+            encodings["y"] = y
+        if color is not None:
+            encodings["color"] = color
+        if size is not None:
+            encodings["size"] = size
+        if tooltip is not None:
+            encodings["tooltip"] = tooltip
+        return (
+            self.chart.mark_point()
+            .encode(*args, **{**encodings, **kwargs})
+            .interactive()
+        )
+
+    def __getattr__(
+        self, attr: str, *args: Any, **kwargs: Any
+    ) -> Callable[..., alt.Chart]:
+        method = self.chart.getattr(f"mark_{attr}", None)
+        if method is None:
+            msg = "Altair has no method 'mark_{attr}'"
+            raise AttributeError(msg)
+        return method().encode(*args, **kwargs).interactive()