assorted improvements

py-polars/polars/dataframe/plotting.py

@@ -62,7 +62,7 @@ def bar(
 
         `df.plot.bar(**kwargs)` is shorthand for
         `alt.Chart(df).mark_bar().encode(**kwargs).interactive()`,
-        as is intended for convenience - for full customisatibility, use a plotting
+        and is provided for convenience - for full customisatibility, use a plotting
         library directly.
 
         .. versionchanged:: 1.6.0
@@ -125,7 +125,7 @@ def line(
         `Altair <https://altair-viz.github.io/>`_.
 
         `alt.Chart(df).mark_line().encode(**kwargs).interactive()`,
-        as is intended for convenience - for full customisatibility, use a plotting
+        and is provided for convenience - for full customisatibility, use a plotting
         library directly.
 
         .. versionchanged:: 1.6.0
@@ -191,7 +191,7 @@ def point(
 
         `df.plot.point(**kwargs)` is shorthand for
         `alt.Chart(df).mark_point().encode(**kwargs).interactive()`,
-        as is intended for convenience - for full customisatibility, use a plotting
+        and is provided for convenience - for full customisatibility, use a plotting
         library directly.
 
         .. versionchanged:: 1.6.0

py-polars/polars/series/plotting.py

@@ -61,7 +61,7 @@ def hist(
 
         `s.plot.hist(**kwargs)` is shorthand for
         `alt.Chart(s.to_frame()).mark_bar().encode(x=alt.X(f'{s.name}:Q', bin=True), y='count()', **kwargs).interactive()`,
-        as is intended for convenience - for full customisatibility, use a plotting
+        and is provided for convenience - for full customisatibility, use a plotting
         library directly.
 
         .. versionchanged:: 1.6.0
@@ -103,7 +103,7 @@ def kde(
 
         `s.plot.kde(**kwargs)` is shorthand for
         `alt.Chart(s.to_frame()).transform_density(s.name, as_=[s.name, 'density']).mark_area().encode(x=s.name, y='density:Q', **kwargs).interactive()`,
-        as is intended for convenience - for full customisatibility, use a plotting
+        and is provided for convenience - for full customisatibility, use a plotting
         library directly.
 
         .. versionchanged:: 1.6.0
@@ -114,18 +114,8 @@ def kde(
 
         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 lines with pointer.
-        *args, **kwargs
-            Additional arguments and keyword arguments passed to Altair.
+        **kwargs
+            Additional keyword arguments passed to Altair.
 
         Examples
         --------
@@ -143,13 +133,56 @@ def kde(
             .interactive()
         )
 
+    def line(
+        self,
+        /,
+        **kwargs: Unpack[EncodeKwds],
+    ) -> alt.Chart:
+        """
+        Draw line plot.
+
+        Polars does not implement plotting logic itself but instead defers to
+        `Altair <https://altair-viz.github.io/>`_.
+
+        `s.plot.line(**kwargs)` is shorthand for
+        `alt.Chart(s.to_frame().with_row_index()).mark_line().encode(x='index', y=s.name, **kwargs).interactive()`,
+        and is provided for convenience - for full customisatibility, use a plotting
+        library directly.
+
+        .. versionchanged:: 1.6.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
+        ----------
+        **kwargs
+            Additional keyword arguments passed to Altair.
+
+        Examples
+        --------
+        >>> s = pl.Series("price", [1, 3, 3, 3, 5, 2, 6, 5, 5, 5, 7])
+        >>> s.plot.kde()  # doctest: +SKIP
+        """  # noqa: W505
+        if self._series_name == "index":
+            msg = "Cannot call `plot.line` when Series name is 'index'"
+            raise ValueError(msg)
+        return (
+            alt.Chart(self._df.with_row_index())
+            .mark_line()
+            .encode(x="index", y=self._series_name, **kwargs)  # type: ignore[misc]
+            .interactive()
+        )
+
     def __getattr__(self, attr: str) -> Callable[..., alt.Chart]:
-        if "index" in self._df.columns:
+        if self._series_name == "index":
             msg = "Cannot call `plot.{attr}` when Series name is 'index'"
             raise ValueError(msg)
-        method = getattr(
-            alt.Chart(self._df.with_row_index("index")), f"mark_{attr}", None
-        )
+        if attr == "scatter":
+            # alias `scatter` to `point` because of how common it is
+            attr = "point"
+        method = getattr(alt.Chart(self._df.with_row_index()), f"mark_{attr}", None)
         if method is None:
             msg = "Altair has no method 'mark_{attr}'"
             raise AttributeError(msg)

py-polars/tests/unit/operations/namespaces/test_plot.py

@@ -12,6 +12,7 @@ def test_dataframe_plot() -> None:
     )
     df.plot.line(x="length", y="width", color="species").to_json()
     df.plot.point(x="length", y="width", size="species").to_json()
+    df.plot.scatter(x="length", y="width", size="species").to_json()
     df.plot.bar(x="length", y="width", color="species").to_json()
     df.plot.area(x="length", y="width", color="species").to_json()
 
@@ -23,7 +24,6 @@ def test_series_plot() -> None:
     s.plot.hist().to_json()
     s.plot.line().to_json()
     s.plot.point().to_json()
-    s.plot.scatter().to_json()
 
 
 def test_empty_dataframe() -> None: