Plotting¶
Introduction¶
Labeled data enables expressive computations. These same labels can also be used to easily create informative plots.
xarray’s plotting capabilities are centered around
DataArray
objects.
To plot Dataset
objects
simply access the relevant DataArrays, ie dset['var1']
.
Dataset specific plotting routines are also available (see Datasets).
Here we focus mostly on arrays 2d or larger. If your data fits
nicely into a pandas DataFrame then you’re better off using one of the more
developed tools there.
xarray plotting functionality is a thin wrapper around the popular matplotlib library. Matplotlib syntax and function names were copied as much as possible, which makes for an easy transition between the two. Matplotlib must be installed before xarray can plot.
To use xarray’s plotting capabilities with time coordinates containing
cftime.datetime
objects
nc-time-axis v1.2.0 or later
needs to be installed.
For more extensive plotting applications consider the following projects:
Seaborn: “provides a high-level interface for drawing attractive statistical graphics.” Integrates well with pandas.
HoloViews and GeoViews: “Composable, declarative data structures for building even complex visualizations easily.” Includes native support for xarray objects.
hvplot:
hvplot
makes it very easy to produce dynamic plots (backed byHoloviews
orGeoviews
) by adding ahvplot
accessor to DataArrays.Cartopy: Provides cartographic tools.
Imports¶
The following imports are necessary for all of the examples.
In [1]: import numpy as np
In [2]: import pandas as pd
In [3]: import matplotlib.pyplot as plt
In [4]: import xarray as xr
For these examples we’ll use the North American air temperature dataset.
In [5]: airtemps = xr.tutorial.open_dataset('air_temperature')
---------------------------------------------------------------------------
FileNotFoundError Traceback (most recent call last)
<ipython-input-5-892a7b38525b> in <module>
----> 1 airtemps = xr.tutorial.open_dataset('air_temperature')
/build/python-xarray-4F1RXc/python-xarray-0.15.1/xarray/tutorial.py in open_dataset(name, cache, cache_dir, github_url, branch, **kws)
76 # May want to add an option to remove it.
77 if not _os.path.isdir(longdir):
---> 78 _os.mkdir(longdir)
79
80 url = "/".join((github_url, "raw", branch, fullname))
FileNotFoundError: [Errno 2] No such file or directory: '/sbuild-nonexistent/.xarray_tutorial_data'
In [6]: airtemps
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-6-eb57b540ddce> in <module>
----> 1 airtemps
NameError: name 'airtemps' is not defined
# Convert to celsius
In [7]: air = airtemps.air - 273.15
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-7-ca9decd7dd88> in <module>
----> 1 air = airtemps.air - 273.15
NameError: name 'airtemps' is not defined
# copy attributes to get nice figure labels and change Kelvin to Celsius
In [8]: air.attrs = airtemps.air.attrs
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-8-0f41191e8013> in <module>
----> 1 air.attrs = airtemps.air.attrs
NameError: name 'airtemps' is not defined
In [9]: air.attrs['units'] = 'deg C'
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-9-92321b3ea868> in <module>
----> 1 air.attrs['units'] = 'deg C'
NameError: name 'air' is not defined
Note
Until GH1614 is solved, you might need to copy over the metadata in attrs
to get informative figure labels (as was done above).
DataArrays¶
One Dimension¶
Simple Example¶
The simplest way to make a plot is to call the DataArray.plot()
method.
In [10]: air1d = air.isel(lat=10, lon=10)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-10-e8b74ff84db4> in <module>
----> 1 air1d = air.isel(lat=10, lon=10)
NameError: name 'air' is not defined
In [11]: air1d.plot()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-11-f4da044a917f> in <module>
----> 1 air1d.plot()
NameError: name 'air1d' is not defined

xarray uses the coordinate name along with metadata attrs.long_name
, attrs.standard_name
, DataArray.name
and attrs.units
(if available) to label the axes. The names long_name
, standard_name
and units
are copied from the CF-conventions spec. When choosing names, the order of precedence is long_name
, standard_name
and finally DataArray.name
. The y-axis label in the above plot was constructed from the long_name
and units
attributes of air1d
.
In [12]: air1d.attrs
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-12-60f8bca41fc7> in <module>
----> 1 air1d.attrs
NameError: name 'air1d' is not defined
Additional Arguments¶
Additional arguments are passed directly to the matplotlib function which
does the work.
For example, xarray.plot.line()
calls
matplotlib.pyplot.plot passing in the index and the array values as x and y, respectively.
So to make a line plot with blue triangles a matplotlib format string
can be used:
In [13]: air1d[:200].plot.line('b-^')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-13-882aeaf2163b> in <module>
----> 1 air1d[:200].plot.line('b-^')
NameError: name 'air1d' is not defined

