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 xarray.DataArray objects. To plot xarray.Dataset objects simply access the relevant DataArrays, ie dset['var1']. 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.

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.
  • 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.load_dataset('air_temperature')
---------------------------------------------------------------------------
ConnectionRefusedError                    Traceback (most recent call last)
/usr/lib/python3.5/urllib/request.py in do_open(self, http_class, req, **http_conn_args)
   1253             try:
-> 1254                 h.request(req.get_method(), req.selector, req.data, headers)
   1255             except OSError as err: # timeout error

/usr/lib/python3.5/http/client.py in request(self, method, url, body, headers)
   1106         """Send a complete request to the server."""
-> 1107         self._send_request(method, url, body, headers)
   1108 

/usr/lib/python3.5/http/client.py in _send_request(self, method, url, body, headers)
   1151             body = _encode(body, 'body')
-> 1152         self.endheaders(body)
   1153 

/usr/lib/python3.5/http/client.py in endheaders(self, message_body)
   1102             raise CannotSendHeader()
-> 1103         self._send_output(message_body)
   1104 

/usr/lib/python3.5/http/client.py in _send_output(self, message_body)
    933 
--> 934         self.send(msg)
    935         if message_body is not None:

/usr/lib/python3.5/http/client.py in send(self, data)
    876             if self.auto_open:
--> 877                 self.connect()
    878             else:

/usr/lib/python3.5/http/client.py in connect(self)
   1252 
-> 1253             super().connect()
   1254 

/usr/lib/python3.5/http/client.py in connect(self)
    848         self.sock = self._create_connection(
--> 849             (self.host,self.port), self.timeout, self.source_address)
    850         self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)

/usr/lib/python3.5/socket.py in create_connection(address, timeout, source_address)
    711     if err is not None:
--> 712         raise err
    713     else:

/usr/lib/python3.5/socket.py in create_connection(address, timeout, source_address)
    702                 sock.bind(source_address)
--> 703             sock.connect(sa)
    704             return sock

ConnectionRefusedError: [Errno 111] Connection refused

During handling of the above exception, another exception occurred:

URLError                                  Traceback (most recent call last)
<ipython-input-5-3527b7d16c68> in <module>()
----> 1 airtemps = xr.tutorial.load_dataset('air_temperature')

/build/python-xarray-sDEpzA/python-xarray-0.9.2/xarray/tutorial.py in load_dataset(name, cache, cache_dir, github_url, **kws)
     54 
     55         url = '/'.join((github_url, 'raw', 'master', fullname))
---> 56         _urlretrieve(url, localfile)
     57 
     58     ds = _open_dataset(localfile, **kws).load()

/usr/lib/python3.5/urllib/request.py in urlretrieve(url, filename, reporthook, data)
    186     url_type, path = splittype(url)
    187 
--> 188     with contextlib.closing(urlopen(url, data)) as fp:
    189         headers = fp.info()
    190 

/usr/lib/python3.5/urllib/request.py in urlopen(url, data, timeout, cafile, capath, cadefault, context)
    161     else:
    162         opener = _opener
--> 163     return opener.open(url, data, timeout)
    164 
    165 def install_opener(opener):

/usr/lib/python3.5/urllib/request.py in open(self, fullurl, data, timeout)
    464             req = meth(req)
    465 
--> 466         response = self._open(req, data)
    467 
    468         # post-process response

/usr/lib/python3.5/urllib/request.py in _open(self, req, data)
    482         protocol = req.type
    483         result = self._call_chain(self.handle_open, protocol, protocol +
--> 484                                   '_open', req)
    485         if result:
    486             return result

/usr/lib/python3.5/urllib/request.py in _call_chain(self, chain, kind, meth_name, *args)
    442         for handler in handlers:
    443             func = getattr(handler, meth_name)
--> 444             result = func(*args)
    445             if result is not None:
    446                 return result

/usr/lib/python3.5/urllib/request.py in https_open(self, req)
   1295         def https_open(self, req):
   1296             return self.do_open(http.client.HTTPSConnection, req,
-> 1297                 context=self._context, check_hostname=self._check_hostname)
   1298 
   1299         https_request = AbstractHTTPHandler.do_request_

