Add LineCollection plot

doc/api-hidden.rst

@@ -391,6 +391,7 @@
    plot.imshow
    plot.pcolormesh
    plot.scatter
+   plot.lines
    plot.surface
 
    CFTimeIndex.all

doc/api.rst

@@ -684,6 +684,7 @@ Dataset
    :template: autosummary/accessor_method.rst
 
    Dataset.plot.scatter
+   Dataset.plot.lines
    Dataset.plot.quiver
    Dataset.plot.streamplot
 
@@ -708,6 +709,7 @@ DataArray
    DataArray.plot.pcolormesh
    DataArray.plot.step
    DataArray.plot.scatter
+   DataArray.plot.lines
    DataArray.plot.surface
 
 

doc/user-guide/plotting.rst

@@ -847,6 +847,75 @@ And adding the z-axis
 For more advanced scatter plots, we recommend converting the relevant data variables
 to a pandas DataFrame and using the extensive plotting capabilities of ``seaborn``.
 
+Lines
+~~~~~
+
+.. ipython:: python
+    :suppress:
+
+    plt.close("all")
+
+:py:func:`xarray.plot.lines` calls matplotlib.collections.LineCollection under the hood,
+allowing multiple lines being drawn efficiently. It uses similar arguments as
+:py:func:`xarray.plot.scatter`.
+
+Let's return to the air temperature dataset:
+
+.. ipython:: python
+    :okwarning:
+
+    airtemps = xr.tutorial.open_dataset("air_temperature")
+    air = airtemps.air - 273.15
+    air.attrs = airtemps.air.attrs
+    air.attrs["units"] = "deg C"
+
+    @savefig lines_air_hue.png
+    air.isel(lon=10).plot.lines(x="time", hue="lat")
+
+Make it a little more transparent:
+
+.. ipython:: python
+    :okwarning:
+
+    @savefig lines_air_hue_alpha.png
+    air.isel(lon=10).plot.lines(x="time", hue="lat", alpha=0.2)
+
+Zoom in a little on the x-axis, and compare a few latitudes and longitudes,
+group them using ``hue`` and ``linewidth``. The  ``linewidth`` kwarg works in
+a similar way as ``markersize`` kwarg for scatter plots, it lets you vary the
+line's size by variable value.
+
+.. ipython:: python
+    :okwarning:
+
+    air_zoom = air.isel(time=slice(1200, 1500), lat=[5, 10, 15], lon=[10, 15])
+
+    @savefig lines_hue_linewidth.png
+    air_zoom.plot.lines(x="time", hue="lat", linewidth="lon", add_colorbar=False)
+
+Lines can modify the linestyle but does not allow markers. Instead combine :py:func:`xarray.plot.lines`
+with :py:func:`xarray.plot.scatter`:
+
+.. ipython:: python
+    :okwarning:
+
+    air.isel(lat=10, lon=10)[:200].plot.lines(x="time", color="k", linestyle="dashed")
+    air.isel(lat=10, lon=10)[:200].plot.scatter(x="time", color="k", marker="^")
+    @savefig lines_linestyle_marker.png
+    plt.draw()
+
+
+Switching to another dataset with more variables we can analyse in similar
+fashion as :py:func:`xarray.plot.scatter`:
+
+.. ipython:: python
+    :okwarning:
+
+    ds = xr.tutorial.scatter_example_dataset(seed=42)
+
+    @savefig lines_xyhuewidthrowcol.png
+    ds.plot.lines(x="A", y="B", hue="y", linewidth="x", row="x", col="w")
+
 Quiver
 ~~~~~~
 

xarray/plot/__init__.py

@@ -13,6 +13,7 @@
     hist,
     imshow,
     line,
+    lines,
     pcolormesh,
     plot,
     step,
@@ -32,5 +33,6 @@
     "pcolormesh",
     "FacetGrid",
     "scatter",
+    "lines",
     "surface",
 ]

xarray/plot/accessor.py

