Update ng-vat-mesh-api branch

README.md

@@ -1,6 +1,6 @@
 <h1 align="center">
-  <a href="https://scitools.org.uk/iris/docs/latest/">
-   <img src="docs/src/_static/iris-logo-title.png" alt="Iris" width="300"></a><br>
+  <a href="https://scitools-iris.readthedocs.io/en/latest/">
+   <img src="https://scitools-iris.readthedocs.io/en/latest/_static/iris-logo-title.png" alt="Iris" width="300"></a><br>
 </h1>
 
 
@@ -13,18 +13,24 @@
 <a href="https://cirrus-ci.com/github/SciTools/iris">
 <img src="https://api.cirrus-ci.com/github/SciTools/iris.svg?branch=master"
      alt="Cirrus-CI" /></a>
-<a href='https://scitools-iris.readthedocs.io/en/latest/?badge=latest'>
-<img src='https://readthedocs.org/projects/scitools-iris/badge/?version=latest'
-     alt='Documentation Status' /></a>
+<a href="https://scitools-iris.readthedocs.io/en/latest/?badge=latest">
+<img src="https://readthedocs.org/projects/scitools-iris/badge/?version=latest"
+     alt="Documentation Status" /></a>
 <a href="https://anaconda.org/conda-forge/iris">
 <img src="https://img.shields.io/conda/dn/conda-forge/iris.svg"
      alt="conda-forge downloads" /></a>
 <a href="https://github.com/SciTools/iris/graphs/contributors">
 <img src="https://img.shields.io/github/contributors/SciTools/iris.svg"
      alt="# contributors" /></a>
+<a href="https://anaconda.org/conda-forge/iris">
+<img src="https://img.shields.io/conda/v/conda-forge/iris?color=orange&label=conda-forge%7Ciris"
+     alt="conda-forge" /></a>
+<a href="https://pypi.org/project/scitools-iris">
+<img src="https://img.shields.io/pypi/v/scitools-iris?color=orange&label=pypi%7Cscitools-iris"
+     alt="pypi" /></a>
 <a href="https://github.com/SciTools/iris/releases">
-<img src="https://img.shields.io/github/tag/SciTools/iris.svg"
-     alt="Latest version" /></a>
+<img src="https://img.shields.io/github/v/release/scitools/iris"
+     alt="latest release" /></a>
 <a href="https://github.com/SciTools/iris/commits/master">
 <img src="https://img.shields.io/github/commits-since/SciTools/iris/latest.svg"
      alt="Commits since last release" /></a>
@@ -35,8 +41,8 @@
 <img src="https://img.shields.io/badge/code%20style-black-000000.svg"
      alt="black" /></a>
 <a href="https://twitter.com/scitools_iris">
-<img src="https://img.shields.io/twitter/follow/scitools_iris?style=social"
-     alt="twitter" /></a>
+<img src="https://img.shields.io/twitter/follow/scitools_iris?color=yellow&label=twitter%7Cscitools_iris&logo=twitter&style=plastic"
+     alt="twitter scitools_iris" /></a>
 </p>
 
 <p align="center">

docs/gallery_code/general/plot_anomaly_log_colouring.py

@@ -12,18 +12,15 @@
 "zero band" which is plotted in white.
 
 To do this, we create a custom value mapping function (normalization) using
-the matplotlib Norm class `matplotlib.colours.SymLogNorm
-<https://matplotlib.org/api/_as_gen/matplotlib.colors.SymLogNorm.html#matplotlib.colors.SymLogNorm>`_.
-We use this to make a cell-filled pseudocolour plot with a colorbar.
+the matplotlib Norm class :obj:`matplotlib.colors.SymLogNorm`.
+We use this to make a cell-filled pseudocolor plot with a colorbar.
 
 NOTE: By "pseudocolour", we mean that each data point is drawn as a "cell"
 region on the plot, coloured according to its data value.
 This is provided in Iris by the functions :meth:`iris.plot.pcolor` and
 :meth:`iris.plot.pcolormesh`, which call the underlying matplotlib