/usr/lib/python3.5/urllib/request.py in do_open(self, http_class, req, **http_conn_args)
   1254                 h.request(req.get_method(), req.selector, req.data, headers)
   1255             except OSError as err: # timeout error
-> 1256                 raise URLError(err)
   1257             r = h.getresponse()
   1258         except:

URLError: <urlopen error [Errno 111] Connection refused>

In [6]: airtemps
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-6-97bf1d613dea> 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-ddb2b18dbefa> in <module>()
----> 1 air = airtemps.air - 273.15

NameError: name 'airtemps' is not defined

One Dimension

Simple Example

xarray uses the coordinate name to label the x axis.

In [8]: air1d = air.isel(lat=10, lon=10)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-8-135df630e7d8> in <module>()
----> 1 air1d = air.isel(lat=10, lon=10)

NameError: name 'air' is not defined

In [9]: air1d.plot()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-9-d18100d4fbc9> in <module>()
----> 1 air1d.plot()

NameError: name 'air1d' is not defined
_images/plotting_1d_simple.png

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 [10]: air1d[:200].plot.line('b-^')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-10-19f2d4f35560> in <module>()
----> 1 air1d[:200].plot.line('b-^')

NameError: name 'air1d' is not defined
_images/plotting_1d_additional_args.png

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 [11]: air1d[:200].plot.line(color='purple', marker='o')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-11-6cf466530841> in <module>()
----> 1 air1d[:200].plot.line(color='purple', marker='o')

NameError: name 'air1d' is not defined
_images/plotting_example_sin3.png

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 [12]: fig, axes = plt.subplots(ncols=2)

In [13]: axes
Out[13]: 
array([<matplotlib.axes._subplots.AxesSubplot object at 0x7f41c89664a8>,
       <matplotlib.axes._subplots.AxesSubplot object at 0x7f41c8613d68>], dtype=object)

In [14]: air1d.plot(ax=axes[0])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-14-539e96723ed9> in <module>()
----> 1 air1d.plot(ax=axes[0])

NameError: name 'air1d' is not defined

In [15]: air1d.plot.hist(ax=axes[1])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-15-0361034e2c57> in <module>()
----> 1 air1d.plot.hist(ax=axes[1])

NameError: name 'air1d' is not defined

In [16]: plt.tight_layout()

In [17]: plt.show()
_images/plotting_example_existing_axes.png

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 [18]: air1d.plot(aspect=2, size=3)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-18-7cb9ed48b9b0> in <module>()
----> 1 air1d.plot(aspect=2, size=3)

NameError: name 'air1d' is not defined

In [19]: plt.tight_layout()
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
<ipython-input-19-d4373de374a7> in <module>()
----> 1 plt.tight_layout()

/usr/lib/python3/dist-packages/matplotlib/pyplot.py in tight_layout(pad, h_pad, w_pad, rect)
   1405 
   1406     fig = gcf()
-> 1407     fig.tight_layout(pad=pad, h_pad=h_pad, w_pad=w_pad, rect=rect)
   1408 
   1409 

/usr/lib/python3/dist-packages/matplotlib/figure.py in tight_layout(self, renderer, pad, h_pad, w_pad, rect)
   1750                                          renderer,
   1751                                          pad=pad, h_pad=h_pad, w_pad=w_pad,
-> 1752                                          rect=rect)
   1753 
   1754         self.subplots_adjust(**kwargs)

/usr/lib/python3/dist-packages/matplotlib/tight_layout.py in get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer, pad, h_pad, w_pad, rect)
    320         subplots.append(ax)
    321 
--> 322     max_nrows = max(nrows_list)
    323     max_ncols = max(ncols_list)
    324 

ValueError: max() arg is an empty sequence
_images/plotting_example_size_and_aspect.png

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.

Two Dimensions

Simple Example

The default method xarray.DataArray.plot() sees that the data is 2 dimensional and calls xarray.plot.pcolormesh().