@@ -135,6 +135,130 @@ def line(
     def line(self, *args, **kwargs) -> list[Line3D] | FacetGrid[DataArray]:
         return dataarray_plot.line(self._da, *args, **kwargs)
 
+    @overload
+    def lines(  # type: ignore[misc,unused-ignore]  # None is hashable :(
+        self,
+        *args: Any,
+        x: Hashable | None = None,
+        y: Hashable | None = None,
+        z: Hashable | None = None,
+        hue: Hashable | None = None,
+        hue_style: HueStyleOptions = None,
+        markersize: Hashable | None = None,
+        linewidth: Hashable | None = None,
+        figsize: Iterable[float] | None = None,
+        size: float | None = None,
+        aspect: float | None = None,
+        ax: Axes | None = None,
+        row: None = None,  # no wrap -> primitive
+        col: None = None,  # no wrap -> primitive
+        col_wrap: int | None = None,
+        xincrease: bool | None = True,
+        yincrease: bool | None = True,
+        add_legend: bool | None = None,
+        add_colorbar: bool | None = None,
+        add_labels: bool | Iterable[bool] = True,
+        add_title: bool = True,
+        subplot_kws: dict[str, Any] | None = None,
+        xscale: ScaleOptions = None,
+        yscale: ScaleOptions = None,
+        xticks: ArrayLike | None = None,
+        yticks: ArrayLike | None = None,
+        xlim: ArrayLike | None = None,
+        ylim: ArrayLike | None = None,
+        cmap=None,
+        vmin: float | None = None,
+        vmax: float | None = None,
+        norm: Normalize | None = None,
+        extend=None,
+        levels=None,
+        **kwargs: Any,
+    ) -> LineCollection: ...
+
+    @overload
+    def lines(
+        self,
+        *args: Any,
+        x: Hashable | None = None,
+        y: Hashable | None = None,
+        z: Hashable | None = None,
+        hue: Hashable | None = None,
+        hue_style: HueStyleOptions = None,
+        markersize: Hashable | None = None,
+        linewidth: Hashable | None = None,
+        figsize: Iterable[float] | None = None,
+        size: float | None = None,
+        aspect: float | None = None,
+        ax: Axes | None = None,
+        row: Hashable | None = None,
+        col: Hashable,  # wrap -> FacetGrid
+        col_wrap: int | None = None,
+        xincrease: bool | None = True,
+        yincrease: bool | None = True,
+        add_legend: bool | None = None,
+        add_colorbar: bool | None = None,
+        add_labels: bool | Iterable[bool] = True,
+        add_title: bool = True,
+        subplot_kws: dict[str, Any] | None = None,
+        xscale: ScaleOptions = None,
+        yscale: ScaleOptions = None,
+        xticks: ArrayLike | None = None,
+        yticks: ArrayLike | None = None,
+        xlim: ArrayLike | None = None,
+        ylim: ArrayLike | None = None,
+        cmap=None,
+        vmin: float | None = None,
+        vmax: float | None = None,
+        norm: Normalize | None = None,
+        extend=None,
+        levels=None,
+        **kwargs: Any,
+    ) -> FacetGrid[DataArray]: ...
+
+    @overload
+    def lines(
+        self,
+        *args: Any,
+        x: Hashable | None = None,
+        y: Hashable | None = None,
+        z: Hashable | None = None,
+        hue: Hashable | None = None,
+        hue_style: HueStyleOptions = None,
+        markersize: Hashable | None = None,
+        linewidth: Hashable | None = None,
+        figsize: Iterable[float] | None = None,
+        size: float | None = None,
+        aspect: float | None = None,
+        ax: Axes | None = None,
+        row: Hashable,  # wrap -> FacetGrid
+        col: Hashable | None = None,
+        col_wrap: int | None = None,
+        xincrease: bool | None = True,
+        yincrease: bool | None = True,
+        add_legend: bool | None = None,
+        add_colorbar: bool | None = None,
+        add_labels: bool | Iterable[bool] = True,
+        add_title: bool = True,
+        subplot_kws: dict[str, Any] | None = None,
+        xscale: ScaleOptions = None,
+        yscale: ScaleOptions = None,
+        xticks: ArrayLike | None = None,
+        yticks: ArrayLike | None = None,
+        xlim: ArrayLike | None = None,
+        ylim: ArrayLike | None = None,
+        cmap=None,
+        vmin: float | None = None,
+        vmax: float | None = None,
+        norm: Normalize | None = None,
+        extend=None,
+        levels=None,
+        **kwargs: Any,
+    ) -> FacetGrid[DataArray]: ...
+
+    @functools.wraps(dataarray_plot.lines)
+    def lines(self, *args, **kwargs) -> LineCollection | FacetGrid[DataArray]:
+        return dataarray_plot.lines(self._da, *args, **kwargs)
+
     @overload
     def step(  # type: ignore[misc,unused-ignore]  # None is hashable :(
         self,
@@ -923,6 +1047,130 @@ def __call__(self, *args, **kwargs) -> NoReturn:
             "an explicit plot method, e.g. ds.plot.scatter(...)"
         )
 
+    @overload
+    def lines(  # type: ignore[misc,unused-ignore]  # None is hashable :(
+        self,
+        *args: Any,
+        x: Hashable | None = None,
+        y: Hashable | None = None,
+        z: Hashable | None = None,
+        hue: Hashable | None = None,
+        hue_style: HueStyleOptions = None,
+        markersize: Hashable | None = None,
+        linewidth: Hashable | None = None,
+        figsize: Iterable[float] | None = None,
+        size: float | None = None,
+        aspect: float | None = None,
+        ax: Axes | None = None,
+        row: None = None,  # no wrap -> primitive
+        col: None = None,  # no wrap -> primitive
+        col_wrap: int | None = None,
+        xincrease: bool | None = True,
+        yincrease: bool | None = True,
+        add_legend: bool | None = None,
+        add_colorbar: bool | None = None,
+        add_labels: bool | Iterable[bool] = True,
+        add_title: bool = True,
+        subplot_kws: dict[str, Any] | None = None,
+        xscale: ScaleOptions = None,
+        yscale: ScaleOptions = None,
+        xticks: ArrayLike | None = None,
+        yticks: ArrayLike | None = None,
+        xlim: ArrayLike | None = None,
+        ylim: ArrayLike | None = None,
+        cmap=None,
+        vmin: float | None = None,
+        vmax: float | None = None,
+        norm: Normalize | None = None,
+        extend=None,
+        levels=None,
+        **kwargs: Any,
+    ) -> LineCollection: ...
+
+    @overload
+    def lines(
+        self,
+        *args: Any,
+        x: Hashable | None = None,
+        y: Hashable | None = None,
+        z: Hashable | None = None,
+        hue: Hashable | None = None,
+        hue_style: HueStyleOptions = None,
+        markersize: Hashable | None = None,
+        linewidth: Hashable | None = None,
+        figsize: Iterable[float] | None = None,
+        size: float | None = None,
+        aspect: float | None = None,
+        ax: Axes | None = None,
+        row: Hashable | None = None,
+        col: Hashable,  # wrap -> FacetGrid
+        col_wrap: int | None = None,
+        xincrease: bool | None = True,
+        yincrease: bool | None = True,
+        add_legend: bool | None = None,
+        add_colorbar: bool | None = None,
+        add_labels: bool | Iterable[bool] = True,
+        add_title: bool = True,
+        subplot_kws: dict[str, Any] | None = None,
+        xscale: ScaleOptions = None,
+        yscale: ScaleOptions = None,
+        xticks: ArrayLike | None = None,
+        yticks: ArrayLike | None = None,
+        xlim: ArrayLike | None = None,
+        ylim: ArrayLike | None = None,
+        cmap=None,
+        vmin: float | None = None,
+        vmax: float | None = None,
+        norm: Normalize | None = None,
+        extend=None,
+        levels=None,
+        **kwargs: Any,
+    ) -> FacetGrid[DataArray]: ...
+
+    @overload
+    def lines(
+        self,
+        *args: Any,
+        x: Hashable | None = None,
+        y: Hashable | None = None,
+        z: Hashable | None = None,
+        hue: Hashable | None = None,
+        hue_style: HueStyleOptions = None,
+        markersize: Hashable | None = None,
+        linewidth: Hashable | None = None,
+        figsize: Iterable[float] | None = None,
+        size: float | None = None,
+        aspect: float | None = None,
+        ax: Axes | None = None,
+        row: Hashable,  # wrap -> FacetGrid
+        col: Hashable | None = None,
+        col_wrap: int | None = None,
+        xincrease: bool | None = True,
+        yincrease: bool | None = True,
+        add_legend: bool | None = None,
+        add_colorbar: bool | None = None,
+        add_labels: bool | Iterable[bool] = True,
+        add_title: bool = True,
+        subplot_kws: dict[str, Any] | None = None,
+        xscale: ScaleOptions = None,
+        yscale: ScaleOptions = None,
+        xticks: ArrayLike | None = None,
+        yticks: ArrayLike | None = None,
+        xlim: ArrayLike | None = None,
+        ylim: ArrayLike | None = None,
+        cmap=None,
+        vmin: float | None = None,
+        vmax: float | None = None,
+        norm: Normalize | None = None,
+        extend=None,
+        levels=None,
+        **kwargs: Any,
+    ) -> FacetGrid[DataArray]: ...
+
+    @functools.wraps(dataset_plot.lines)
+    def lines(self, *args, **kwargs) -> LineCollection | FacetGrid[DataArray]:
+        return dataset_plot.lines(self._ds, *args, **kwargs)
+
     @overload
     def scatter(  # type: ignore[misc,unused-ignore]  # None is hashable :(
         self,