Note
Not all xarray plotting methods support passing positional arguments to the wrapped matplotlib functions, but they do all support keyword arguments.
Keyword arguments work the same way, and are more explicit.
In [14]: air1d[:200].plot.line(color='purple', marker='o')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-14-d2ab9e3a878c> in <module>
----> 1 air1d[:200].plot.line(color='purple', marker='o')
NameError: name 'air1d' is not defined

Adding to Existing Axis¶
To add the plot to an existing axis pass in the axis as a keyword argument
ax
. This works for all xarray plotting methods.
In this example axes
is an array consisting of the left and right
axes created by plt.subplots
.
In [15]: fig, axes = plt.subplots(ncols=2)
In [16]: axes
Out[16]:
array([<matplotlib.axes._subplots.AxesSubplot object at 0x7f048ed1f100>,
<matplotlib.axes._subplots.AxesSubplot object at 0x7f048ef71c70>], dtype=object)
In [17]: air1d.plot(ax=axes[0])
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-17-47c7fe138f5e> in <module>
----> 1 air1d.plot(ax=axes[0])
NameError: name 'air1d' is not defined
In [18]: air1d.plot.hist(ax=axes[1])
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-18-41753485ddae> in <module>
----> 1 air1d.plot.hist(ax=axes[1])
NameError: name 'air1d' is not defined
In [19]: plt.tight_layout()
In [20]: plt.draw()

On the right is a histogram created by xarray.plot.hist()
.
Controlling the figure size¶
You can pass a figsize
argument to all xarray’s plotting methods to
control the figure size. For convenience, xarray’s plotting methods also
support the aspect
and size
arguments which control the size of the
resulting image via the formula figsize = (aspect * size, size)
:
In [21]: air1d.plot(aspect=2, size=3)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-21-5fbaeea09bd8> in <module>
----> 1 air1d.plot(aspect=2, size=3)
NameError: name 'air1d' is not defined
In [22]: plt.tight_layout()

This feature also works with Faceting. For facet plots,
size
and aspect
refer to a single panel (so that aspect * size
gives the width of each facet in inches), while figsize
refers to the
entire figure (as for matplotlib’s figsize
argument).
Note
If figsize
or size
are used, a new figure is created,
so this is mutually exclusive with the ax
argument.
Note
The convention used by xarray (figsize = (aspect * size, size)
) is
borrowed from seaborn: it is therefore not equivalent to matplotlib’s.
Multiple lines showing variation along a dimension¶
It is possible to make line plots of two-dimensional data by calling xarray.plot.line()
with appropriate arguments. Consider the 3D variable air
defined above. We can use line
plots to check the variation of air temperature at three different latitudes along a longitude line:
In [23]: air.isel(lon=10, lat=[19,21,22]).plot.line(x='time')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-23-ffc2f522aa0e> in <module>
----> 1 air.isel(lon=10, lat=[19,21,22]).plot.line(x='time')
NameError: name 'air' is not defined

It is required to explicitly specify either
x
: the dimension to be used for the x-axis, orhue
: the dimension you want to represent by multiple lines.
Thus, we could have made the previous plot by specifying hue='lat'
instead of x='time'
.
If required, the automatic legend can be turned off using add_legend=False
. Alternatively,
hue
can be passed directly to xarray.plot.line()
as air.isel(lon=10, lat=[19,21,22]).plot.line(hue=’lat’).
Dimension along y-axis¶
It is also possible to make line plots such that the data are on the x-axis and a dimension is on the y-axis. This can be done by specifying the appropriate y
keyword argument.
In [24]: air.isel(time=10, lon=[10, 11]).plot(y='lat', hue='lon')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-24-a3482393ead8> in <module>
----> 1 air.isel(time=10, lon=[10, 11]).plot(y='lat', hue='lon')
NameError: name 'air' is not defined

Step plots¶
As an alternative, also a step plot similar to matplotlib’s plt.step
can be
made using 1D data.
In [25]: air1d[:20].plot.step(where='mid')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-25-2f04611674f8> in <module>
----> 1 air1d[:20].plot.step(where='mid')
NameError: name 'air1d' is not defined