In [20]: air2d = air.isel(time=500)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-20-a09591e4acb9> in <module>()
----> 1 air2d = air.isel(time=500)

NameError: name 'air' is not defined

In [21]: air2d.plot()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-21-e07efde17aab> in <module>()
----> 1 air2d.plot()

NameError: name 'air2d' is not defined
_images/2d_simple.png

All 2d plots in xarray allow the use of the keyword arguments yincrease and xincrease.

In [22]: air2d.plot(yincrease=False)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-22-aee11e44ea8c> in <module>()
----> 1 air2d.plot(yincrease=False)

NameError: name 'air2d' is not defined
_images/2d_simple_yincrease.png

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 [23]: bad_air2d = air2d.copy()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-23-422d52248f67> in <module>()
----> 1 bad_air2d = air2d.copy()

NameError: name 'air2d' is not defined

In [24]: bad_air2d[dict(lat=slice(0, 10), lon=slice(0, 25))] = np.nan
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-24-26e6fd241dca> in <module>()
----> 1 bad_air2d[dict(lat=slice(0, 10), lon=slice(0, 25))] = np.nan

NameError: name 'bad_air2d' is not defined

In [25]: bad_air2d.plot()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-25-0191722eda1f> in <module>()
----> 1 bad_air2d.plot()

NameError: name 'bad_air2d' is not defined
_images/plotting_missing_values.png

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 [26]: b = air2d.copy()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-26-1a5be76ab043> in <module>()
----> 1 b = air2d.copy()

NameError: name 'air2d' is not defined

# Apply a nonlinear transformation to one of the coords
In [27]: b.coords['lat'] = np.log(b.coords['lat'])
---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
/build/python-xarray-sDEpzA/python-xarray-0.9.2/xarray/core/dataarray.py in _getitem_coord(self, key)
    455         try:
--> 456             var = self._coords[key]
    457         except KeyError:

KeyError: 'lat'

During handling of the above exception, another exception occurred:

KeyError                                  Traceback (most recent call last)
<ipython-input-27-498a04a8c870> in <module>()
----> 1 b.coords['lat'] = np.log(b.coords['lat'])

/build/python-xarray-sDEpzA/python-xarray-0.9.2/xarray/core/coordinates.py in __getitem__(self, key)
    189 
    190     def __getitem__(self, key):
--> 191         return self._data._getitem_coord(key)
    192 
    193     def _update_coords(self, coords):

/build/python-xarray-sDEpzA/python-xarray-0.9.2/xarray/core/dataarray.py in _getitem_coord(self, key)
    458             dim_sizes = dict(zip(self.dims, self.shape))
    459             _, key, var = _get_virtual_variable(
--> 460                 self._coords, key, self._level_coords, dim_sizes)
    461 
    462         return self._replace_maybe_drop_dims(var, name=key)

/build/python-xarray-sDEpzA/python-xarray-0.9.2/xarray/core/dataset.py in _get_virtual_variable(variables, key, level_vars, dim_sizes)
     68         ref_var = dim_var.to_index_variable().get_level_variable(ref_name)
     69     else:
---> 70         ref_var = variables[ref_name]
     71 
     72     if var_name is None:

KeyError: 'lat'

In [28]: b.plot()
Out[28]: [<matplotlib.lines.Line2D at 0x7f41d61eb828>]
_images/plotting_nonuniform_coords.png

Calling Matplotlib

Since this is a thin wrapper around matplotlib, all the functionality of matplotlib is available.

In [29]: air2d.plot(cmap=plt.cm.Blues)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-29-3ff13a5e932b> in <module>()
----> 1 air2d.plot(cmap=plt.cm.Blues)

NameError: name 'air2d' is not defined

In [30]: plt.title('These colors prove North America\nhas fallen in the ocean')
Out[30]: <matplotlib.text.Text at 0x7f41d4cbf7b8>

In [31]: plt.ylabel('latitude')
Out[31]: <matplotlib.text.Text at 0x7f41c8b33c88>