-functions of the same names (i.e. `matplotlib.pyplot.pcolor
-<http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.pcolor>`_
-and  `matplotlib.pyplot.pcolormesh
-<http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.pcolormesh>`_).
+functions of the same names (i.e., :obj:`matplotlib.pyplot.pcolor`
+and :obj:`matplotlib.pyplot.pcolormesh`).
 See also: http://en.wikipedia.org/wiki/False_color#Pseudocolor.
 
 """
@@ -65,7 +62,7 @@ def main():
 
     # Use a standard colour map which varies blue-white-red.
     # For suitable options, see the 'Diverging colormaps' section in:
-    # http://matplotlib.org/examples/color/colormaps_reference.html
+    # http://matplotlib.org/stable/gallery/color/colormap_reference.html
     anom_cmap = "bwr"
 
     # Create a 'logarithmic' data normalization.

docs/gallery_code/meteorology/plot_COP_maps.py

@@ -38,34 +38,32 @@ def cop_metadata_callback(cube, field, filename):
     filename.
     """
 
-    # Extract the experiment name (such as a1b or e1) from the filename (in
-    # this case it is just the parent folder's name)
-    containing_folder = os.path.dirname(filename)
-    experiment_label = os.path.basename(containing_folder)
+    # Extract the experiment name (such as A1B or E1) from the filename (in
+    # this case it is just the start of the file name, before the first ".").
+    fname = os.path.basename(filename)  # filename without path.
+    experiment_label = fname.split(".")[0]
 
-    # Create a coordinate with the experiment label in it
+    # Create a coordinate with the experiment label in it...
     exp_coord = coords.AuxCoord(
         experiment_label, long_name="Experiment", units="no_unit"
     )
 
-    # and add it to the cube
+    # ...and add it to the cube.
     cube.add_aux_coord(exp_coord)
 
 
 def main():
-    # Load e1 and a1 using the callback to update the metadata
-    e1 = iris.load_cube(
-        iris.sample_data_path("E1.2098.pp"), callback=cop_metadata_callback
-    )
-    a1b = iris.load_cube(
-        iris.sample_data_path("A1B.2098.pp"), callback=cop_metadata_callback
-    )
+    # Load E1 and A1B scenarios using the callback to update the metadata.
+    scenario_files = [
+        iris.sample_data_path(fname) for fname in ["E1.2098.pp", "A1B.2098.pp"]
+    ]
+    scenarios = iris.load(scenario_files, callback=cop_metadata_callback)
 
-    # Load the global average data and add an 'Experiment' coord it
-    global_avg = iris.load_cube(iris.sample_data_path("pre-industrial.pp"))
+    # Load the preindustrial reference data.
+    preindustrial = iris.load_cube(iris.sample_data_path("pre-industrial.pp"))
 
     # Define evenly spaced contour levels: -2.5, -1.5, ... 15.5, 16.5 with the