The argument where
defines where the steps should be placed, options are
'pre'
(default), 'post'
, and 'mid'
. This is particularly handy
when plotting data grouped with Dataset.groupby_bins()
.
In [26]: air_grp = air.mean(['time','lon']).groupby_bins('lat',[0,23.5,66.5,90])
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-26-5383803c0fc0> in <module>
----> 1 air_grp = air.mean(['time','lon']).groupby_bins('lat',[0,23.5,66.5,90])
NameError: name 'air' is not defined
In [27]: air_mean = air_grp.mean()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-27-4361268a2eea> in <module>
----> 1 air_mean = air_grp.mean()
NameError: name 'air_grp' is not defined
In [28]: air_std = air_grp.std()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-28-d5a1e0e5c771> in <module>
----> 1 air_std = air_grp.std()
NameError: name 'air_grp' is not defined
In [29]: air_mean.plot.step()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-29-4162c0ac1db4> in <module>
----> 1 air_mean.plot.step()
NameError: name 'air_mean' is not defined
In [30]: (air_mean + air_std).plot.step(ls=':')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-30-e6be09a2d1dc> in <module>
----> 1 (air_mean + air_std).plot.step(ls=':')
NameError: name 'air_mean' is not defined
In [31]: (air_mean - air_std).plot.step(ls=':')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-31-ad918a821665> in <module>
----> 1 (air_mean - air_std).plot.step(ls=':')
NameError: name 'air_mean' is not defined
In [32]: plt.ylim(-20,30)
Out[32]: (-20, 30)
In [33]: plt.title('Zonal mean temperature')
Out[33]: Text(0.5, 1.0, 'Zonal mean temperature')

In this case, the actual boundaries of the bins are used and the where
argument
is ignored.
Other axes kwargs¶
The keyword arguments xincrease
and yincrease
let you control the axes direction.
In [34]: air.isel(time=10, lon=[10, 11]).plot.line(y='lat', hue='lon', xincrease=False, yincrease=False)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-34-b5b202d47469> in <module>
----> 1 air.isel(time=10, lon=[10, 11]).plot.line(y='lat', hue='lon', xincrease=False, yincrease=False)
NameError: name 'air' is not defined

In addition, one can use xscale, yscale
to set axes scaling; xticks, yticks
to set axes ticks and xlim, ylim
to set axes limits. These accept the same values as the matplotlib methods Axes.set_(x,y)scale()
, Axes.set_(x,y)ticks()
, Axes.set_(x,y)lim()
respectively.
Two Dimensions¶
Simple Example¶
The default method DataArray.plot()
calls xarray.plot.pcolormesh()
by default when the data is two-dimensional.
In [35]: air2d = air.isel(time=500)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-35-aeb322c2d11c> in <module>
----> 1 air2d = air.isel(time=500)
NameError: name 'air' is not defined
In [36]: air2d.plot()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-36-267da278d579> in <module>
----> 1 air2d.plot()
NameError: name 'air2d' is not defined

All 2d plots in xarray allow the use of the keyword arguments yincrease
and xincrease
.
In [37]: air2d.plot(yincrease=False)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-37-2643e81aa1a9> in <module>
----> 1 air2d.plot(yincrease=False)
NameError: name 'air2d' is not defined

Note
We use xarray.plot.pcolormesh()
as the default two-dimensional plot
method because it is more flexible than xarray.plot.imshow()
.
However, for large arrays, imshow
can be much faster than pcolormesh
.
If speed is important to you and you are plotting a regular mesh, consider
using imshow
.
Missing Values¶
xarray plots data with Missing values.
In [38]: bad_air2d = air2d.copy()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-38-8362b177be7e> in <module>
----> 1 bad_air2d = air2d.copy()
NameError: name 'air2d' is not defined
In [39]: bad_air2d[dict(lat=slice(0, 10), lon=slice(0, 25))] = np.nan
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-39-9ea5b3533d69> in <module>
----> 1 bad_air2d[dict(lat=slice(0, 10), lon=slice(0, 25))] = np.nan
NameError: name 'bad_air2d' is not defined
In [40]: bad_air2d.plot()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-40-d64f0a79960e> in <module>
----> 1 bad_air2d.plot()
NameError: name 'bad_air2d' is not defined

