Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix the RTD timeouts #4254

Merged
merged 3 commits into from
Jul 22, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 44 additions & 1 deletion doc/plotting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ One Dimension
The simplest way to make a plot is to call the :py:func:`DataArray.plot()` method.

.. ipython:: python
:okwarning:

air1d = air.isel(lat=10, lon=10)

Expand All @@ -125,6 +126,7 @@ can be used:
.. _matplotlib.pyplot.plot: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.plot

.. ipython:: python
:okwarning:

@savefig plotting_1d_additional_args.png width=4in
air1d[:200].plot.line("b-^")
Expand All @@ -137,6 +139,7 @@ can be used:
Keyword arguments work the same way, and are more explicit.

.. ipython:: python
:okwarning:

@savefig plotting_example_sin3.png width=4in
air1d[:200].plot.line(color="purple", marker="o")
Expand All @@ -151,6 +154,7 @@ In this example ``axes`` is an array consisting of the left and right
axes created by ``plt.subplots``.

.. ipython:: python
:okwarning:

fig, axes = plt.subplots(ncols=2)

Expand Down Expand Up @@ -178,6 +182,7 @@ support the ``aspect`` and ``size`` arguments which control the size of the
resulting image via the formula ``figsize = (aspect * size, size)``:

.. ipython:: python
:okwarning:

air1d.plot(aspect=2, size=3)
@savefig plotting_example_size_and_aspect.png
Expand Down Expand Up @@ -219,6 +224,7 @@ without coordinates along the x-axis. To illustrate this, let's calculate a 'dec
from the time and assign it as a non-dimension coordinate:

.. ipython:: python
:okwarning:

decimal_day = (air1d.time - air1d.time[0]) / pd.Timedelta("1d")
air1d_multi = air1d.assign_coords(decimal_day=("time", decimal_day))
Expand All @@ -227,20 +233,23 @@ from the time and assign it as a non-dimension coordinate:
To use ``'decimal_day'`` as x coordinate it must be explicitly specified:

.. ipython:: python
:okwarning:

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:

.. ipython:: python
:okwarning:

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:

.. ipython:: python
:okwarning:

air1d_multi = air1d_multi.drop("date")
air1d_multi.plot()
Expand All @@ -256,6 +265,7 @@ with appropriate arguments. Consider the 3D variable ``air`` defined above. We c
plots to check the variation of air temperature at three different latitudes along a longitude line:

.. ipython:: python
:okwarning:

@savefig plotting_example_multiple_lines_x_kwarg.png
air.isel(lon=10, lat=[19, 21, 22]).plot.line(x="time")
Expand All @@ -277,6 +287,7 @@ If required, the automatic legend can be turned off using ``add_legend=False``.
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.

.. ipython:: python
:okwarning:

@savefig plotting_example_xy_kwarg.png
air.isel(time=10, lon=[10, 11]).plot(y="lat", hue="lon")
Expand All @@ -299,6 +310,7 @@ The argument ``where`` defines where the steps should be placed, options are
when plotting data grouped with :py:meth:`Dataset.groupby_bins`.

.. ipython:: python
:okwarning:

air_grp = air.mean(["time", "lon"]).groupby_bins("lat", [0, 23.5, 66.5, 90])
air_mean = air_grp.mean()
Expand All @@ -321,6 +333,7 @@ Other axes kwargs
The keyword arguments ``xincrease`` and ``yincrease`` let you control the axes direction.

.. ipython:: python
:okwarning:

