Merge branch 'master' of git://github.com/SciTools/iris into fix-issu…

…e-3677

docs/iris/src/developers_guide/graphics_tests.rst

@@ -10,9 +10,10 @@ For this, a basic 'graphics test' assertion operation is provided in the method
 match against a stored reference.
 A "graphics test" is any test which employs this.
 
-At present (Iris version 1.10), such tests include the testing for modules
-`iris.tests.test_plot` and `iris.tests.test_quickplot`, and also some other
-'legacy' style tests (as described in :ref:`developer_tests`).
+At present, such tests include the testing for modules `iris.tests.test_plot`
+and `iris.tests.test_quickplot`, all output plots from the gallery examples
+(contained in `docs/iris/example_tests`), and a few  other 'legacy' style tests
+(as described in :ref:`developer_tests`).
 It is conceivable that new 'graphics tests' of this sort can still be added.
 However, as graphics tests are inherently "integration" style rather than true
 unit tests, results can differ with the installed versions of dependent
@@ -38,80 +39,110 @@ Testing actual plot results introduces some significant difficulties :
 Graphics Testing Strategy
 =========================
 
-Prior to Iris 1.10, all graphics tests compared against a stored reference
-image with a small tolerance on pixel values.
+In the Iris Travis matrix, and over time, graphics tests must run with
+multiple versions of Python, and of key dependencies such as matplotlib.
+To make this manageable, the "check_graphic" test routine tests against
+multiple alternative 'acceptable' results.  It does this using an image "hash"
+comparison technique which avoids storing reference images in the Iris
+repository itself, to avoid space problems.
 
-From Iris v1.11 onward, we want to support testing Iris against multiple
-versions of matplotlib (and some other dependencies).  
-To make this manageable, we have now rewritten "check_graphic" to allow
-multiple alternative 'correct' results without including many more images in
-the Iris repository.  
 This consists of :
 