In [32]: plt.xlabel('longitude')
Out[32]: <matplotlib.text.Text at 0x7f41d502acf8>

In [33]: plt.tight_layout()

In [34]: plt.show()
_images/plotting_2d_call_matplotlib.png

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 [35]: plt.xlabel('Never gonna see this.')
Out[35]: <matplotlib.text.Text at 0x7f41c8262cc0>

In [36]: air2d.plot()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-36-e07efde17aab> in <module>()
----> 1 air2d.plot()

NameError: name 'air2d' is not defined

In [37]: plt.show()
_images/plotting_2d_call_matplotlib2.png

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 [38]: airtemps.air.isel(time=0).plot()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-38-8144c2998176> in <module>()
----> 1 airtemps.air.isel(time=0).plot()

NameError: name 'airtemps' is not defined
_images/plotting_kelvin.png

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 [39]: air_outliers = airtemps.air.isel(time=0).copy()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-39-33d7f88a80d6> in <module>()
----> 1 air_outliers = airtemps.air.isel(time=0).copy()

NameError: name 'airtemps' is not defined

In [40]: air_outliers[0, 0] = 100
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-40-670ca642b62f> in <module>()
----> 1 air_outliers[0, 0] = 100

NameError: name 'air_outliers' is not defined

In [41]: air_outliers[-1, -1] = 400
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-41-292cb47d553c> in <module>()
----> 1 air_outliers[-1, -1] = 400

NameError: name 'air_outliers' is not defined

In [42]: air_outliers.plot()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-42-b6909f9304af> in <module>()
----> 1 air_outliers.plot()