@savefig plotting_example_xincrease_yincrease_kwarg.png
air.isel(time=10, lon=[10, 11]).plot.line(
Expand All @@ -340,6 +353,7 @@ Two Dimensions
The default method :py:meth:`DataArray.plot` calls :py:func:`xarray.plot.pcolormesh` by default when the data is two-dimensional.

.. ipython:: python
:okwarning:

air2d = air.isel(time=500)

Expand All @@ -350,6 +364,7 @@ All 2d plots in xarray allow the use of the keyword arguments ``yincrease``
and ``xincrease``.

.. ipython:: python
:okwarning:

@savefig 2d_simple_yincrease.png width=4in
air2d.plot(yincrease=False)
Expand All @@ -369,6 +384,7 @@ and ``xincrease``.
xarray plots data with :ref:`missing_values`.

.. ipython:: python
:okwarning:

bad_air2d = air2d.copy()

Expand All @@ -386,6 +402,7 @@ It's not necessary for the coordinates to be evenly spaced. Both
produce plots with nonuniform coordinates.

.. ipython:: python
:okwarning:

b = air2d.copy()
# Apply a nonlinear transformation to one of the coords
Expand All @@ -402,6 +419,7 @@ Since this is a thin wrapper around matplotlib, all the functionality of
matplotlib is available.

.. ipython:: python
:okwarning:

air2d.plot(cmap=plt.cm.Blues)
plt.title("These colors prove North America\nhas fallen in the ocean")
Expand All @@ -421,6 +439,7 @@ matplotlib is available.
``d_ylog.plot()`` updates the xlabel.

.. ipython:: python
:okwarning:

plt.xlabel("Never gonna see this.")
air2d.plot()
Expand All @@ -436,6 +455,7 @@ 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:

.. ipython:: python
:okwarning:

@savefig plotting_kelvin.png width=4in
airtemps.air.isel(time=0).plot()
Expand All @@ -454,6 +474,7 @@ Here we add two bad data points. This affects the color scale,
washing out the plot.

.. ipython:: python
:okwarning:

air_outliers = airtemps.air.isel(time=0).copy()
air_outliers[0, 0] = 100
Expand All @@ -469,6 +490,7 @@ This will use the 2nd and 98th
percentiles of the data to compute the color limits.

.. ipython:: python
:okwarning:

@savefig plotting_robust2.png width=4in
air_outliers.plot(robust=True)
Expand All @@ -487,6 +509,7 @@ rather than the default continuous colormaps that matplotlib uses. The
colormaps. For example, to make a plot with 8 discrete color intervals:

.. ipython:: python
:okwarning:

@savefig plotting_discrete_levels.png width=4in
air2d.plot(levels=8)
Expand All @@ -495,13 +518,15 @@ It is also possible to use a list of levels to specify the boundaries of the
discrete colormap:

.. ipython:: python
:okwarning:

@savefig plotting_listed_levels.png width=4in
air2d.plot(levels=[0, 12, 18, 30])

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

.. ipython:: python
:okwarning:

flatui = ["#9b59b6", "#3498db", "#95a5a6", "#e74c3c", "#34495e", "#2ecc71"]
@savefig plotting_custom_colors_levels.png width=4in
Expand Down Expand Up @@ -559,13 +584,15 @@ arguments to the xarray plotting methods/functions. This returns a
:py:class:`xarray.plot.FacetGrid` object.

.. ipython:: python
:okwarning:

@savefig plot_facet_dataarray.png
g_simple = t.plot(x="lon", y="lat", col="time", col_wrap=3)

Faceting also works for line plots.

.. ipython:: python
:okwarning:

@savefig plot_facet_dataarray_line.png
g_simple_line = t.isel(lat=slice(0, None, 4)).plot(
Expand All @@ -582,6 +609,7 @@ a fixed amount. Now we can see how the temperature maps would compare if
one were much hotter.

.. ipython:: python
:okwarning:

t2 = t.isel(time=slice(0, 2))
t4d = xr.concat([t2, t2 + 40], pd.Index(["normal", "hot"], name="fourth_dim"))
Expand All @@ -603,6 +631,7 @@ Faceted plotting supports other arguments common to xarray 2d plots.
plt.close("all")

.. ipython:: python
:okwarning:

hasoutliers = t.isel(time=slice(0, 5)).copy()
hasoutliers[0, 0, 0] = -100
Expand Down Expand Up @@ -649,6 +678,7 @@ Here is an example of using the lower level API and then modifying the axes afte
they have been plotted.

.. ipython:: python
:okwarning:

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

Expand Down Expand Up @@ -688,13 +718,15 @@ Consider this dataset
Suppose we want to scatter ``A`` against ``B``

.. ipython:: python
:okwarning:

@savefig ds_simple_scatter.png
ds.plot.scatter(x="A", y="B")

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

.. ipython:: python
:okwarning:

@savefig ds_hue_scatter.png
ds.plot.scatter(x="A", y="B", hue="w")
Expand All @@ -705,6 +737,7 @@ 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).

.. ipython:: python
:okwarning:

ds = ds.assign(w=[1, 2, 3, 5])
@savefig ds_discrete_legend_hue_scatter.png
Expand All @@ -713,13 +746,15 @@ Additionally, the boolean kwarg ``add_guide`` can be used to prevent the display
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.

.. ipython:: python
:okwarning:

@savefig ds_hue_size_scatter.png
ds.plot.scatter(x="A", y="B", hue="z", hue_style="discrete", markersize="z")

Faceting is also possible

.. ipython:: python
:okwarning:

@savefig ds_facet_scatter.png
ds.plot.scatter(x="A", y="B", col="x", row="z", hue="w", hue_style="discrete")
Expand All @@ -738,14 +773,16 @@ To follow this section you'll need to have Cartopy installed and working.
This script will plot the air temperature on a map.

.. ipython:: python
:okwarning:

import cartopy.crs as ccrs

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())
transform=ccrs.PlateCarree(),
)
p.axes.set_global()

@savefig plotting_maps_cartopy.png width=100%
Expand Down Expand Up @@ -788,6 +825,7 @@ There are three ways to use the xarray plotting functionality:
These are provided for user convenience; they all call the same code.

.. ipython:: python
:okwarning:

import xarray.plot as xplt

Expand Down Expand Up @@ -837,6 +875,7 @@ think carefully about what the limits, labels, and orientation for
each of the axes should be.

.. ipython:: python
:okwarning:

@savefig plotting_example_2d_simple.png width=4in
a.plot()
Expand All @@ -857,6 +896,7 @@ xarray, but you'll have to tell the plot function to use these coordinates
instead of the default ones:

.. ipython:: python
:okwarning:

lon, lat = np.meshgrid(np.linspace(-20, 20, 5), np.linspace(0, 30, 4))
lon += lat / 10
Expand All @@ -876,6 +916,7 @@ on a polar projection (:issue:`781`). This is why the default is to not follow
this convention when plotting on a map:

.. ipython:: python
:okwarning:

import cartopy.crs as ccrs

Expand All @@ -890,6 +931,7 @@ You can however decide to infer the cell boundaries and use the
``infer_intervals`` keyword:

.. ipython:: python
:okwarning:

ax = plt.subplot(projection=ccrs.PlateCarree())
da.plot.pcolormesh("lon", "lat", ax=ax, infer_intervals=True)
Expand All @@ -908,6 +950,7 @@ You can however decide to infer the cell boundaries and use the
One can also make line plots with multidimensional coordinates. In this case, ``hue`` must be a dimension name, not a coordinate name.

.. ipython:: python
:okwarning:

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