- * using a perceptual 'image hash' of the outputs (see
-   https://github.com/JohannesBuchner/imagehash) as the basis for checking
+ * The 'check_graphic' function uses a perceptual 'image hash' of the outputs
+   (see https://github.com/JohannesBuchner/imagehash) as the basis for checking
    test results.
- * storing the hashes of 'known accepted results' for each test in a
-   database in the repo (which is actually stored in 
-   ``lib/iris/tests/results/imagerepo.json``).
- * storing associated reference images for each hash value in a separate public
-   repository, currently in https://github.com/SciTools/test-images-scitools ,
-   allowing human-eye judgement of 'valid equivalent' results.
- * a new version of the 'iris/tests/idiff.py' assists in comparing proposed
-   new 'correct' result images with the existing accepted ones.
-
-BRIEF...
-There should be sufficient work-flow detail here to allow an iris developer to:
-
- * understand the new check graphic test process
- * understand the steps to take and tools to use to add a new graphic test
- * understand the steps to take and tools to use to diagnose and fix an graphic test failure
-
-
-Basic workflow
-==============
-
-If you notice that a graphics test in the Iris testing suite has failed
-following changes in Iris or any of its dependencies, this is the process
-you now need to follow:
-
-#. Create a directory in iris/lib/iris/tests called 'result_image_comparison'.
-#. From your Iris root directory, run the tests by using the command: 
-   ``python setup.py test``.
-#. Navigate to iris/lib/iris/tests and run the command: ``python idiff.py``.
-   This will open a window for you to visually inspect the changes to the
-   graphic and then either accept or reject the new result.
-#. Upon acceptance of a change or a new image, a copy of the output PNG file
-   is added to the reference image repository in
-   https://github.com/SciTools/test-images-scitools.  The file is named
-   according to the image hash value, as ``<hash>.png``.
-#. The hash value of the new result is added into the relevant set of 'valid
-   result hashes' in the image result database file,
-   ``tests/results/imagerepo.json``.
-#. The tests must now be re-run, and the 'new' result should be accepted.
-   Occasionally there are several graphics checks in a single test, only the
-   first of which will be run should it fail.  If this is the case, then you
-   may well encounter further graphical test failures in your next runs, and
-   you must repeat the process until all the graphical tests pass.
-#. To add your changes to Iris, you need to make two pull requests.  The first
-   should be made to the test-images-scitools repository, and this should
-   contain all the newly-generated png files copied into the folder named
-   'image_files'.
-#. The second pull request should be created in the Iris repository, and should
-   only include the change to the image results database
-   (``tests/results/imagerepo.json``) :
-   This pull request must contain a reference to the matching one in
-   test-images-scitools.
+ * The hashes of known 'acceptable' results for each test are stored in a
+   lookup dictionary, saved to the repo file
+   ``lib/iris/tests/results/imagerepo.json`` .
+ * An actual reference image for each hash value is stored in a *separate*
+   public repository : https://github.com/SciTools/test-iris-imagehash .
+ * The reference images allow human-eye assessment of whether a new output is
+   judged to be 'close enough' to the older ones, or not.
+ * The utility script ``iris/tests/idiff.py`` automates checking, enabling the
+   developer to easily compare proposed new 'acceptable' result images against the
+   existing accepted reference images, for each failing test.
 
-Note: the Iris pull-request will not test out successfully in Travis until the
-test-images-scitools pull request has been merged :  This is because there is
-an Iris test which ensures the existence of the reference images (uris) for all
-the targets in the image results database.
 
+How to Add New 'Acceptable' Result Images to Existing Tests
+========================================
+
+When you find that a graphics test in the Iris testing suite has failed,
+following changes in Iris or the run dependencies, this is the process
+you should follow:
+
+#. Create a new, empty directory to store temporary image results, at the path
+   ``lib/iris/tests/result_image_comparison`` in your Iris repository checkout.
+
+#. **In your Iris repo root directory**, run the relevant (failing) tests
+   directly as python scripts, or by using a command such as
+   ``python -m unittest discover paths/to/test/files``.
+
+#. **In the** ``iris/lib/iris/tests`` **folder**,  run the command: ``python idiff.py``.
+   This will open a window for you to visually inspect side-by-side 'old', 'new'
+   and 'difference' images for each failed graphics test.
+   Hit a button to either "accept", "reject" or "skip" each new result ...
+
+   * If the change is *"accepted"* :
+
+     * the imagehash value of the new result image is added into the relevant
+       set of 'valid result hashes' in the image result database file,
+       ``tests/results/imagerepo.json`` ;
+
+     * the relevant output file in ``tests/result_image_comparison`` is
+       renamed according to the image hash value, as ``<hash>.png``.
+       A copy of this new PNG file must then be added into the reference image
+       repository at https://github.com/SciTools/test-iris-imagehash.
+       (See below).
+
+   * If a change is *"skipped"* :
+
+     * no further changes are made in the repo.
+
+     * when you run idiff again, the skipped choice will be presented again.
 
-Fixing a failing graphics test
-==============================
+   * If a change is *"rejected"* :
 
+     * the output image is deleted from ``result_image_comparison``.
 
-Adding a new graphics test
-==========================
+     * when you run idiff again, the skipped choice will not appear, unless
+       and until the relevant failing test is re-run.
+
+#. Now re-run the tests.  The 'new' result should now be recognised and the
+   relevant test should pass.  However, some tests can perform *multiple* graphics
+   checks within a single testcase function : In those cases, any failing
+   check will prevent the following ones from being run, so a test re-run may
+   encounter further (new) graphical test failures.  If that happens, simply
+   repeat the check-and-accept process until all tests pass.
+
+#. To add your changes to Iris, you need to make two pull requests :
+
+   * (1) The first PR is made in the test-iris-imagehash repository, at
+     https://github.com/SciTools/test-iris-imagehash.
+
+     *  First, add all the newly-generated referenced PNG files into the
+        ``images/v4`` directory.  In your Iris repo, these files are to be found
+        in the temporary results folder ``iris/tests/result_image_comparison``.
+
+        .. Note::
+
+           The ``result_image_comparison`` folder is covered by a project
+           ``.gitignore`` setting, so those files *will not show up* in a
+           ``git status`` check.
+
+     *  Then, run ``python recreate_v4_files_listing.py``, to update the file
+        which lists available images, ``v4_files_listing.txt``.
+
+     *  Create a PR proposing these changes, in the usual way.
+
+   * (2) The second PR is created in the Iris repository, and
+     should only include the change to the image results database,
+     ``tests/results/imagerepo.json`` :
+     The description box of this pull request should contain a reference to
+     the matching one in test-iris-imagehash.
+
+Note: the Iris pull-request will not test out successfully in Travis until the
+test-iris-imagehash pull request has been merged :  This is because there is
+an Iris test which ensures the existence of the reference images (uris) for all
+the targets in the image results database.  N.B. likewise, it will *also* fail
+if you forgot to run ``recreate_v4_files_listing.py`` to update the image-listing
+file in test-iris-imagehash.

docs/iris/src/developers_guide/tests.rst

@@ -139,16 +139,5 @@ This the only way of testing the modules :mod:`iris.plot` and
 :mod:`iris.quickplot`, but is also used for some other legacy and integration-
 style testcases.
 
-Prior to Iris version 1.10, a single reference image for each testcase was
-stored in the main Iris repository, and a 'tolerant' comparison was performed
-against this.
-
-From version 1.11 onwards, graphics testcase outputs are compared against
-possibly *multiple* known-good images, of which only the signature is stored.
-This uses a sophisticated perceptual "image hashing" scheme (see: 
-<https://github.com/JohannesBuchner/imagehash>).
-Only imagehash signatures are stored in the Iris repo itself, thus freeing up
-valuable space.  Meanwhile, the actual reference *images* -- which are required
-for human-eyes evaluation of proposed new "good results" -- are all stored
-elsewhere in a separate public repository.
+There are specific mechanisms for handling this.
 See :ref:`developer_graphics_tests`.

docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2020-May-22_cubelist_extract_cubes.txt

@@ -0,0 +1,10 @@
+* The method :meth:`~iris.cube.CubeList.extract_strict`, and the 'strict'
+  keyword to :meth:`~iris.cube.CubeList.extract` method have been removed, and
+  are replaced by the new routines :meth:`~iris.cube.CubeList.extract_cube` and
+  :meth:`~iris.cube.CubeList.extract_cubes`.
+  The new routines perform the same operation, but in a style more like other
+  Iris functions such as :meth:`iris.load_cube` and :meth:`iris.load_cubes`.
+  Unlike 'strict extraction', the type of return value is now completely
+  consistent : :meth:`~iris.cube.CubeList.extract_cube` always returns a cube,
+  and :meth:`~iris.cube.CubeList.extract_cubes` always returns a CubeList of a
+  length equal to the number of constraints.

docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Dec-20_cache_area_weights.txt

@@ -1,2 +1,5 @@
-* The area weights used when performing area weighted regridding are now
-  cached. 
+* The area weights used when performing area weighted regridding with :class:`iris.analysis.AreaWeighted`
+  are now cached.
+  This allows a significant speedup when regridding multiple similar cubes, by repeatedly using
+  a `'regridder' object <../iris/iris/analysis.html?highlight=regridder#iris.analysis.AreaWeighted.regridder>`_
+  which you created first.

lib/iris/_constraints.py

@@ -428,7 +428,7 @@ def list_of_constraints(constraints):
     using :func:`as_constraint`.
 
     """
-    if not isinstance(constraints, (list, tuple)):
+    if isinstance(constraints, str) or not isinstance(constraints, Iterable):
         constraints = [constraints]
 
     return [as_constraint(constraint) for constraint in constraints]

lib/iris/coord_categorisation.py

@@ -182,7 +182,7 @@ def add_day_of_year(cube, coord, name="day_of_year"):
 def add_weekday_number(cube, coord, name="weekday_number"):
     """Add a categorical weekday coordinate, values 0..6  [0=Monday]."""
     add_categorised_coord(
-        cube, name, coord, lambda coord, x: _pt_date(coord, x).weekday()
+        cube, name, coord, lambda coord, x: _pt_date(coord, x).dayofwk
     )
 
 
@@ -192,7 +192,7 @@ def add_weekday_fullname(cube, coord, name="weekday_fullname"):
         cube,
         name,
         coord,
-        lambda coord, x: calendar.day_name[_pt_date(coord, x).weekday()],
+        lambda coord, x: calendar.day_name[_pt_date(coord, x).dayofwk],
         units="no_unit",
     )
 
@@ -203,7 +203,7 @@ def add_weekday(cube, coord, name="weekday"):
         cube,
         name,
         coord,
-        lambda coord, x: calendar.day_abbr[_pt_date(coord, x).weekday()],
+        lambda coord, x: calendar.day_abbr[_pt_date(coord, x).dayofwk],
         units="no_unit",
     )
 

lib/iris/cube.py

@@ -268,7 +268,7 @@ def xml(self, checksum=False, order=True, byteorder=True):
         # return our newly created XML string
         return doc.toprettyxml(indent="  ")
 
-    def extract(self, constraints, strict=False):
+    def extract(self, constraints):
         """
         Filter each of the cubes which can be filtered by the given
         constraints.
@@ -278,22 +278,57 @@ def extract(self, constraints, strict=False):
         **n** when filtered with **m** constraints can generate a maximum of
         **m * n** cubes.
 
-        Keywords:
+        Args:
+
+        * constraints (:class:`~iris.Constraint` or iterable of constraints):
+            A single constraint or an iterable.
+
+        """
+        return self._extract_and_merge(self, constraints, strict=False)
+
+    def extract_cube(self, constraint):
+        """
+        Extract a single cube from a CubeList, and return it.
+        Raise an error if the extract produces no cubes, or more than one.
+
+        Args:
+
+        * constraint (:class:`~iris.Constraint`):
+            The constraint to extract with.
 
-        * strict - boolean
-            If strict is True, then there must be exactly one cube which is
-            filtered per constraint.
+        .. see also::
+            :meth:`~iris.cube.CubeList.extract`
 
         """
+        # Just validate this, so we can accept strings etc, but not multiples.
+        constraint = iris._constraints.as_constraint(constraint)
         return self._extract_and_merge(
-            self, constraints, strict, merge_unique=None
+            self, constraint, strict=True, return_single_cube=True
         )
 
-    @staticmethod
-    def _extract_and_merge(cubes, constraints, strict, merge_unique=False):
-        # * merge_unique - if None: no merging, if false: non unique merging,
-        # else unique merging (see merge)
+    def extract_cubes(self, constraints):
+        """
+        Extract specific cubes from a CubeList, one for each given constraint.
+        Each constraint must produce exactly one cube, otherwise an error is
+        raised.
+
+        Args:
 
+        * constraints (iterable of, or single, :class:`~iris.Constraint`):
+            The constraints to extract with.
+
+        .. see also::
+            :meth:`~iris.cube.CubeList.extract`
+
+        """
+        return self._extract_and_merge(
+            self, constraints, strict=True, return_single_cube=False
+        )
+
+    @staticmethod
+    def _extract_and_merge(
+        cubes, constraints, strict=False, return_single_cube=False
+    ):
         constraints = iris._constraints.list_of_constraints(constraints)
 
         # group the resultant cubes by constraints in a dictionary
@@ -306,10 +341,6 @@ def _extract_and_merge(cubes, constraints, strict, merge_unique=False):
                 if sub_cube is not None:
                     cube_list.append(sub_cube)
 
-        if merge_unique is not None:
-            for constraint, cubelist in constraint_groups.items():
-                constraint_groups[constraint] = cubelist.merge(merge_unique)
-
         result = CubeList()
         for constraint in constraints:
             constraint_cubes = constraint_groups[constraint]
@@ -321,18 +352,18 @@ def _extract_and_merge(cubes, constraints, strict, merge_unique=False):
                 raise iris.exceptions.ConstraintMismatchError(msg)
             result.extend(constraint_cubes)
 
-        if strict and len(constraints) == 1:
+        if return_single_cube:
+            if len(result) != 1:
+                # Practically this should never occur, as we now *only* request
+                # single cube result for 'extract_cube'.
+                msg = "Got {!s} cubes for constraints {!r}, expecting 1."
+                raise iris.exceptions.ConstraintMismatchError(
+                    msg.format(len(result), constraints)
+                )
             result = result[0]
 
         return result
 
-    def extract_strict(self, constraints):
-        """
-        Calls :meth:`CubeList.extract` with the strict keyword set to True.
-
-        """
-        return self.extract(constraints, strict=True)
-
     def extract_overlapping(self, coord_names):
         """
         Returns a :class:`CubeList` of cubes extracted over regions