<a id="plotting"></a>

# 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`](../generated/xarray.DataArray.html.md#xarray.DataArray) objects.
To plot [`Dataset`](../generated/xarray.Dataset.html.md#xarray.Dataset) objects
simply access the relevant DataArrays, i.e. `dset['var1']`.
Dataset specific plotting routines are also available (see [Datasets](#plot-dataset)).
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](https://matplotlib.org/) 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](https://github.com/SciTools/nc-time-axis) v1.3.0 or later
needs to be installed.

For more extensive plotting applications consider the following projects:

- [Seaborn](https://seaborn.pydata.org/): “provides
  a high-level interface for drawing attractive statistical graphics.”
  Integrates well with pandas.
- [HoloViews](https://holoviews.org/)
  and [GeoViews](https://geoviews.org/): “Composable, declarative
  data structures for building even complex visualizations easily.” Includes
  native support for xarray objects.
- [hvplot](https://hvplot.pyviz.org/): `hvplot` makes it very easy to produce
  dynamic plots (backed by `Holoviews` or `Geoviews`) by adding a `hvplot`
  accessor to DataArrays.
- [Cartopy](https://cartopy.readthedocs.io/stable/): Provides cartographic
  tools.

### Imports

The following imports are necessary for all of the examples.

```ipython3
import cartopy.crs as ccrs
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import xarray as xr
```

For these examples we’ll use the North American air temperature dataset.

```ipython3
airtemps = xr.tutorial.open_dataset("air_temperature")
airtemps
```

```ipython3
# Convert to celsius
air = airtemps.air - 273.15

# copy attributes to get nice figure labels and change Kelvin to Celsius
air.attrs = airtemps.air.attrs
air.attrs["units"] = "deg C"
```

#### NOTE
Until [GH1614](https://github.com/pydata/xarray/issues/1614) 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()`](../generated/xarray.DataArray.plot.html.md#xarray.DataArray.plot) method.

```ipython3
air1d = air.isel(lat=10, lon=10)
air1d.plot();
```

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](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch03s03.html).
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`.

```ipython3
air1d.attrs
```

#### Additional Arguments

Additional arguments are passed directly to the matplotlib function which
does the work.
For example, [`xarray.plot.line()`](../generated/xarray.plot.line.html.md#xarray.plot.line) calls
[matplotlib.pyplot.plot](https://matplotlib.org/api/pyplot_api.html#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:

```ipython3
air1d[:200].plot.line("b-^");
```

#### 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.

```ipython3
air1d[:200].plot.line(color="purple", marker="o");
```

#### 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 `axs` is an array consisting of the left and right
axes created by `plt.subplots`.

```ipython3
fig, axs = plt.subplots(ncols=2, figsize=(12, 4), layout="constrained")

print(axs)

air1d.plot(ax=axs[0])
air1d.plot.hist(ax=axs[1]);
```

```myst-ansi
[<Axes: > <Axes: >]
```

On the right is a histogram created by [`xarray.plot.hist()`](../generated/xarray.plot.hist.html.md#xarray.plot.hist).

<a id="plotting-figsize"></a>

#### 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)`:

```ipython3
air1d.plot(aspect=2, size=3);
```

This feature also works with [Faceting](#plotting-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](https://github.com/mwaskom/seaborn/issues/746).

<a id="plotting-multiplelines"></a>

#### Determine x-axis values

Per default dimension coordinates are used for the x-axis (here the time coordinates).
However, you can also use non-dimension coordinates, MultiIndex levels, and dimensions
without coordinates along the x-axis. To illustrate this, let’s calculate a ‘decimal day’ (epoch)
from the time and assign it as a non-dimension coordinate:

```ipython3
decimal_day = (air1d.time - air1d.time[0]) / pd.Timedelta("1D")
air1d_multi = air1d.assign_coords(decimal_day=("time", decimal_day.data))
air1d_multi
```

To use `'decimal_day'` as x coordinate it must be explicitly specified:

```ipython3
air1d_multi.plot(x="decimal_day");
```

Creating a new MultiIndex named `'date'` from `'time'` and `'decimal_day'`,
it is also possible to use a MultiIndex level as x-axis:

```ipython3
air1d_multi = air1d_multi.set_index(date=("time", "decimal_day"))
air1d_multi.plot(x="decimal_day");
```

Finally, if a dataset does not have any coordinates it enumerates all data points:

```ipython3
air1d_multi = air1d_multi.drop_vars(["date", "time", "decimal_day"])
air1d_multi.plot();
```

The same applies to 2D plots below.

#### Multiple lines showing variation along a dimension

It is possible to make line plots of two-dimensional data by calling [`xarray.plot.line()`](../generated/xarray.plot.line.html.md#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:

```ipython3
air.isel(lon=10, lat=[19, 21, 22]).plot.line(x="time");
```

It is required to explicitly specify either

1. `x`: the dimension to be used for the x-axis, or
2. `hue`: 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()`](../generated/xarray.plot.line.html.md#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.

```ipython3
air.isel(time=10, lon=[10, 11]).plot(y="lat", hue="lon");
```

#### Step plots

As an alternative, also a step plot similar to matplotlib’s `plt.step` can be
made using 1D data.

```ipython3
air1d[:20].plot.step(where="mid");
```

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()`](../generated/xarray.Dataset.groupby_bins.html.md#xarray.Dataset.groupby_bins).

```ipython3
air_grp = air.mean(["time", "lon"]).groupby_bins("lat", [0, 23.5, 66.5, 90])
air_mean = air_grp.mean()
air_std = air_grp.std()
air_mean.plot.step()
(air_mean + air_std).plot.step(ls=":")
(air_mean - air_std).plot.step(ls=":")
plt.ylim(-20, 30)
plt.title("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.

```ipython3
air.isel(time=10, lon=[10, 11]).plot.line(
    y="lat", hue="lon", xincrease=False, yincrease=False
);
```

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 `ax.set_(x,y)scale()`,
`ax.set_(x,y)ticks()`, `ax.set_(x,y)lim()`, respectively.

### Two Dimensions

#### Simple Example

The default method [`DataArray.plot()`](../generated/xarray.DataArray.plot.html.md#xarray.DataArray.plot) calls [`xarray.plot.pcolormesh()`](../generated/xarray.plot.pcolormesh.html.md#xarray.plot.pcolormesh)
by default when the data is two-dimensional.

```ipython3
air2d = air.isel(time=500)
air2d.plot();
```

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

```ipython3
air2d.plot(yincrease=False);
```

#### NOTE
We use [`xarray.plot.pcolormesh()`](../generated/xarray.plot.pcolormesh.html.md#xarray.plot.pcolormesh) as the default two-dimensional plot
method because it is more flexible than [`xarray.plot.imshow()`](../generated/xarray.plot.imshow.html.md#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](computation.html.md#missing-values).

```ipython3
bad_air2d = air2d.copy()
bad_air2d[dict(lat=slice(0, 10), lon=slice(0, 25))] = np.nan
bad_air2d.plot();
```

#### Nonuniform Coordinates

It’s not necessary for the coordinates to be evenly spaced. Both
[`xarray.plot.pcolormesh()`](../generated/xarray.plot.pcolormesh.html.md#xarray.plot.pcolormesh) (default) and [`xarray.plot.contourf()`](../generated/xarray.plot.contourf.html.md#xarray.plot.contourf) can
produce plots with nonuniform coordinates.

```ipython3
b = air2d.copy()
# Apply a nonlinear transformation to one of the coords
b.coords["lat"] = np.log(b.coords["lat"])

b.plot();
```

#### Other types of plot

There are several other options for plotting 2D data.

Contour plot using [`DataArray.plot.contour()`](../generated/xarray.DataArray.plot.contour.html.md#xarray.DataArray.plot.contour)

```ipython3
air2d.plot.contour();
```

Filled contour plot using [`DataArray.plot.contourf()`](../generated/xarray.DataArray.plot.contourf.html.md#xarray.DataArray.plot.contourf)

```ipython3
air2d.plot.contourf();
```

Surface plot using [`DataArray.plot.surface()`](../generated/xarray.DataArray.plot.surface.html.md#xarray.DataArray.plot.surface)

```ipython3
# transpose just to make the example look a bit nicer
air2d.T.plot.surface();
```

#### Calling Matplotlib

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

```ipython3
air2d.plot(cmap=plt.cm.Blues)
plt.title("These colors prove North America\nhas fallen in the ocean")
plt.ylabel("latitude")
plt.xlabel("longitude");
```

#### 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.
See the cell below:

```ipython3
plt.xlabel("Never gonna see this.")
air2d.plot();
```

#### 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:

```ipython3
airtemps.air.isel(time=0).plot();
```

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.

<a id="robust-plotting"></a>

#### 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.

```ipython3
air_outliers = airtemps.air.isel(time=0).copy()
air_outliers[0, 0] = 100
air_outliers[-1, -1] = 400

air_outliers.plot();
```

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.

```ipython3
air_outliers.plot(robust=True);
```

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:

```ipython3
air2d.plot(levels=8);
```

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

```ipython3
air2d.plot(levels=[0, 12, 18, 30]);
```

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

```ipython3
flatui = ["#9b59b6", "#3498db", "#95a5a6", "#e74c3c", "#34495e", "#2ecc71"]
air2d.plot(levels=[0, 12, 18, 30], colors=flatui);
```

Finally, if you have [Seaborn](https://seaborn.pydata.org/)
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).

```ipython3
air2d.plot(levels=10, cmap="husl");
```

<a id="plotting-faceting"></a>

### 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 or 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.

```ipython3
t = air.isel(time=slice(0, 365 * 4, 250))
t.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`](../generated/xarray.plot.FacetGrid.html.md#xarray.plot.FacetGrid) object.

```ipython3
g_simple = t.plot(x="lon", y="lat", col="time", col_wrap=3);
```

Faceting also works for line plots.

```ipython3
g_simple_line = t.isel(lat=slice(0, None, 4)).plot(
    x="lon", hue="lat", col="time", col_wrap=3
);
```

#### 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.

```ipython3
t2 = t.isel(time=slice(0, 2))
t4d = xr.concat([t2, t2 + 40], pd.Index(["normal", "hot"], name="fourth_dim"))
# This is a 4d array
t4d.coords

t4d.plot(x="lon", y="lat", col="time", row="fourth_dim");
```

#### Other features

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

```ipython3
hasoutliers = t.isel(time=slice(0, 5)).copy()
hasoutliers[0, 0, 0] = -100
hasoutliers[-1, -1, -1] = 400

g = hasoutliers.plot.pcolormesh(
    x="lon",
    y="lat",
    col="time",
    col_wrap=3,
    robust=True,
    cmap="viridis",
    cbar_kwargs={"label": "this has outliers"},
)
```

#### FacetGrid Objects

The object returned, `g` in the above examples, is a [`FacetGrid`](../generated/xarray.plot.FacetGrid.html.md#xarray.plot.FacetGrid) object
that links a [`DataArray`](../generated/xarray.DataArray.html.md#xarray.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](https://seaborn.pydata.org/tutorial/axis_grids.html).
The structure is contained within the `axs` and `name_dicts`
attributes, both 2d NumPy object arrays.

```ipython3
g.axs
```

```ipython3
g.name_dicts
```

It’s possible to select the [`xarray.DataArray`](../generated/xarray.DataArray.html.md#xarray.DataArray) or
[`xarray.Dataset`](../generated/xarray.Dataset.html.md#xarray.Dataset) corresponding to the FacetGrid through the
`name_dicts`.

```ipython3
g.data.loc[g.name_dicts[0, 0]]
```

Here is an example of using the lower level API and then modifying the axes after
they have been plotted.

```ipython3
g = t.plot.imshow(x="lon", y="lat", col="time", col_wrap=3, robust=True)

for i, ax in enumerate(g.axs.flat):
    ax.set_title("Air Temperature %d" % i)

bottomright = g.axs[-1, -1]
bottomright.annotate("bottom right", (240, 40));
```

[`FacetGrid`](../generated/xarray.plot.FacetGrid.html.md#xarray.plot.FacetGrid) objects have methods that let you customize the automatically generated
axis labels, axis ticks and plot titles. See [`set_titles()`](../generated/xarray.plot.FacetGrid.set_titles.html.md#xarray.plot.FacetGrid.set_titles),
[`set_xlabels()`](../generated/xarray.plot.FacetGrid.set_xlabels.html.md#xarray.plot.FacetGrid.set_xlabels), [`set_ylabels()`](../generated/xarray.plot.FacetGrid.set_ylabels.html.md#xarray.plot.FacetGrid.set_ylabels) and
[`set_ticks()`](../generated/xarray.plot.FacetGrid.set_ticks.html.md#xarray.plot.FacetGrid.set_ticks) for more information.
Plotting functions can be applied to each subset of the data by calling
[`map_dataarray()`](../generated/xarray.plot.FacetGrid.map_dataarray.html.md#xarray.plot.FacetGrid.map_dataarray) or to each subplot by calling [`map()`](../generated/xarray.plot.FacetGrid.map.html.md#xarray.plot.FacetGrid.map).

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

<a id="plot-dataset"></a>

## Datasets

Xarray has limited support for plotting Dataset variables against each other.
Consider this dataset

```ipython3
ds = xr.tutorial.scatter_example_dataset(seed=42)
ds
```

### Scatter

Let’s plot the `A` DataArray as a function of the `y` coord

```ipython3
with xr.set_options(display_expand_data=False):
    display(ds.A)
```

```ipython3
ds.A.plot.scatter(x="y");
```

Same plot can be displayed using the dataset:

```ipython3
ds.plot.scatter(x="y", y="A");
```

Now suppose we want to scatter the `A` DataArray against the `B` DataArray

```ipython3
ds.plot.scatter(x="A", y="B");
```

The `hue` kwarg lets you vary the color by variable value

```ipython3
ds.plot.scatter(x="A", y="B", hue="w");
```

You can force a legend instead of a colorbar by setting `add_legend=True, add_colorbar=False`.

```ipython3
ds.plot.scatter(x="A", y="B", hue="w", add_legend=True, add_colorbar=False);
```

```ipython3
ds.plot.scatter(x="A", y="B", hue="w", add_legend=False, add_colorbar=True);
```

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.

```ipython3
ds.plot.scatter(x="A", y="B", hue="y", markersize="z");
```

The `z` kwarg lets you plot the data along the z-axis as well.

```ipython3
ds.plot.scatter(x="A", y="B", z="z", hue="y", markersize="x");
```

Faceting is also possible

```ipython3
ds.plot.scatter(x="A", y="B", hue="y", markersize="x", row="x", col="w");
```

And adding the z-axis

```ipython3
ds.plot.scatter(x="A", y="B", z="z", hue="y", markersize="x", row="x", col="w");
```

For more advanced scatter plots, we recommend converting the relevant data variables
to a pandas DataFrame and using the extensive plotting capabilities of `seaborn`.

### Lines

[`xarray.plot.lines()`](../generated/xarray.plot.lines.html.md#xarray.plot.lines) calls matplotlib.collections.LineCollection under the hood,
allowing multiple lines being drawn efficiently. It uses similar arguments as
[`xarray.plot.scatter()`](../generated/xarray.plot.scatter.html.md#xarray.plot.scatter).

Let’s return to the air temperature dataset:

```ipython3
airtemps = xr.tutorial.open_dataset("air_temperature")
air = airtemps.air - 273.15
air.attrs = airtemps.air.attrs
air.attrs["units"] = "deg C"

air.isel(lon=10).plot.lines(x="time", hue="lat");
```

Make it a little more transparent:

```ipython3
air.isel(lon=10).plot.lines(x="time", hue="lat", alpha=0.2);
```

Zoom in a little on the x-axis, and compare a few latitudes and longitudes,
group them using `hue` and `linewidth`. The `linewidth` kwarg works in
a similar way as `markersize` kwarg for scatter plots, it lets you vary the
line’s size by variable value.

```ipython3
air_zoom = air.isel(time=slice(1200, 1500), lat=[5, 10, 15], lon=[10, 15])
air_zoom.plot.lines(x="time", hue="lat", linewidth="lon", add_colorbar=False);
```

Lines can modify the linestyle but does not allow markers. Instead combine [`xarray.plot.lines()`](../generated/xarray.plot.lines.html.md#xarray.plot.lines)
with [`xarray.plot.scatter()`](../generated/xarray.plot.scatter.html.md#xarray.plot.scatter):

```ipython3
air.isel(lat=10, lon=10)[:200].plot.lines(x="time", color="k", linestyle="dashed")
air.isel(lat=10, lon=10)[:200].plot.scatter(x="time", color="k", marker="^");
```

Switching to another dataset with more variables we can analyse in similar
fashion as [`xarray.plot.scatter()`](../generated/xarray.plot.scatter.html.md#xarray.plot.scatter):

```ipython3
ds = xr.tutorial.scatter_example_dataset(seed=42)
ds.plot.lines(x="A", y="B", hue="y", linewidth="x", row="x", col="w");
```

### Quiver

Visualizing vector fields is supported with quiver plots:

```ipython3
ds.isel(w=1, z=1).plot.quiver(x="x", y="y", u="A", v="B");
```

where `u` and `v` denote the x and y direction components of the arrow vectors. Again, faceting is also possible:

```ipython3
ds.plot.quiver(x="x", y="y", u="A", v="B", col="w", row="z", scale=4);
```

`scale` is required for faceted quiver plots.
The scale determines the number of data units per arrow length unit, i.e. a smaller scale parameter makes the arrow longer.

### Streamplot

Visualizing vector fields is also supported with streamline plots:

```ipython3
ds.isel(w=1, z=1).plot.streamplot(x="x", y="y", u="A", v="B");
```

where `u` and `v` denote the x and y direction components of the vectors tangent to the streamlines.
Again, faceting is also possible:

```ipython3
ds.plot.streamplot(x="x", y="y", u="A", v="B", col="w", row="z");
```

<a id="plot-maps"></a>

## Maps

To follow this section you’ll need to have Cartopy installed and working.

This script will plot the air temperature on a map.

```ipython3
air = xr.tutorial.open_dataset("air_temperature").air

p = air.isel(time=0).plot(
    subplot_kws=dict(projection=ccrs.Orthographic(-80, 35), facecolor="gray"),
    transform=ccrs.PlateCarree(),
)
p.axes.set_global()

p.axes.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`:

```ipython3
p = air.isel(time=[0, 4]).plot(
    transform=ccrs.PlateCarree(),
    col="time",
    subplot_kws={"projection": ccrs.Orthographic(-80, 35)},
)
for ax in p.axs.flat:
    ax.coastlines()
    ax.gridlines()
```

## 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.

```ipython3
da = xr.DataArray(range(5))
fig, axs = plt.subplots(ncols=2, nrows=2)
da.plot(ax=axs[0, 0])
da.plot.line(ax=axs[0, 1])
xr.plot.plot(da, ax=axs[1, 0])
xr.plot.line(da, ax=axs[1, 1]);
```

Here the output is the same. Since the data is 1 dimensional the line plot
was used.

The convenience method [`xarray.DataArray.plot()`](../generated/xarray.DataArray.plot.html.md#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()`](../generated/xarray.plot.line.html.md#xarray.plot.line)             |
| 2             | [`xarray.plot.pcolormesh()`](../generated/xarray.plot.pcolormesh.html.md#xarray.plot.pcolormesh) |
| Anything else | [`xarray.plot.hist()`](../generated/xarray.plot.hist.html.md#xarray.plot.hist)             |

### Coordinates

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

```ipython3
a0 = xr.DataArray(np.zeros((4, 3, 2)), dims=("y", "x", "z"), name="temperature")
a0[0, 0, 0] = 1
a = a0.isel(z=0)
a
```

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.

```ipython3
a.plot();
```

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](../examples/multidimensional-coords.html.md).

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:

```ipython3
lon, lat = np.meshgrid(np.linspace(-20, 20, 5), np.linspace(0, 30, 4))
lon += lat / 10
lat += lon / 10
da = xr.DataArray(
    np.arange(20).reshape(4, 5),
    dims=["y", "x"],
    coords={"lat": (("y", "x"), lat), "lon": (("y", "x"), lon)},
)

da.plot.pcolormesh(x="lon", y="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](https://github.com/pydata/xarray/issues/781)). This is why the default is to not follow
this convention when plotting on a map:

```ipython3
ax = plt.subplot(projection=ccrs.PlateCarree())
da.plot.pcolormesh(x="lon", y="lat", ax=ax)
ax.scatter(lon, lat, transform=ccrs.PlateCarree())
ax.coastlines()
ax.gridlines(draw_labels=True);
```

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

```ipython3
ax = plt.subplot(projection=ccrs.PlateCarree())
da.plot.pcolormesh(x="lon", y="lat", ax=ax, infer_intervals=True)
ax.scatter(lon, lat, transform=ccrs.PlateCarree())
ax.coastlines()
ax.gridlines(draw_labels=True);
```

#### NOTE
The data model of xarray does not support datasets with [cell boundaries](https://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#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.

```ipython3
f, ax = plt.subplots(2, 1)
da.plot.line(x="lon", hue="y", ax=ax[0])
da.plot.line(x="lon", hue="x", ax=ax[1]);
```