NameError: name 'air_outliers' is not defined
_images/plotting_robust1.png

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 [43]: air_outliers.plot(robust=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-43-fab29a3e3a92> in <module>()
----> 1 air_outliers.plot(robust=True)

NameError: name 'air_outliers' is not defined
_images/plotting_robust2.png

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 [44]: air2d.plot(levels=8)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-44-1e5e1bceae75> in <module>()
----> 1 air2d.plot(levels=8)

NameError: name 'air2d' is not defined
_images/plotting_discrete_levels.png

It is also possible to use a list of levels to specify the boundaries of the discrete colormap:

In [45]: air2d.plot(levels=[0, 12, 18, 30])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-45-6ac464986fde> in <module>()
----> 1 air2d.plot(levels=[0, 12, 18, 30])

NameError: name 'air2d' is not defined
_images/plotting_listed_levels.png

You can also specify a list of discrete colors through the colors argument:

In [46]: flatui = ["#9b59b6", "#3498db", "#95a5a6", "#e74c3c", "#34495e", "#2ecc71"]

In [47]: air2d.plot(levels=[0, 12, 18, 30], colors=flatui)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-47-3c244310ff51> in <module>()
----> 1 air2d.plot(levels=[0, 12, 18, 30], colors=flatui)

NameError: name 'air2d' is not defined
_images/plotting_custom_colors_levels.png

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 [48]: air2d.plot(levels=10, cmap='husl')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-48-f3abd1bcfb90> in <module>()
----> 1 air2d.plot(levels=10, cmap='husl')

NameError: name 'air2d' is not defined
_images/plotting_seaborn_palette.png

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.

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 seperate 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 [49]: t = air.isel(time=slice(0, 365 * 4, 250))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-49-836ac319e2bc> in <module>()
----> 1 t = air.isel(time=slice(0, 365 * 4, 250))

NameError: name 'air' is not defined

In [50]: t.coords
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-50-9e473e044a51> in <module>()
----> 1 t.coords

NameError: name 't' is not defined

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 [51]: g_simple = t.plot(x='lon', y='lat', col='time', col_wrap=3)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-51-414f9c710f04> in <module>()
----> 1 g_simple = t.plot(x='lon', y='lat', col='time', col_wrap=3)

NameError: name 't' is not defined
_images/plot_facet_dataarray.png

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 [52]: t2 = t.isel(time=slice(0, 2))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-52-60564aec5d20> in <module>()
----> 1 t2 = t.isel(time=slice(0, 2))

NameError: name 't' is not defined

In [53]: t4d = xr.concat([t2, t2 + 40], pd.Index(['normal', 'hot'], name='fourth_dim'))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-53-e7ee6cac0f23> 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 [54]: t4d.coords
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-54-85c7d6d4d520> in <module>()
----> 1 t4d.coords

NameError: name 't4d' is not defined

In [55]: t4d.plot(x='lon', y='lat', col='time', row='fourth_dim')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-55-0f6208e877ae> in <module>()
----> 1 t4d.plot(x='lon', y='lat', col='time', row='fourth_dim')

NameError: name 't4d' is not defined
_images/plot_facet_4d.png

Other features

Faceted plotting supports other arguments common to xarray 2d plots.

In [56]: hasoutliers = t.isel(time=slice(0, 5)).copy()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-56-86184577316b> in <module>()
----> 1 hasoutliers = t.isel(time=slice(0, 5)).copy()

NameError: name 't' is not defined

In [57]: hasoutliers[0, 0, 0] = -100
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-57-371026ce7e96> in <module>()
----> 1 hasoutliers[0, 0, 0] = -100

NameError: name 'hasoutliers' is not defined

In [58]: hasoutliers[-1, -1, -1] = 400
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-58-0a4baae54127> in <module>()
----> 1 hasoutliers[-1, -1, -1] = 400

NameError: name 'hasoutliers' is not defined

In [59]: g = hasoutliers.plot.pcolormesh('lon', 'lat', col='time', col_wrap=3,
   ....:                                 robust=True, cmap='viridis')
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-59-ffeabd3a15e9> in <module>()
----> 1 g = hasoutliers.plot.pcolormesh('lon', 'lat', col='time', col_wrap=3,
      2                                 robust=True, cmap='viridis')

NameError: name 'hasoutliers' is not defined
_images/plot_facet_robust.png

FacetGrid Objects

xarray.plot.FacetGrid is 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 [60]: g.axes
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-60-08aa76028cdf> in <module>()
----> 1 g.axes

NameError: name 'g' is not defined

In [61]: g.name_dicts
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-61-dcdc9a034d93> 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 [62]: g.data.loc[g.name_dicts[0, 0]]
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-62-22a0c8bff048> 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 [63]: g = t.plot.imshow('lon', 'lat', col='time', col_wrap=3, robust=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-63-23d6dac48bc1> in <module>()
----> 1 g = t.plot.imshow('lon', 'lat', col='time', col_wrap=3, robust=True)

NameError: name 't' is not defined

In [64]: for i, ax in enumerate(g.axes.flat):
   ....:     ax.set_title('Air Temperature %d' % i)
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-64-16e93ad56fb7> in <module>()
----> 1 for i, ax in enumerate(g.axes.flat):
      2     ax.set_title('Air Temperature %d' % i)
      3 

NameError: name 'g' is not defined

In [65]: bottomright = g.axes[-1, -1]
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-65-8d38f09ba20e> in <module>()
----> 1 bottomright = g.axes[-1, -1]

NameError: name 'g' is not defined

In [66]: bottomright.annotate('bottom right', (240, 40))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-66-6872c49f27d5> in <module>()
----> 1 bottomright.annotate('bottom right', (240, 40))

NameError: name 'bottomright' is not defined

In [67]: plt.show()
_images/plot_facet_iterator.png

TODO: add an example of using the map method to plot dataset variables (e.g., with plt.quiver).

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 [68]: import cartopy.crs as ccrs

In [69]: air = xr.tutorial.load_dataset('air_temperature').air
---------------------------------------------------------------------------
ConnectionRefusedError                    Traceback (most recent call last)
/usr/lib/python3.5/urllib/request.py in do_open(self, http_class, req, **http_conn_args)
   1253             try:
-> 1254                 h.request(req.get_method(), req.selector, req.data, headers)
   1255             except OSError as err: # timeout error

/usr/lib/python3.5/http/client.py in request(self, method, url, body, headers)
   1106         """Send a complete request to the server."""
-> 1107         self._send_request(method, url, body, headers)
   1108 

/usr/lib/python3.5/http/client.py in _send_request(self, method, url, body, headers)
   1151             body = _encode(body, 'body')
-> 1152         self.endheaders(body)
   1153 

/usr/lib/python3.5/http/client.py in endheaders(self, message_body)
   1102             raise CannotSendHeader()
-> 1103         self._send_output(message_body)
   1104 

/usr/lib/python3.5/http/client.py in _send_output(self, message_body)
    933 
--> 934         self.send(msg)
    935         if message_body is not None:

/usr/lib/python3.5/http/client.py in send(self, data)
    876             if self.auto_open:
--> 877                 self.connect()
    878             else:

/usr/lib/python3.5/http/client.py in connect(self)
   1252 
-> 1253             super().connect()
   1254 

/usr/lib/python3.5/http/client.py in connect(self)
    848         self.sock = self._create_connection(
--> 849             (self.host,self.port), self.timeout, self.source_address)
    850         self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)

/usr/lib/python3.5/socket.py in create_connection(address, timeout, source_address)
    711     if err is not None:
--> 712         raise err
    713     else:

/usr/lib/python3.5/socket.py in create_connection(address, timeout, source_address)
    702                 sock.bind(source_address)
--> 703             sock.connect(sa)
    704             return sock

ConnectionRefusedError: [Errno 111] Connection refused

During handling of the above exception, another exception occurred:

URLError                                  Traceback (most recent call last)
<ipython-input-69-e477c589252c> in <module>()
----> 1 air = xr.tutorial.load_dataset('air_temperature').air

/build/python-xarray-sDEpzA/python-xarray-0.9.2/xarray/tutorial.py in load_dataset(name, cache, cache_dir, github_url, **kws)
     54 
     55         url = '/'.join((github_url, 'raw', 'master', fullname))
---> 56         _urlretrieve(url, localfile)
     57 
     58     ds = _open_dataset(localfile, **kws).load()

/usr/lib/python3.5/urllib/request.py in urlretrieve(url, filename, reporthook, data)
    186     url_type, path = splittype(url)
    187 
--> 188     with contextlib.closing(urlopen(url, data)) as fp:
    189         headers = fp.info()
    190 

/usr/lib/python3.5/urllib/request.py in urlopen(url, data, timeout, cafile, capath, cadefault, context)
    161     else:
    162         opener = _opener
--> 163     return opener.open(url, data, timeout)
    164 
    165 def install_opener(opener):

/usr/lib/python3.5/urllib/request.py in open(self, fullurl, data, timeout)
    464             req = meth(req)
    465 
--> 466         response = self._open(req, data)
    467 
    468         # post-process response

/usr/lib/python3.5/urllib/request.py in _open(self, req, data)
    482         protocol = req.type
    483         result = self._call_chain(self.handle_open, protocol, protocol +
--> 484                                   '_open', req)
    485         if result:
    486             return result

/usr/lib/python3.5/urllib/request.py in _call_chain(self, chain, kind, meth_name, *args)
    442         for handler in handlers:
    443             func = getattr(handler, meth_name)
--> 444             result = func(*args)
    445             if result is not None:
    446                 return result

/usr/lib/python3.5/urllib/request.py in https_open(self, req)
   1295         def https_open(self, req):
   1296             return self.do_open(http.client.HTTPSConnection, req,
-> 1297                 context=self._context, check_hostname=self._check_hostname)
   1298 
   1299         https_request = AbstractHTTPHandler.do_request_

/usr/lib/python3.5/urllib/request.py in do_open(self, http_class, req, **http_conn_args)
   1254                 h.request(req.get_method(), req.selector, req.data, headers)
   1255             except OSError as err: # timeout error
-> 1256                 raise URLError(err)
   1257             r = h.getresponse()
   1258         except:

URLError: <urlopen error [Errno 111] Connection refused>

In [70]: ax = plt.axes(projection=ccrs.Orthographic(-80, 35))

In [71]: air.isel(time=0).plot.contourf(ax=ax, transform=ccrs.PlateCarree());

In [72]: ax.set_global(); ax.coastlines();
_build/html/_static/plotting_maps_cartopy.png

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 [73]: 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-73-4e7f86d4c31a> 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 [74]: for ax in p.axes.flat:
   ....:     ax.coastlines()
   ....:     ax.gridlines()
   ....: 
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-74-5e6b1456ede2> in <module>()
----> 1 for ax in p.axes.flat:
      2     ax.coastlines()
      3     ax.gridlines()
      4 

NameError: name 'p' is not defined

In [75]: plt.show();
_images/plotting_maps_cartopy_facetting.png

Details

Ways to Use

There are three ways to use the xarray plotting functionality:

  1. Use plot as a convenience method for a DataArray.
  2. Access a specific plotting method from the plot attribute of a DataArray.
  3. Directly from the xarray plot submodule.

These are provided for user convenience; they all call the same code.

In [76]: import xarray.plot as xplt

In [77]: da = xr.DataArray(range(5))

In [78]: fig, axes = plt.subplots(ncols=2, nrows=2)

In [79]: da.plot(ax=axes[0, 0])
Out[79]: [<matplotlib.lines.Line2D at 0x7f41c85c1c88>]

In [80]: da.plot.line(ax=axes[0, 1])
Out[80]: [<matplotlib.lines.Line2D at 0x7f41c85c19e8>]

In [81]: xplt.plot(da, ax=axes[1, 0])
Out[81]: [<matplotlib.lines.Line2D at 0x7f41c896cf98>]

In [82]: xplt.line(da, ax=axes[1, 1])
Out[82]: [<matplotlib.lines.Line2D at 0x7f41c896c278>]

In [83]: plt.tight_layout()

In [84]: plt.show()
_images/plotting_ways_to_use.png

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 xarray.plot.line()
2 xarray.plot.pcolormesh()
Anything else xarray.plot.hist()

Coordinates

If you’d like to find out what’s really going on in the coordinate system, read on.

In [85]: a0 = xr.DataArray(np.zeros((4, 3, 2)), dims=('y', 'x', 'z'),
   ....:                   name='temperature')
   ....: 

In [86]: a0[0, 0, 0] = 1

In [87]: a = a0.isel(z=0)

In [88]: a
Out[88]: 
<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 [89]: a.plot()
Out[89]: <matplotlib.collections.QuadMesh at 0x7f41c80ecb38>
_images/plotting_example_2d_simple.png

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 [90]: lon, lat = np.meshgrid(np.linspace(-20, 20, 5), np.linspace(0, 30, 4))

In [91]: lon += lat/10

In [92]: lat += lon/10

In [93]: da = xr.DataArray(np.arange(20).reshape(4, 5), dims=['y', 'x'],
   ....:                   coords = {'lat': (('y', 'x'), lat),
   ....:                             'lon': (('y', 'x'), lon)})
   ....: 

In [94]: da.plot.pcolormesh('lon', 'lat');
_images/plotting_example_2d_irreg.png

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 [95]: import cartopy.crs as ccrs

In [96]: ax = plt.subplot(projection=ccrs.PlateCarree());

In [97]: da.plot.pcolormesh('lon', 'lat', ax=ax);

In [98]: ax.scatter(lon, lat, transform=ccrs.PlateCarree());

In [99]: ax.coastlines(); ax.gridlines(draw_labels=True);
_build/html/_static/plotting_example_2d_irreg_map.png

You can however decide to infer the cell boundaries and use the infer_intervals keyword:

In [100]: ax = plt.subplot(projection=ccrs.PlateCarree());

In [101]: da.plot.pcolormesh('lon', 'lat', ax=ax, infer_intervals=True);

In [102]: ax.scatter(lon, lat, transform=ccrs.PlateCarree());

In [103]: ax.coastlines(); ax.gridlines(draw_labels=True);
_build/html/_static/plotting_example_2d_irreg_map_infer.png

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.