-    # specific colours
+    # specific colours.
     levels = np.arange(20) - 2.5
     red = (
         np.array(
@@ -147,81 +145,67 @@ def main():
     )
 
     # Put those colours into an array which can be passed to contourf as the
-    # specific colours for each level
-    colors = np.array([red, green, blue]).T
+    # specific colours for each level.
+    colors = np.stack([red, green, blue], axis=1)
 
-    # Subtract the global
+    # Make a wider than normal figure to house two maps side-by-side.
+    fig, ax_array = plt.subplots(1, 2, figsize=(12, 5))
 
-    # Iterate over each latitude longitude slice for both e1 and a1b scenarios
-    # simultaneously
-    for e1_slice, a1b_slice in zip(
-        e1.slices(["latitude", "longitude"]),
-        a1b.slices(["latitude", "longitude"]),
+    # Loop over our scenarios to make a plot for each.
+    for ax, experiment, label in zip(
+        ax_array, ["E1", "A1B"], ["E1", "A1B-Image"]
     ):
-
-        time_coord = a1b_slice.coord("time")
-
-        # Calculate the difference from the mean
-        delta_e1 = e1_slice - global_avg
-        delta_a1b = a1b_slice - global_avg
-
-        # Make a wider than normal figure to house two maps side-by-side
-        fig = plt.figure(figsize=(12, 5))
-
-        # Get the time datetime from the coordinate
-        time = time_coord.units.num2date(time_coord.points[0])
-        # Set a title for the entire figure, giving the time in a nice format
-        # of "MonthName Year". Also, set the y value for the title so that it
-        # is not tight to the top of the plot.
-        fig.suptitle(
-            "Annual Temperature Predictions for " + time.strftime("%Y"),
-            y=0.9,
-            fontsize=18,
+        exp_cube = scenarios.extract_cube(
+            iris.Constraint(Experiment=experiment)
         )
+        time_coord = exp_cube.coord("time")
 
-        # Add the first subplot showing the E1 scenario
-        plt.subplot(121)
-        plt.title("HadGEM2 E1 Scenario", fontsize=10)
-        iplt.contourf(delta_e1, levels, colors=colors, extend="both")
-        plt.gca().coastlines()
-        # get the current axes' subplot for use later on
-        plt1_ax = plt.gca()
+        # Calculate the difference from the preindustial control run.
+        exp_anom_cube = exp_cube - preindustrial
 
-        # Add the second subplot showing the A1B scenario
-        plt.subplot(122)
-        plt.title("HadGEM2 A1B-Image Scenario", fontsize=10)
+        # Plot this anomaly.
+        plt.sca(ax)
+        ax.set_title(f"HadGEM2 {label} Scenario", fontsize=10)
         contour_result = iplt.contourf(
-            delta_a1b, levels, colors=colors, extend="both"
+            exp_anom_cube, levels, colors=colors, extend="both"
         )
         plt.gca().coastlines()
-        # get the current axes' subplot for use later on
-        plt2_ax = plt.gca()
 
-        # Now add a colourbar who's leftmost point is the same as the leftmost
-        # point of the left hand plot and rightmost point is the rightmost
-        # point of the right hand plot
+    # Now add a colourbar who's leftmost point is the same as the leftmost
+    # point of the left hand plot and rightmost point is the rightmost
+    # point of the right hand plot.
 
-        # Get the positions of the 2nd plot and the left position of the 1st
-        # plot
-        left, bottom, width, height = plt2_ax.get_position().bounds
-        first_plot_left = plt1_ax.get_position().bounds[0]
+    # Get the positions of the 2nd plot and the left position of the 1st plot.
+    left, bottom, width, height = ax_array[1].get_position().bounds
+    first_plot_left = ax_array[0].get_position().bounds[0]
 
-        # the width of the colorbar should now be simple
-        width = left - first_plot_left + width
+    # The width of the colorbar should now be simple.
+    width = left - first_plot_left + width
 
-        # Add axes to the figure, to place the colour bar
-        colorbar_axes = fig.add_axes([first_plot_left, 0.18, width, 0.03])
+    # Add axes to the figure, to place the colour bar.
+    colorbar_axes = fig.add_axes([first_plot_left, 0.18, width, 0.03])
 
-        # Add the colour bar
-        cbar = plt.colorbar(
-            contour_result, colorbar_axes, orientation="horizontal"
-        )
+    # Add the colour bar.
+    cbar = plt.colorbar(
+        contour_result, colorbar_axes, orientation="horizontal"
+    )
 
-        # Label the colour bar and add ticks
-        cbar.set_label(e1_slice.units)
-        cbar.ax.tick_params(length=0)
+    # Label the colour bar and add ticks.
+    cbar.set_label(preindustrial.units)
+    cbar.ax.tick_params(length=0)
+
+    # Get the time datetime from the coordinate.
+    time = time_coord.units.num2date(time_coord.points[0])
+    # Set a title for the entire figure, using the year from the datetime
+    # object. Also, set the y value for the title so that it is not tight to
+    # the top of the plot.
+    fig.suptitle(
+        f"Annual Temperature Predictions for {time.year}",
+        y=0.9,
+        fontsize=18,
+    )
 
-        iplt.show()
+    iplt.show()
 
 
 if __name__ == "__main__":

docs/gallery_code/meteorology/plot_deriving_phenomena.py

@@ -26,14 +26,7 @@ def limit_colorbar_ticks(contour_object):
     number of ticks on the colorbar to 4.
 
     """
-    # Under Matplotlib v1.2.x the colorbar attribute of a contour object is
-    # a tuple containing the colorbar and an axes object, whereas under
-    # Matplotlib v1.3.x it is simply the colorbar.
-    try:
-        colorbar = contour_object.colorbar[0]
-    except (AttributeError, TypeError):
-        colorbar = contour_object.colorbar
-
+    colorbar = contour_object.colorbar
     colorbar.locator = matplotlib.ticker.MaxNLocator(4)
     colorbar.update_ticks()
 

docs/src/common_links.inc

@@ -18,7 +18,7 @@
 .. _issue: https://github.com/SciTools/iris/issues
 .. _issues: https://github.com/SciTools/iris/issues
 .. _legacy documentation: https://scitools.org.uk/iris/docs/v2.4.0/
-.. _matplotlib: https://matplotlib.org/
+.. _matplotlib: https://matplotlib.org/stable/
 .. _napolean: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
 .. _nox: https://nox.thea.codes/en/stable/
 .. _New Issue: https://github.com/scitools/iris/issues/new/choose

docs/src/conf.py

@@ -184,18 +184,18 @@ def autolog(message):
 # -- intersphinx extension ----------------------------------------------------
 # See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 intersphinx_mapping = {
-    "cartopy": ("http://scitools.org.uk/cartopy/docs/latest/", None),
-    "matplotlib": ("http://matplotlib.org/", None),
-    "numpy": ("http://docs.scipy.org/doc/numpy/", None),
-    "python": ("http://docs.python.org/2.7", None),
-    "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
+    "cartopy": ("https://scitools.org.uk/cartopy/docs/latest/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
 }
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
 # -- plot_directive extension -------------------------------------------------
-# See https://matplotlib.org/3.1.3/devel/plot_directive.html#options
+# See https://matplotlib.org/stable/api/sphinxext_plot_directive_api.html#options
 plot_formats = [
     ("png", 100),
 ]

docs/src/whatsnew/3.0.1.rst

@@ -167,12 +167,12 @@ This document explains the changes made to Iris for this release
    ``volume`` are the only accepted values. (:pull:`3533`)
 
 #. `@trexfeathers`_ set **all** plot types in :mod:`iris.plot` to now use
-   `matplotlib.dates.date2num`_ to format date/time coordinates for use on a plot
+   :obj:`matplotlib.dates.date2num` to format date/time coordinates for use on a plot
    axis (previously :meth:`~iris.plot.pcolor` and :meth:`~iris.plot.pcolormesh`
    did not include this behaviour). (:pull:`3762`)
 
 #. `@trexfeathers`_ changed date/time axis labels in :mod:`iris.quickplot` to
-   now **always** be based on the ``epoch`` used in `matplotlib.dates.date2num`_
+   now **always** be based on the ``epoch`` used in :obj:`matplotlib.dates.date2num`
    (previously would take the unit from a time coordinate, if present, even
    though the coordinate's value had been changed via ``date2num``).
    (:pull:`3762`)
@@ -189,7 +189,7 @@ This document explains the changes made to Iris for this release
 
 #. `@stephenworsley`_ changed the way tick labels are assigned from string coords.
    Previously, the first tick label would occasionally be duplicated. This also
-   removes the use of Matplotlib's deprecated ``IndexFormatter``. (:pull:`3857`)
+   removes the use of the deprecated `matplotlib`_ ``IndexFormatter``. (:pull:`3857`)
 
 #. `@znicholls`_ fixed :meth:`~iris.quickplot._title` to only check
    ``units.is_time_reference`` if the ``units`` symbol is not used. (:pull:`3902`)
@@ -295,11 +295,11 @@ This document explains the changes made to Iris for this release
 
 #. `@stephenworsley`_ and `@trexfeathers`_ pinned Iris to require
    `Cartopy`_ ``>=0.18``, in order to remain compatible with the latest version
-   of `Matplotlib`_. (:pull:`3762`)
+   of `matplotlib`_. (:pull:`3762`)
 
-#. `@bjlittle`_ unpinned Iris to use the latest version of `Matplotlib`_.
+#. `@bjlittle`_ unpinned Iris to use the latest version of `matplotlib`_.
    Supporting ``Iris`` for both ``Python2`` and ``Python3`` had resulted in
-   pinning our dependency on `Matplotlib`_ at ``v2.x``.  But this is no longer
+   pinning our dependency on `matplotlib`_ at ``v2.x``.  But this is no longer
    necessary now that ``Python2`` support has been dropped. (:pull:`3468`)
 
 #. `@stephenworsley`_ and `@trexfeathers`_ unpinned Iris to use the latest version
@@ -422,11 +422,11 @@ This document explains the changes made to Iris for this release
    grid-line spacing in `Cartopy`_. (:pull:`3762`) (see also `Cartopy#1117`_)
 
 #. `@trexfeathers`_ added additional acceptable graphics test targets to account
-   for very minor changes in `Matplotlib`_ version ``3.3`` (colormaps, fonts and
+   for very minor changes in `matplotlib`_ version ``3.3`` (colormaps, fonts and
    axes borders). (:pull:`3762`)
 
-#. `@rcomer`_ corrected the Matplotlib backend in Iris tests to ignore
-   `matplotlib.rcdefaults`_, instead the tests will **always** use ``agg``.
+#. `@rcomer`_ corrected the `matplotlib`_ backend in Iris tests to ignore
+   :obj:`matplotlib.rcdefaults`, instead the tests will **always** use ``agg``.
    (:pull:`3846`)
 
 #. `@bjlittle`_ migrated the `black`_ support from ``19.10b0`` to ``20.8b1``.
@@ -470,7 +470,6 @@ This document explains the changes made to Iris for this release
    with `flake8`_ and `black`_. (:pull:`3928`)
 
 .. _Read the Docs: https://scitools-iris.readthedocs.io/en/latest/
-.. _Matplotlib: https://matplotlib.org/
 .. _CF units rules: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units
 .. _CF Ancillary Data: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#ancillary-data
 .. _Quality Flags: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags
@@ -480,7 +479,6 @@ This document explains the changes made to Iris for this release
 .. _Cartopy#1105: https://github.com/SciTools/cartopy/pull/1105
 .. _Cartopy#1117: https://github.com/SciTools/cartopy/pull/1117
 .. _Dask: https://github.com/dask/dask
-.. _matplotlib.dates.date2num: https://matplotlib.org/api/dates_api.html#matplotlib.dates.date2num
 .. _Proj: https://github.com/OSGeo/PROJ
 .. _black: https://black.readthedocs.io/en/stable/
 .. _Proj#1292: https://github.com/OSGeo/PROJ/pull/1292
@@ -510,7 +508,6 @@ This document explains the changes made to Iris for this release
 .. _numpy: https://github.com/numpy/numpy
 .. _xxHash: https://github.com/Cyan4973/xxHash
 .. _PyKE: https://pypi.org/project/scitools-pyke/
-.. _matplotlib.rcdefaults: https://matplotlib.org/3.1.1/api/matplotlib_configuration_api.html?highlight=rcdefaults#matplotlib.rcdefaults
 .. _@owena11: https://github.com/owena11
 .. _GitHub: https://github.com/SciTools/iris/issues/new/choose
 .. _readthedocs: https://readthedocs.org/