Skip to content

Commit f515b4d

Browse files
Illviljanpre-commit-ci[bot]headtr1ckclaude
authored
Add LineCollection plot (#7173)
* Add linecollection * Update dataarray_plot.py * add more lines * Update dataarray_plot.py * Remove old code * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update accessor.py * keep similar format as scatter * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update dataarray_plot.py * keep same format as scatter * Fix lines plot * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update dataarray_plot.py * Update utils.py * Attempt at hanlding coordinates with multiple dimensions * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update test_plot.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update test_plot.py * merge tests * Use similar format as scatter * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * Update utils.py * s can be float, no __len__ on those * Update dataarray_plot.py * Update dataarray_plot.py * Update dataarray_plot.py * Update dataarray_plot.py * add Hashable vs None ignores * Update utils.py * clean up * Fix color="k" * cleanup * Add tests for color and linestyle * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update test_plot.py * Update test_plot.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * assert not needed * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add some docs examples * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update plotting.rst * Update plotting.rst * Update plotting.rst * Update plotting.rst * Update plotting.rst * Update plotting.rst * Update plotting.rst * Update api.rst * improve docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update __init__.py * fix legend values * Update api-hidden.rst * Update utils.py * Add more legend labels tests * Try without fix * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add fix * mypy fixes * Make sure lines legend is correct * Update test_plot.py * Update test_plot.py * Update test_plot.py * Update test_plot.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update facetgrid.py * Update facetgrid.py * Update dataarray_plot.py * remove commented code * Update xarray/plot/utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update whats-new.rst * Add more docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix bad merge * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * make mypy happy again * Update whats-new.rst * Update whats-new.rst * Update plotting.rst * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Apply suggestions from code review * align with ax.scatter * align more with ax.scatter * Update utils.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update plotting.rst * hide warning with :stderr: * extra linebreak helps? * 2 stderr to catch the 2 warnings? * nope didn't work * test all * remove the unneccessary stderr * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update whats-new.rst * Update whats-new.rst * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * make pre-commit happy * Fix mypy error with newer matplotlib stubs Co-authored-by: Claude <[email protected]> --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Michael Niklas <[email protected]> Co-authored-by: Claude <[email protected]>
1 parent 7b03d82 commit f515b4d

11 files changed

Lines changed: 1134 additions & 45 deletions

File tree

‎doc/api-hidden.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,7 @@
396396
plot.imshow
397397
plot.pcolormesh
398398
plot.scatter
399+
plot.lines
399400
plot.surface
400401

401402
CFTimeIndex.all

‎doc/api/plotting.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Dataset
1010
:toctree: ../generated/
1111
:template: autosummary/accessor_method.rst
1212

13+
Dataset.plot.lines
1314
Dataset.plot.scatter
1415
Dataset.plot.quiver
1516
Dataset.plot.streamplot
@@ -32,6 +33,7 @@ DataArray
3233
DataArray.plot.hist
3334
DataArray.plot.imshow
3435
DataArray.plot.line
36+
DataArray.plot.lines
3537
DataArray.plot.pcolormesh
3638
DataArray.plot.step
3739
DataArray.plot.scatter

‎doc/user-guide/plotting.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -689,6 +689,59 @@ ds.plot.scatter(x="A", y="B", z="z", hue="y", markersize="x", row="x", col="w");
689689
For more advanced scatter plots, we recommend converting the relevant data variables
690690
to a pandas DataFrame and using the extensive plotting capabilities of `seaborn`.
691691

692+
### Lines
693+
694+
{py:func}`xarray.plot.lines` calls matplotlib.collections.LineCollection under the hood,
695+
allowing multiple lines being drawn efficiently. It uses similar arguments as
696+
{py:func}`xarray.plot.scatter`.
697+
698+
Let's return to the air temperature dataset:
699+
700+
```{code-cell}
701+
airtemps = xr.tutorial.open_dataset("air_temperature")
702+
air = airtemps.air - 273.15
703+
air.attrs = airtemps.air.attrs
704+
air.attrs["units"] = "deg C"
705+
706+
air.isel(lon=10).plot.lines(x="time", hue="lat");
707+
```
708+
709+
Make it a little more transparent:
710+
711+
```{code-cell}
712+
air.isel(lon=10).plot.lines(x="time", hue="lat", alpha=0.2);
713+
```
714+
715+
Zoom in a little on the x-axis, and compare a few latitudes and longitudes,
716+
group them using `hue` and `linewidth`. The `linewidth` kwarg works in
717+
a similar way as `markersize` kwarg for scatter plots, it lets you vary the
718+
line's size by variable value.
719+
720+
```{code-cell}
721+
:tags: [remove-stderr]
722+
723+
air_zoom = air.isel(time=slice(1200, 1500), lat=[5, 10, 15], lon=[10, 15])
724+
air_zoom.plot.lines(x="time", hue="lat", linewidth="lon", add_colorbar=False);
725+
```
726+
727+
Lines can modify the linestyle but does not allow markers. Instead combine {py:func}`xarray.plot.lines`
728+
with {py:func}`xarray.plot.scatter`:
729+
730+
```{code-cell}
731+
air.isel(lat=10, lon=10)[:200].plot.lines(x="time", color="k", linestyle="dashed")
732+
air.isel(lat=10, lon=10)[:200].plot.scatter(x="time", color="k", marker="^");
733+
```
734+
735+
Switching to another dataset with more variables we can analyse in similar
736+
fashion as {py:func}`xarray.plot.scatter`:
737+
738+
```{code-cell}
739+
:tags: [remove-stderr]
740+
741+
ds = xr.tutorial.scatter_example_dataset(seed=42)
742+
ds.plot.lines(x="A", y="B", hue="y", linewidth="x", row="x", col="w");
743+
```
744+
692745
### Quiver
693746

694747
Visualizing vector fields is supported with quiver plots:

‎doc/whats-new.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ New Features
2525
to :py:class:`DataArray` (``__arrow_c_schema__`` and ``__arrow_c_stream__``), enabling near zero-copy
2626
export to pyarrow, polars or duckdb.
2727
By `Jules Chéron <https://github.com/jules-ch>`_.
28+
- Added new plot method :py:meth:`DataArray.plot.lines` which allows creating line plots efficiently in
29+
a similar manner to :py:meth:`DataArray.plot.scatter`, also available for datasets. (:pull:`7173`)
30+
By `Jimmy Westling <https://github.com/illviljan>`_.
2831

2932
- The ``h5netcdf`` backend now reports compression and filter settings in the
3033
variable ``encoding`` consistently with the ``netCDF4`` backend (using

‎xarray/plot/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
hist,
1414
imshow,
1515
line,
16+
lines,
1617
pcolormesh,
1718
plot,
1819
step,
@@ -28,6 +29,7 @@
2829
"hist",
2930
"imshow",
3031
"line",
32+
"lines",
3133
"pcolormesh",
3234
"plot",
3335
"scatter",

‎xarray/plot/accessor.py‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,130 @@ def line(
135135
def line(self, *args, **kwargs) -> list[Line3D] | FacetGrid[DataArray]:
136136
return dataarray_plot.line(self._da, *args, **kwargs)
137137

138+
@overload
139+
def lines( # type: ignore[misc,unused-ignore] # None is hashable :(
140+
self,
141+
*args: Any,
142+
x: Hashable | None = None,
143+
y: Hashable | None = None,
144+
z: Hashable | None = None,
145+
hue: Hashable | None = None,
146+
hue_style: HueStyleOptions = None,
147+
markersize: Hashable | None = None,
148+
linewidth: Hashable | None = None,
149+
figsize: Iterable[float] | None = None,
150+
size: float | None = None,
151+
aspect: float | None = None,
152+
ax: Axes | None = None,
153+
row: None = None, # no wrap -> primitive
154+
col: None = None, # no wrap -> primitive
155+
col_wrap: int | None = None,
156+
xincrease: bool | None = True,
157+
yincrease: bool | None = True,
158+
add_legend: bool | None = None,
159+
add_colorbar: bool | None = None,
160+
add_labels: bool | Iterable[bool] = True,
161+
add_title: bool = True,
162+
subplot_kws: dict[str, Any] | None = None,
163+
xscale: ScaleOptions = None,
164+
yscale: ScaleOptions = None,
165+
xticks: ArrayLike | None = None,
166+
yticks: ArrayLike | None = None,
167+
xlim: ArrayLike | None = None,
168+
ylim: ArrayLike | None = None,
169+
cmap=None,
170+
vmin: float | None = None,
171+
vmax: float | None = None,
172+
norm: Normalize | None = None,
173+
extend=None,
174+
levels=None,
175+
**kwargs: Any,
176+
) -> LineCollection: ...
177+
178+
@overload
179+
def lines(
180+
self,
181+
*args: Any,
182+
x: Hashable | None = None,
183+
y: Hashable | None = None,
184+
z: Hashable | None = None,
185+
hue: Hashable | None = None,
186+
hue_style: HueStyleOptions = None,
187+
markersize: Hashable | None = None,
188+
linewidth: Hashable | None = None,
189+
figsize: Iterable[float] | None = None,
190+
size: float | None = None,
191+
aspect: float | None = None,
192+
ax: Axes | None = None,
193+
row: Hashable | None = None,
194+
col: Hashable, # wrap -> FacetGrid
195+
col_wrap: int | None = None,
196+
xincrease: bool | None = True,
197+
yincrease: bool | None = True,
198+
add_legend: bool | None = None,
199+
add_colorbar: bool | None = None,
200+
add_labels: bool | Iterable[bool] = True,
201+
add_title: bool = True,
202+
subplot_kws: dict[str, Any] | None = None,
203+
xscale: ScaleOptions = None,
204+
yscale: ScaleOptions = None,
205+
xticks: ArrayLike | None = None,
206+
yticks: ArrayLike | None = None,
207+
xlim: ArrayLike | None = None,
208+
ylim: ArrayLike | None = None,
209+
cmap=None,
210+
vmin: float | None = None,
211+
vmax: float | None = None,
212+
norm: Normalize | None = None,
213+
extend=None,
214+
levels=None,
215+
**kwargs: Any,
216+
) -> FacetGrid[DataArray]: ...
217+
218+
@overload
219+
def lines(
220+
self,
221+
*args: Any,
222+
x: Hashable | None = None,
223+
y: Hashable | None = None,
224+
z: Hashable | None = None,
225+
hue: Hashable | None = None,
226+
hue_style: HueStyleOptions = None,
227+
markersize: Hashable | None = None,
228+
linewidth: Hashable | None = None,
229+
figsize: Iterable[float] | None = None,
230+
size: float | None = None,
231+
aspect: float | None = None,
232+
ax: Axes | None = None,
233+
row: Hashable, # wrap -> FacetGrid
234+
col: Hashable | None = None,
235+
col_wrap: int | None = None,
236+
xincrease: bool | None = True,
237+
yincrease: bool | None = True,
238+
add_legend: bool | None = None,
239+
add_colorbar: bool | None = None,
240+
add_labels: bool | Iterable[bool] = True,
241+
add_title: bool = True,
242+
subplot_kws: dict[str, Any] | None = None,
243+
xscale: ScaleOptions = None,
244+
yscale: ScaleOptions = None,
245+
xticks: ArrayLike | None = None,
246+
yticks: ArrayLike | None = None,
247+
xlim: ArrayLike | None = None,
248+
ylim: ArrayLike | None = None,
249+
cmap=None,
250+
vmin: float | None = None,
251+
vmax: float | None = None,
252+
norm: Normalize | None = None,
253+
extend=None,
254+
levels=None,
255+
**kwargs: Any,
256+
) -> FacetGrid[DataArray]: ...
257+
258+
@functools.wraps(dataarray_plot.lines)
259+
def lines(self, *args, **kwargs) -> LineCollection | FacetGrid[DataArray]:
260+
return dataarray_plot.lines(self._da, *args, **kwargs)
261+
138262
@overload
139263
def step( # type: ignore[misc,unused-ignore] # None is hashable :(
140264
self,
@@ -923,6 +1047,130 @@ def __call__(self, *args, **kwargs) -> NoReturn:
9231047
"an explicit plot method, e.g. ds.plot.scatter(...)"
9241048
)
9251049

1050+
@overload
1051+
def lines( # type: ignore[misc,unused-ignore] # None is hashable :(
1052+
self,
1053+
*args: Any,
1054+
x: Hashable | None = None,
1055+
y: Hashable | None = None,
1056+
z: Hashable | None = None,
1057+
hue: Hashable | None = None,
1058+
hue_style: HueStyleOptions = None,
1059+
markersize: Hashable | None = None,
1060+
linewidth: Hashable | None = None,
1061+
figsize: Iterable[float] | None = None,
1062+
size: float | None = None,
1063+
aspect: float | None = None,
1064+
ax: Axes | None = None,
1065+
row: None = None, # no wrap -> primitive
1066+
col: None = None, # no wrap -> primitive
1067+
col_wrap: int | None = None,
1068+
xincrease: bool | None = True,
1069+
yincrease: bool | None = True,
1070+
add_legend: bool | None = None,
1071+
add_colorbar: bool | None = None,
1072+
add_labels: bool | Iterable[bool] = True,
1073+
add_title: bool = True,
1074+
subplot_kws: dict[str, Any] | None = None,
1075+
xscale: ScaleOptions = None,
1076+
yscale: ScaleOptions = None,
1077+
xticks: ArrayLike | None = None,
1078+
yticks: ArrayLike | None = None,
1079+
xlim: ArrayLike | None = None,
1080+
ylim: ArrayLike | None = None,
1081+
cmap=None,
1082+
vmin: float | None = None,
1083+
vmax: float | None = None,
1084+
norm: Normalize | None = None,
1085+
extend=None,
1086+
levels=None,
1087+
**kwargs: Any,
1088+
) -> LineCollection: ...
1089+
1090+
@overload
1091+
def lines(
1092+
self,
1093+
*args: Any,
1094+
x: Hashable | None = None,
1095+
y: Hashable | None = None,
1096+
z: Hashable | None = None,
1097+
hue: Hashable | None = None,
1098+
hue_style: HueStyleOptions = None,
1099+
markersize: Hashable | None = None,
1100+
linewidth: Hashable | None = None,
1101+
figsize: Iterable[float] | None = None,
1102+
size: float | None = None,
1103+
aspect: float | None = None,
1104+
ax: Axes | None = None,
1105+
row: Hashable | None = None,
1106+
col: Hashable, # wrap -> FacetGrid
1107+
col_wrap: int | None = None,
1108+
xincrease: bool | None = True,
1109+
yincrease: bool | None = True,
1110+
add_legend: bool | None = None,
1111+
add_colorbar: bool | None = None,
1112+
add_labels: bool | Iterable[bool] = True,
1113+
add_title: bool = True,
1114+
subplot_kws: dict[str, Any] | None = None,
1115+
xscale: ScaleOptions = None,
1116+
yscale: ScaleOptions = None,
1117+
xticks: ArrayLike | None = None,
1118+
yticks: ArrayLike | None = None,
1119+
xlim: ArrayLike | None = None,
1120+
ylim: ArrayLike | None = None,
1121+
cmap=None,
1122+
vmin: float | None = None,
1123+
vmax: float | None = None,
1124+
norm: Normalize | None = None,
1125+
extend=None,
1126+
levels=None,
1127+
**kwargs: Any,
1128+
) -> FacetGrid[DataArray]: ...
1129+
1130+
@overload
1131+
def lines(
1132+
self,
1133+
*args: Any,
1134+
x: Hashable | None = None,
1135+
y: Hashable | None = None,
1136+
z: Hashable | None = None,
1137+
hue: Hashable | None = None,
1138+
hue_style: HueStyleOptions = None,
1139+
markersize: Hashable | None = None,
1140+
linewidth: Hashable | None = None,
1141+
figsize: Iterable[float] | None = None,
1142+
size: float | None = None,
1143+
aspect: float | None = None,
1144+
ax: Axes | None = None,
1145+
row: Hashable, # wrap -> FacetGrid
1146+
col: Hashable | None = None,
1147+
col_wrap: int | None = None,
1148+
xincrease: bool | None = True,
1149+
yincrease: bool | None = True,
1150+
add_legend: bool | None = None,
1151+
add_colorbar: bool | None = None,
1152+
add_labels: bool | Iterable[bool] = True,
1153+
add_title: bool = True,
1154+
subplot_kws: dict[str, Any] | None = None,
1155+
xscale: ScaleOptions = None,
1156+
yscale: ScaleOptions = None,
1157+
xticks: ArrayLike | None = None,
1158+
yticks: ArrayLike | None = None,
1159+
xlim: ArrayLike | None = None,
1160+
ylim: ArrayLike | None = None,
1161+
cmap=None,
1162+
vmin: float | None = None,
1163+
vmax: float | None = None,
1164+
norm: Normalize | None = None,
1165+
extend=None,
1166+
levels=None,
1167+
**kwargs: Any,
1168+
) -> FacetGrid[DataArray]: ...
1169+
1170+
@functools.wraps(dataset_plot.lines)
1171+
def lines(self, *args, **kwargs) -> LineCollection | FacetGrid[DataArray]:
1172+
return dataset_plot.lines(self._ds, *args, **kwargs)
1173+
9261174
@overload
9271175
def scatter( # type: ignore[misc,unused-ignore] # None is hashable :(
9281176
self,

0 commit comments

Comments
 (0)