Skip to content

Commit

Permalink
Switch examples to notebooks + scipy19 docs improvements (#3557)
Browse files Browse the repository at this point in the history
* Switch doc examples to use nbsphinx (#3105)

* switching out examples to use nbsphinx

* added jupyter_client to doc env

* added ipykernel to doc env

* Replace sphinx_gallery with notebook (#3106)

* switching out examples to use nbsphinx

* added jupyter_client to doc env

* moved gallery to notebook

* Allow other tutorial filename extensions (#3121)

* switching out examples to use nbsphinx

* added jupyter_client to doc env

* allow non netcdf tutorial files

* Added ROMS ocean model example notebook (#3116)

* change name of test env to xarray-tests (#3110)

* ROMS_ocean_model example added

* Allow other tutorial filename extensions (#3121)

* switching out examples to use nbsphinx

* added jupyter_client to doc env

* allow non netcdf tutorial files

* Changed load to xr.tutorial.open_dataset(), and
added some extra documentation.

* change name of test env to xarray-tests (#3110)

* ROMS_ocean_model example added

* Changed load to xr.tutorial.open_dataset(), and
added some extra documentation.

* fixed colormap issues leftover from cmocean import

* Added intro paragraph to ROMS example notebook, removed comments, and added citation in whats-new.

* Add an example of ERA5 and GRIB data & visualization to the gallery (#3199)

* Adds an example of ERA5 and GRIB data to the gallery

* Add markdown narrative cells to GRIB example

* Update load method to use xr.tutorial

* Fix load method

* require nbsphinx for the documentation builds

* add more nbsphinx dependencies

* install cfgrib using pip

* add the eccodes library to the dependencies

* remove the dependency on sphinx-gallery

* add the ERA5 GRIB example to the list

* update the documentation links

Missing: section links in visualization_gallery.ipynb don't work yet,
also the one in io.rst (it has a unicode char).

* Fix leap year condition in monthly means example (#3464)

* Typo correction in docs (#3387)

* Update terminology.rst (#3455)

Fixed broken link

* Error in leap year?

I've tried this script; however, it adds +1 to all months of the leap years. It sounds like an error, or I am wrong? So I wrote the condition "and month == 2" line 86 so that only the month of February gets +1.

* Fix leap year (#3464)

* Update doc/whats-new.rst

Co-Authored-By: Deepak Cherian <dcherian@users.noreply.github.com>

* fix the reference to the rasterio geocoordinates docs

* update whats-new.rst
  • Loading branch information
keewis authored and dcherian committed Nov 22, 2019
1 parent 9717681 commit b0064b2
Show file tree
Hide file tree
Showing 17 changed files with 1,257 additions and 1,187 deletions.
9 changes: 8 additions & 1 deletion ci/requirements/doc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,23 @@ dependencies:
- python=3.7
- bottleneck
- cartopy
- eccodes
- h5netcdf
- ipykernel
- ipython
- iris
- jupyter_client
- nbsphinx
- netcdf4
- numpy
- numpydoc
- pandas<0.25 # Hack around https://github.com/pydata/xarray/issues/3369
- rasterio
- seaborn
- sphinx
- sphinx-gallery
- sphinx_rtd_theme
- zarr
- pip
- pip:
- cfgrib

20 changes: 12 additions & 8 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,20 +76,24 @@
"numpydoc",
"IPython.sphinxext.ipython_directive",
"IPython.sphinxext.ipython_console_highlighting",
"sphinx_gallery.gen_gallery",
"nbsphinx",
]

extlinks = {
"issue": ("https://github.com/pydata/xarray/issues/%s", "GH"),
"pull": ("https://github.com/pydata/xarray/pull/%s", "PR"),
}

sphinx_gallery_conf = {
"examples_dirs": "gallery",
"gallery_dirs": "auto_gallery",
"backreferences_dir": False,
"expected_failing_examples": list(allowed_failures),
}
nbsphinx_timeout = 600
nbsphinx_execute = "always"
nbsphinx_prolog = """
{% set docname = env.doc2path(env.docname, base=None) %}
You can run this notebook in a `live session <https://mybinder.org/v2/gh/pydata/xarray/doc/examples/master?urlpath=lab/tree/doc/{{ docname }}>`_ |Binder| or view it `on Github <https://github.com/pydata/xarray/blob/master/doc/{{ docname }}>`_.
.. |Binder| image:: https://mybinder.org/badge.svg
:target: https://mybinder.org/v2/gh/pydata/xarray/master?urlpath=lab/tree/doc/{{ docname }}
"""

autosummary_generate = True
autodoc_typehints = "none"
Expand Down Expand Up @@ -137,7 +141,7 @@

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ["_build"]
exclude_patterns = ["_build", "**.ipynb_checkpoints"]

# The reST default role (used for this markup: `text`) to use for all
# documents.
Expand Down
16 changes: 8 additions & 8 deletions doc/data-structures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -485,14 +485,14 @@ in xarray:
:py:class:`pandas.Index` internally to store their values.

- **non-dimension coordinates** are variables that contain coordinate
data, but are not a dimension coordinate. They can be multidimensional
(see :ref:`examples.multidim`), and there is no relationship between the
name of a non-dimension coordinate and the name(s) of its dimension(s).
Non-dimension coordinates can be useful for indexing or plotting; otherwise,
xarray does not make any direct use of the values associated with them.
They are not used for alignment or automatic indexing, nor are they required
to match when doing arithmetic
(see :ref:`coordinates math`).
data, but are not a dimension coordinate. They can be multidimensional (see
:ref:`/examples/multidimensional-coords.ipynb`), and there is no
relationship between the name of a non-dimension coordinate and the
name(s) of its dimension(s). Non-dimension coordinates can be
useful for indexing or plotting; otherwise, xarray does not make any
direct use of the values associated with them. They are not used
for alignment or automatic indexing, nor are they required to match
when doing arithmetic (see :ref:`coordinates math`).

.. note::

Expand Down
4 changes: 3 additions & 1 deletion doc/examples.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,6 @@ Examples
examples/weather-data
examples/monthly-means
examples/multidimensional-coords
auto_gallery/index
examples/visualization_gallery
examples/ROMS_ocean_model
examples/ERA5-GRIB-example
121 changes: 121 additions & 0 deletions doc/examples/ERA5-GRIB-example.ipynb
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# GRIB Data Example "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"GRIB format is commonly used to disemminate atmospheric model data. With Xarray and the cfgrib engine, GRIB data can easily be analyzed and visualized."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import xarray as xr\n",
"import matplotlib.pyplot as plt"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To read GRIB data, you can use `xarray.load_dataset`. The only extra code you need is to specify the engine as `cfgrib`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"ds = xr.tutorial.load_dataset('era5-2mt-2019-03-uk.grib', engine='cfgrib')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Let's create a simple plot of 2-m air temperature in degrees Celsius:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"ds = ds - 273.15\n",
"ds.t2m[0].plot(cmap=plt.cm.coolwarm)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"With CartoPy, we can create a more detailed plot, using built-in shapefiles to help provide geographic context:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import cartopy.crs as ccrs\n",
"import cartopy\n",
"fig = plt.figure(figsize=(10,10))\n",
"ax = plt.axes(projection=ccrs.Robinson())\n",
"ax.coastlines(resolution='10m')\n",
"plot = ds.t2m[0].plot(cmap=plt.cm.coolwarm, transform=ccrs.PlateCarree(), cbar_kwargs={'shrink':0.6})\n",
"plt.title('ERA5 - 2m temperature British Isles March 2019')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Finally, we can also pull out a time series for a given location easily:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"ds.t2m.sel(longitude=0,latitude=51.5).plot()\n",
"plt.title('ERA5 - London 2m temperature March 2019')"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.3"
}
},
"nbformat": 4,
"nbformat_minor": 4
}
Loading

0 comments on commit b0064b2

Please sign in to comment.