Nonuniform Coordinates¶
It’s not necessary for the coordinates to be evenly spaced. Both
xarray.plot.pcolormesh()
(default) and xarray.plot.contourf()
can
produce plots with nonuniform coordinates.
In [41]: b = air2d.copy()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-41-8ff3ba4430a3> in <module>
----> 1 b = air2d.copy()
NameError: name 'air2d' is not defined
# Apply a nonlinear transformation to one of the coords
In [42]: b.coords['lat'] = np.log(b.coords['lat'])
---------------------------------------------------------------------------
KeyError Traceback (most recent call last)
/build/python-xarray-4F1RXc/python-xarray-0.15.1/xarray/core/dataarray.py in _getitem_coord(self, key)
616 try:
--> 617 var = self._coords[key]
618 except KeyError:
KeyError: 'lat'
During handling of the above exception, another exception occurred:
KeyError Traceback (most recent call last)
<ipython-input-42-ec02fa6ccfba> in <module>
----> 1 b.coords['lat'] = np.log(b.coords['lat'])
/build/python-xarray-4F1RXc/python-xarray-0.15.1/xarray/core/coordinates.py in __getitem__(self, key)
280
281 def __getitem__(self, key: Hashable) -> "DataArray":
--> 282 return self._data._getitem_coord(key)
283
284 def _update_coords(
/build/python-xarray-4F1RXc/python-xarray-0.15.1/xarray/core/dataarray.py in _getitem_coord(self, key)
618 except KeyError:
619 dim_sizes = dict(zip(self.dims, self.shape))
--> 620 _, key, var = _get_virtual_variable(
621 self._coords, key, self._level_coords, dim_sizes
622 )
/build/python-xarray-4F1RXc/python-xarray-0.15.1/xarray/core/dataset.py in _get_virtual_variable(variables, key, level_vars, dim_sizes)
165 ref_var = dim_var.to_index_variable().get_level_variable(ref_name)
166 else:
--> 167 ref_var = variables[ref_name]
168
169 if var_name is None:
KeyError: 'lat'
In [43]: b.plot()
Out[43]: [<matplotlib.lines.Line2D at 0x7f048fa93cd0>]

Calling Matplotlib¶
Since this is a thin wrapper around matplotlib, all the functionality of matplotlib is available.
In [44]: air2d.plot(cmap=plt.cm.Blues)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-44-b347cf3a8c47> in <module>
----> 1 air2d.plot(cmap=plt.cm.Blues)
NameError: name 'air2d' is not defined
In [45]: plt.title('These colors prove North America\nhas fallen in the ocean')
Out[45]: Text(0.5, 1.0, 'These colors prove North America\nhas fallen in the ocean')
In [46]: plt.ylabel('latitude')
Out[46]: Text(0, 0.5, 'latitude')
In [47]: plt.xlabel('longitude')
Out[47]: Text(0.5, 0, 'longitude')
In [48]: plt.tight_layout()
In [49]: plt.draw()

Note
xarray methods update label information and generally play around with the
axes. So any kind of updates to the plot
should be done after the call to the xarray’s plot.
In the example below, plt.xlabel
effectively does nothing, since
d_ylog.plot()
updates the xlabel.
In [50]: plt.xlabel('Never gonna see this.')
Out[50]: Text(0.5, 0, 'Never gonna see this.')
In [51]: air2d.plot()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-51-267da278d579> in <module>
----> 1 air2d.plot()
NameError: name 'air2d' is not defined
In [52]: plt.draw()

Colormaps¶
xarray borrows logic from Seaborn to infer what kind of color map to use. For example, consider the original data in Kelvins rather than Celsius:
In [53]: airtemps.air.isel(time=0).plot()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-53-518aaa410d12> in <module>
----> 1 airtemps.air.isel(time=0).plot()
NameError: name 'airtemps' is not defined

The Celsius data contain 0, so a diverging color map was used. The Kelvins do not have 0, so the default color map was used.
Robust¶
Outliers often have an extreme effect on the output of the plot. Here we add two bad data points. This affects the color scale, washing out the plot.
In [54]: air_outliers = airtemps.air.isel(time=0).copy()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-54-07230c544b46> in <module>
----> 1 air_outliers = airtemps.air.isel(time=0).copy()
NameError: name 'airtemps' is not defined
In [55]: air_outliers[0, 0] = 100
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-55-27ab3b18e532> in <module>
----> 1 air_outliers[0, 0] = 100
NameError: name 'air_outliers' is not defined
In [56]: air_outliers[-1, -1] = 400
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-56-a5788991cda7> in <module>
----> 1 air_outliers[-1, -1] = 400
NameError: name 'air_outliers' is not defined
In [57]: air_outliers.plot()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-57-143cc03c2ff6> in <module>
----> 1 air_outliers.plot()
NameError: name 'air_outliers' is not defined

This plot shows that we have outliers. The easy way to visualize
the data without the outliers is to pass the parameter
robust=True
.
This will use the 2nd and 98th
percentiles of the data to compute the color limits.
In [58]: air_outliers.plot(robust=True)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-58-cdc0b84add6a> in <module>
----> 1 air_outliers.plot(robust=True)
NameError: name 'air_outliers' is not defined

Observe that the ranges of the color bar have changed. The arrows on the color bar indicate that the colors include data points outside the bounds.
Discrete Colormaps¶
It is often useful, when visualizing 2d data, to use a discrete colormap,
rather than the default continuous colormaps that matplotlib uses. The
levels
keyword argument can be used to generate plots with discrete
colormaps. For example, to make a plot with 8 discrete color intervals:
In [59]: air2d.plot(levels=8)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-59-89bc1504b066> in <module>
----> 1 air2d.plot(levels=8)
NameError: name 'air2d' is not defined

It is also possible to use a list of levels to specify the boundaries of the discrete colormap:
In [60]: air2d.plot(levels=[0, 12, 18, 30])
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-60-bbd038f02d85> in <module>
----> 1 air2d.plot(levels=[0, 12, 18, 30])
NameError: name 'air2d' is not defined

You can also specify a list of discrete colors through the colors
argument:
In [61]: flatui = ["#9b59b6", "#3498db", "#95a5a6", "#e74c3c", "#34495e", "#2ecc71"]
In [62]: air2d.plot(levels=[0, 12, 18, 30], colors=flatui)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-62-d56a56059dba> in <module>
----> 1 air2d.plot(levels=[0, 12, 18, 30], colors=flatui)
NameError: name 'air2d' is not defined

Finally, if you have Seaborn
installed, you can also specify a seaborn color palette to the cmap
argument. Note that levels
must be specified with seaborn color palettes
if using imshow
or pcolormesh
(but not with contour
or contourf
,
since levels are chosen automatically).
In [63]: air2d.plot(levels=10, cmap='husl')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-63-bd9e60a038d1> in <module>
----> 1 air2d.plot(levels=10, cmap='husl')
NameError: name 'air2d' is not defined
In [64]: plt.draw()

Faceting¶
Faceting here refers to splitting an array along one or two dimensions and plotting each group. xarray’s basic plotting is useful for plotting two dimensional arrays. What about three or four dimensional arrays? That’s where facets become helpful. The general approach to plotting here is called “small multiples”, where the same kind of plot is repeated multiple times, and the specific use of small multiples to display the same relationship conditioned on one ore more other variables is often called a “trellis plot”.
Consider the temperature data set. There are 4 observations per day for two years which makes for 2920 values along the time dimension. One way to visualize this data is to make a separate plot for each time period.
The faceted dimension should not have too many values; faceting on the time dimension will produce 2920 plots. That’s too much to be helpful. To handle this situation try performing an operation that reduces the size of the data in some way. For example, we could compute the average air temperature for each month and reduce the size of this dimension from 2920 -> 12. A simpler way is to just take a slice on that dimension. So let’s use a slice to pick 6 times throughout the first year.
In [65]: t = air.isel(time=slice(0, 365 * 4, 250))
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-65-d2310b76d025> in <module>
----> 1 t = air.isel(time=slice(0, 365 * 4, 250))
NameError: name 'air' is not defined
In [66]: t.coords
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-66-22319bc55475> in <module>
----> 1 t.coords
AttributeError: 'DatetimeIndex' object has no attribute 'coords'
Simple Example¶
The easiest way to create faceted plots is to pass in row
or col
arguments to the xarray plotting methods/functions. This returns a
xarray.plot.FacetGrid
object.
In [67]: g_simple = t.plot(x='lon', y='lat', col='time', col_wrap=3)
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-67-c47cf93c074c> in <module>
----> 1 g_simple = t.plot(x='lon', y='lat', col='time', col_wrap=3)
AttributeError: 'DatetimeIndex' object has no attribute 'plot'

Faceting also works for line plots.
In [68]: g_simple_line = t.isel(lat=slice(0,None,4)).plot(x='lon', hue='lat', col='time', col_wrap=3)
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-68-16639ffe62fd> in <module>
----> 1 g_simple_line = t.isel(lat=slice(0,None,4)).plot(x='lon', hue='lat', col='time', col_wrap=3)
AttributeError: 'DatetimeIndex' object has no attribute 'isel'

4 dimensional¶
For 4 dimensional arrays we can use the rows and columns of the grids. Here we create a 4 dimensional array by taking the original data and adding a fixed amount. Now we can see how the temperature maps would compare if one were much hotter.
In [69]: t2 = t.isel(time=slice(0, 2))
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-69-529e418b1a0d> in <module>
----> 1 t2 = t.isel(time=slice(0, 2))
AttributeError: 'DatetimeIndex' object has no attribute 'isel'
In [70]: t4d = xr.concat([t2, t2 + 40], pd.Index(['normal', 'hot'], name='fourth_dim'))
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-70-4f02325ae2c5> in <module>
----> 1 t4d = xr.concat([t2, t2 + 40], pd.Index(['normal', 'hot'], name='fourth_dim'))
NameError: name 't2' is not defined
# This is a 4d array
In [71]: t4d.coords
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-71-30c5897da9ca> in <module>
----> 1 t4d.coords
NameError: name 't4d' is not defined
In [72]: t4d.plot(x='lon', y='lat', col='time', row='fourth_dim')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-72-596329cde362> in <module>
----> 1 t4d.plot(x='lon', y='lat', col='time', row='fourth_dim')
NameError: name 't4d' is not defined

Other features¶
Faceted plotting supports other arguments common to xarray 2d plots.
In [73]: hasoutliers = t.isel(time=slice(0, 5)).copy()
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-73-2c58f0b7b3c1> in <module>
----> 1 hasoutliers = t.isel(time=slice(0, 5)).copy()
AttributeError: 'DatetimeIndex' object has no attribute 'isel'
In [74]: hasoutliers[0, 0, 0] = -100
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-74-610f8fdf815a> in <module>
----> 1 hasoutliers[0, 0, 0] = -100
NameError: name 'hasoutliers' is not defined
In [75]: hasoutliers[-1, -1, -1] = 400
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-75-faa35bc97fe5> in <module>
----> 1 hasoutliers[-1, -1, -1] = 400
NameError: name 'hasoutliers' is not defined
In [76]: g = hasoutliers.plot.pcolormesh('lon', 'lat', col='time', col_wrap=3,
....: robust=True, cmap='viridis',
....: cbar_kwargs={'label': 'this has outliers'})
....:
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-76-b34d65c0994b> in <module>
----> 1 g = hasoutliers.plot.pcolormesh('lon', 'lat', col='time', col_wrap=3,
2 robust=True, cmap='viridis',
3 cbar_kwargs={'label': 'this has outliers'})
NameError: name 'hasoutliers' is not defined

FacetGrid Objects¶
The object returned, g
in the above examples, is a FacetGrid
object
that links a DataArray
to a matplotlib figure with a particular structure.
This object can be used to control the behavior of the multiple plots.
It borrows an API and code from Seaborn’s FacetGrid.
The structure is contained within the axes
and name_dicts
attributes, both 2d Numpy object arrays.
In [77]: g.axes
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-77-f75038449fe8> in <module>
----> 1 g.axes
NameError: name 'g' is not defined
In [78]: g.name_dicts
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-78-2df4766167c7> in <module>
----> 1 g.name_dicts
NameError: name 'g' is not defined
It’s possible to select the xarray.DataArray
or
xarray.Dataset
corresponding to the FacetGrid through the
name_dicts
.
In [79]: g.data.loc[g.name_dicts[0, 0]]
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-79-d47bb47790a1> in <module>
----> 1 g.data.loc[g.name_dicts[0, 0]]
NameError: name 'g' is not defined
Here is an example of using the lower level API and then modifying the axes after they have been plotted.
In [80]: g = t.plot.imshow('lon', 'lat', col='time', col_wrap=3, robust=True)
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-80-a14bfd1ccb9f> in <module>
----> 1 g = t.plot.imshow('lon', 'lat', col='time', col_wrap=3, robust=True)
AttributeError: 'DatetimeIndex' object has no attribute 'plot'
In [81]: for i, ax in enumerate(g.axes.flat):
....: ax.set_title('Air Temperature %d' % i)
....:
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-81-aceca28e57c8> in <module>
----> 1 for i, ax in enumerate(g.axes.flat):
2 ax.set_title('Air Temperature %d' % i)
NameError: name 'g' is not defined
In [82]: bottomright = g.axes[-1, -1]
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-82-1d727aa86050> in <module>
----> 1 bottomright = g.axes[-1, -1]
NameError: name 'g' is not defined
In [83]: bottomright.annotate('bottom right', (240, 40))
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-83-08c49fd5c18d> in <module>
----> 1 bottomright.annotate('bottom right', (240, 40))
NameError: name 'bottomright' is not defined
In [84]: plt.draw()

FacetGrid
objects have methods that let you customize the automatically generated
axis labels, axis ticks and plot titles. See set_titles()
,
set_xlabels()
, set_ylabels()
and
set_ticks()
for more information.
Plotting functions can be applied to each subset of the data by calling map_dataarray()
or to each subplot by calling map()
.
TODO: add an example of using the map
method to plot dataset variables
(e.g., with plt.quiver
).
Datasets¶
xarray
has limited support for plotting Dataset variables against each other.
Consider this dataset
In [85]: ds = xr.tutorial.scatter_example_dataset()
In [86]: ds
Out[86]:
<xarray.Dataset>
Dimensions: (w: 4, x: 3, y: 11, z: 4)
Coordinates:
* x (x) int64 0 1 2
* y (y) float64 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
* z (z) int64 0 1 2 3
* w (w) <U5 'one' 'two' 'three' 'five'
Data variables:
A (x, y, z, w) float64 -0.104 0.02719 -0.0425 ... -0.1175 -0.0183
B (x, y, z, w) float64 0.0 0.0 0.0 0.0 ... 1.369 1.408 1.387 1.417
Suppose we want to scatter A
against B
In [87]: ds.plot.scatter(x='A', y='B')
Out[87]: <matplotlib.collections.PathCollection at 0x7f04a2ab0190>

The hue
kwarg lets you vary the color by variable value
In [88]: ds.plot.scatter(x='A', y='B', hue='w')
Out[88]:
[<matplotlib.collections.PathCollection at 0x7f048ee7b940>,
<matplotlib.collections.PathCollection at 0x7f04782b2310>,
<matplotlib.collections.PathCollection at 0x7f04780dc5e0>,
<matplotlib.collections.PathCollection at 0x7f04780e9850>]

When hue
is specified, a colorbar is added for numeric hue
DataArrays by
default and a legend is added for non-numeric hue
DataArrays (as above).
You can force a legend instead of a colorbar by setting hue_style='discrete'
.
Additionally, the boolean kwarg add_guide
can be used to prevent the display of a legend or colorbar (as appropriate).
In [89]: ds = ds.assign(w=[1, 2, 3, 5])
In [90]: ds.plot.scatter(x='A', y='B', hue='w', hue_style='discrete')
Out[90]:
[<matplotlib.collections.PathCollection at 0x7f048ea43460>,
<matplotlib.collections.PathCollection at 0x7f048ed29a90>,
<matplotlib.collections.PathCollection at 0x7f048ea436d0>,
<matplotlib.collections.PathCollection at 0x7f048fd9e9d0>]

The markersize
kwarg lets you vary the point’s size by variable value. You can additionally pass size_norm
to control how the variable’s values are mapped to point sizes.
In [91]: ds.plot.scatter(x='A', y='B', hue='z', hue_style='discrete', markersize='z')
Out[91]:
[<matplotlib.collections.PathCollection at 0x7f046a00bdf0>,
<matplotlib.collections.PathCollection at 0x7f0478183d30>,
<matplotlib.collections.PathCollection at 0x7f048eb790a0>,
<matplotlib.collections.PathCollection at 0x7f048e94a760>]

Faceting is also possible
In [92]: ds.plot.scatter(x='A', y='B', col='x', row='z', hue='w', hue_style='discrete')
Out[92]: <xarray.plot.facetgrid.FacetGrid at 0x7f04780c1be0>

For more advanced scatter plots, we recommend converting the relevant data variables to a pandas DataFrame and using the extensive plotting capabilities of seaborn
.
Maps¶
To follow this section you’ll need to have Cartopy installed and working.
This script will plot the air temperature on a map.
In [93]: import cartopy.crs as ccrs
In [94]: air = xr.tutorial.open_dataset('air_temperature').air
---------------------------------------------------------------------------
FileNotFoundError Traceback (most recent call last)
<ipython-input-94-3070dce7a52d> in <module>
----> 1 air = xr.tutorial.open_dataset('air_temperature').air
/build/python-xarray-4F1RXc/python-xarray-0.15.1/xarray/tutorial.py in open_dataset(name, cache, cache_dir, github_url, branch, **kws)
76 # May want to add an option to remove it.
77 if not _os.path.isdir(longdir):
---> 78 _os.mkdir(longdir)
79
80 url = "/".join((github_url, "raw", branch, fullname))
FileNotFoundError: [Errno 2] No such file or directory: '/sbuild-nonexistent/.xarray_tutorial_data'
In [95]: ax = plt.axes(projection=ccrs.Orthographic(-80, 35))
In [96]: air.isel(time=0).plot.contourf(ax=ax, transform=ccrs.PlateCarree());
In [97]: ax.set_global(); ax.coastlines();

When faceting on maps, the projection can be transferred to the plot
function using the subplot_kws
keyword. The axes for the subplots created
by faceting are accessible in the object returned by plot
:
In [98]: p = air.isel(time=[0, 4]).plot(transform=ccrs.PlateCarree(), col='time',
....: subplot_kws={'projection': ccrs.Orthographic(-80, 35)})
....:
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-98-e84dbea1c4e3> in <module>
----> 1 p = air.isel(time=[0, 4]).plot(transform=ccrs.PlateCarree(), col='time',
2 subplot_kws={'projection': ccrs.Orthographic(-80, 35)})
NameError: name 'air' is not defined
In [99]: for ax in p.axes.flat:
....: ax.coastlines()
....: ax.gridlines()
....:
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-99-a8809283349e> in <module>
----> 1 for ax in p.axes.flat:
2 ax.coastlines()
3 ax.gridlines()
NameError: name 'p' is not defined
In [100]: plt.draw();

Details¶
Ways to Use¶
There are three ways to use the xarray plotting functionality:
Use
plot
as a convenience method for a DataArray.Access a specific plotting method from the
plot
attribute of a DataArray.Directly from the xarray plot submodule.
These are provided for user convenience; they all call the same code.
In [101]: import xarray.plot as xplt
In [102]: da = xr.DataArray(range(5))
In [103]: fig, axes = plt.subplots(ncols=2, nrows=2)
In [104]: da.plot(ax=axes[0, 0])
Out[104]: [<matplotlib.lines.Line2D at 0x7f0469ff0640>]
In [105]: da.plot.line(ax=axes[0, 1])
Out[105]: [<matplotlib.lines.Line2D at 0x7f0469c53100>]
In [106]: xplt.plot(da, ax=axes[1, 0])
Out[106]: [<matplotlib.lines.Line2D at 0x7f0469c53e20>]
In [107]: xplt.line(da, ax=axes[1, 1])
Out[107]: [<matplotlib.lines.Line2D at 0x7f0469c576a0>]
In [108]: plt.tight_layout()
In [109]: plt.draw()

Here the output is the same. Since the data is 1 dimensional the line plot was used.
The convenience method xarray.DataArray.plot()
dispatches to an appropriate
plotting function based on the dimensions of the DataArray
and whether
the coordinates are sorted and uniformly spaced. This table
describes what gets plotted:
Dimensions |
Plotting function |
1 |
|
2 |
|
Anything else |
Coordinates¶
If you’d like to find out what’s really going on in the coordinate system, read on.
In [110]: a0 = xr.DataArray(np.zeros((4, 3, 2)), dims=('y', 'x', 'z'),
.....: name='temperature')
.....:
In [111]: a0[0, 0, 0] = 1
In [112]: a = a0.isel(z=0)
In [113]: a
Out[113]:
<xarray.DataArray 'temperature' (y: 4, x: 3)>
array([[1., 0., 0.],
[0., 0., 0.],
[0., 0., 0.],
[0., 0., 0.]])
Dimensions without coordinates: y, x
The plot will produce an image corresponding to the values of the array. Hence the top left pixel will be a different color than the others. Before reading on, you may want to look at the coordinates and think carefully about what the limits, labels, and orientation for each of the axes should be.
In [114]: a.plot()
Out[114]: <matplotlib.collections.QuadMesh at 0x7f0469d05cd0>

It may seem strange that the values on the y axis are decreasing with -0.5 on the top. This is because the pixels are centered over their coordinates, and the axis labels and ranges correspond to the values of the coordinates.
Multidimensional coordinates¶
See also: Working with Multidimensional Coordinates.
You can plot irregular grids defined by multidimensional coordinates with xarray, but you’ll have to tell the plot function to use these coordinates instead of the default ones:
In [115]: lon, lat = np.meshgrid(np.linspace(-20, 20, 5), np.linspace(0, 30, 4))
In [116]: lon += lat/10
In [117]: lat += lon/10
In [118]: da = xr.DataArray(np.arange(20).reshape(4, 5), dims=['y', 'x'],
.....: coords = {'lat': (('y', 'x'), lat),
.....: 'lon': (('y', 'x'), lon)})
.....:
In [119]: da.plot.pcolormesh('lon', 'lat');

Note that in this case, xarray still follows the pixel centered convention. This might be undesirable in some cases, for example when your data is defined on a polar projection (GH781). This is why the default is to not follow this convention when plotting on a map:
In [120]: import cartopy.crs as ccrs
In [121]: ax = plt.subplot(projection=ccrs.PlateCarree());
In [122]: da.plot.pcolormesh('lon', 'lat', ax=ax);
In [123]: ax.scatter(lon, lat, transform=ccrs.PlateCarree());
In [124]: ax.coastlines(); ax.gridlines(draw_labels=True);

You can however decide to infer the cell boundaries and use the
infer_intervals
keyword:
In [125]: ax = plt.subplot(projection=ccrs.PlateCarree());
In [126]: da.plot.pcolormesh('lon', 'lat', ax=ax, infer_intervals=True);
In [127]: ax.scatter(lon, lat, transform=ccrs.PlateCarree());
In [128]: ax.coastlines(); ax.gridlines(draw_labels=True);

Note
The data model of xarray does not support datasets with cell boundaries yet. If you want to use these coordinates, you’ll have to make the plots outside the xarray framework.
One can also make line plots with multidimensional coordinates. In this case, hue
must be a dimension name, not a coordinate name.
In [129]: f, ax = plt.subplots(2, 1)
In [130]: da.plot.line(x='lon', hue='y', ax=ax[0]);
In [131]: da.plot.line(x='lon', hue='x', ax=ax[1]);
