diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-26_remove_coord_comparison.txt b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-26_remove_coord_comparison.txt new file mode 100644 index 0000000000..a8ba4131d0 --- /dev/null +++ b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-26_remove_coord_comparison.txt @@ -0,0 +1 @@ +* The former function "iris.analysis.coord_comparison" has been removed. diff --git a/lib/iris/analysis/__init__.py b/lib/iris/analysis/__init__.py index 0544cd8cb4..c0962ec568 100644 --- a/lib/iris/analysis/__init__.py +++ b/lib/iris/analysis/__init__.py @@ -71,7 +71,6 @@ "SUM", "VARIANCE", "WPERCENTILE", - "coord_comparison", "Aggregator", "WeightedAggregator", "clear_phenomenon_identity", @@ -186,16 +185,53 @@ def matches_any(self, predicate): return any(self.matches(predicate)) -def coord_comparison(*cubes, object_get=None): +def _dimensional_metadata_comparison(*cubes, object_get=None): """ - Convenience function to help compare coordinates on one or more cubes - by their metadata. + Convenience function to help compare coordinates, cell-measures or + ancillary-variables, on one or more cubes, by their metadata. - Return a dictionary where the key represents the statement, + .. Note:: + + Up to Iris 2.x, this _used_ to be the public API method + "iris.analysis.coord_comparison". + It has since been generalised, and made private. + However, the cube elements handled are still mostly referred to as 'coords' / + 'coordinates' throughout, for simplicity : In fact, they will all be either + `iris.coords.Coord`, `iris.coords.CellMeasure` or + `iris.coords.AncillaryVariable`, the cube element type being controlled by the + 'object_get' keyword. + + Args: + + * cubes (iterable of `iris.cube.Cube`): + a set of cubes whose coordinates, cell-measures or ancillary-variables are to + be compared. + + Kwargs: + + * object_get (callable(cube) or None): + If not None, this must be a cube method returning a list of all cube elements + of the required type, i.e. one of `iris.cube.Cube.coords`, + `iris.cube.Cube.cell_measures`, or `iris.cube.Cube.ancillary_variables`. + If not specified, defaults to `iris.cube.Cube.coords` + + Returns: + + result (dict mapping string: list of _CoordGroup): + A dictionary whose keys are match categories and values are groups of + coordinates, cell-measures or ancillary-variables. + + The values of the returned dictionary are lists of _CoordGroup representing + grouped coordinates. Each _CoordGroup contains all the input 'cubes', and a + matching list of the coord within each cube that matches some specific CoordDefn + (or maybe None). + + The keys of the returned dictionary are strings naming 'categories' : Each + represents a statement, "Given these cubes list the coordinates which, when grouped by metadata, are/have..." - Keys: + Returned Keys: * grouped_coords A list of coordinate groups of all the coordinates grouped together @@ -236,7 +272,7 @@ def coord_comparison(*cubes, object_get=None): Example usage:: - result = coord_comparison(cube1, cube2) + result = _dimensional_metadata_comparison(cube1, cube2) print('All equal coordinates: ', result['equal']) """ diff --git a/lib/iris/analysis/calculus.py b/lib/iris/analysis/calculus.py index 18b2bb888c..a7ce385932 100644 --- a/lib/iris/analysis/calculus.py +++ b/lib/iris/analysis/calculus.py @@ -536,7 +536,7 @@ def curl(i_cube, j_cube, k_cube=None): cubes = filter(None, [i_cube, j_cube, k_cube]) # get the names of all coords binned into useful comparison groups - coord_comparison = iris.analysis.coord_comparison(*cubes) + coord_comparison = iris.analysis._dimensional_metadata_comparison(*cubes) bad_coords = coord_comparison["ungroupable_and_dimensioned"] if bad_coords: diff --git a/lib/iris/analysis/maths.py b/lib/iris/analysis/maths.py index 619fd2b317..0de97b02f3 100644 --- a/lib/iris/analysis/maths.py +++ b/lib/iris/analysis/maths.py @@ -148,7 +148,9 @@ def intersection_of_cubes(cube, other_cube): if coord.ndim != 1: raise iris.exceptions.CoordinateMultiDimError(coord) - coord_comp = iris.analysis.coord_comparison(cube, other_cube) + coord_comp = iris.analysis._dimensional_metadata_comparison( + cube, other_cube + ) if coord_comp["ungroupable_and_dimensioned"]: raise ValueError( @@ -338,7 +340,9 @@ def _add_subtract_common( if isinstance(other, iris.cube.Cube): # get a coordinate comparison of this cube and the cube to do the # operation with - coord_comp = iris.analysis.coord_comparison(cube, other) + coord_comp = iris.analysis._dimensional_metadata_comparison( + cube, other + ) bad_coord_grps = ( coord_comp["ungroupable_and_dimensioned"] @@ -413,7 +417,9 @@ def multiply(cube, other, dim=None, in_place=False): if isinstance(other, iris.cube.Cube): # get a coordinate comparison of this cube and the cube to do the # operation with - coord_comp = iris.analysis.coord_comparison(cube, other) + coord_comp = iris.analysis._dimensional_metadata_comparison( + cube, other + ) bad_coord_grps = ( coord_comp["ungroupable_and_dimensioned"] + coord_comp["resamplable"] @@ -512,7 +518,9 @@ def divide(cube, other, dim=None, in_place=False): if isinstance(other, iris.cube.Cube): # get a coordinate comparison of this cube and the cube to do the # operation with - coord_comp = iris.analysis.coord_comparison(cube, other) + coord_comp = iris.analysis._dimensional_metadata_comparison( + cube, other + ) bad_coord_grps = ( coord_comp["ungroupable_and_dimensioned"] + coord_comp["resamplable"] diff --git a/lib/iris/cube.py b/lib/iris/cube.py index 3ff77fa1ad..c990064a66 100644 --- a/lib/iris/cube.py +++ b/lib/iris/cube.py @@ -3567,31 +3567,33 @@ def __eq__(self, other): # having checked the metadata, now check the coordinates if result: - coord_comparison = iris.analysis.coord_comparison(self, other) + coord_compares = iris.analysis._dimensional_metadata_comparison( + self, other + ) # if there are any coordinates which are not equal result = not ( - coord_comparison["not_equal"] - or coord_comparison["non_equal_data_dimension"] + coord_compares["not_equal"] + or coord_compares["non_equal_data_dimension"] ) if result: - coord_comparison = iris.analysis.coord_comparison( + cm_compares = iris.analysis._dimensional_metadata_comparison( self, other, object_get=Cube.cell_measures, ) # if there are any cell measures which are not equal result = not ( - coord_comparison["not_equal"] - or coord_comparison["non_equal_data_dimension"] + cm_compares["not_equal"] + or cm_compares["non_equal_data_dimension"] ) if result: - coord_comparison = iris.analysis.coord_comparison( + av_compares = iris.analysis._dimensional_metadata_comparison( self, other, object_get=Cube.ancillary_variables, ) # if there are any ancillary variables which are not equal result = not ( - coord_comparison["not_equal"] - or coord_comparison["non_equal_data_dimension"] + av_compares["not_equal"] + or av_compares["non_equal_data_dimension"] ) # Having checked everything else, check approximate data equality. diff --git a/lib/iris/tests/test_analysis.py b/lib/iris/tests/test_analysis.py index 1ac6de8ce8..b39e1810fc 100644 --- a/lib/iris/tests/test_analysis.py +++ b/lib/iris/tests/test_analysis.py @@ -109,7 +109,7 @@ def test_coord_comparison(self): cube5.add_dim_coord(lon, 0) cube5.add_dim_coord(lat, 1) - coord_comparison = iris.analysis.coord_comparison + coord_comparison = iris.analysis._dimensional_metadata_comparison self.assertComparisonDict( coord_comparison(cube1, cube1), diff --git a/lib/iris/tests/test_cdm.py b/lib/iris/tests/test_cdm.py index d1f7fa3236..2c006e0e4f 100644 --- a/lib/iris/tests/test_cdm.py +++ b/lib/iris/tests/test_cdm.py @@ -1207,7 +1207,7 @@ def test_fancy_indexing_bool_array(self): class TestCubeCollapsed(tests.IrisTest): def partial_compare(self, dual, single): - result = iris.analysis.coord_comparison(dual, single) + result = iris.analysis._dimensional_metadata_comparison(dual, single) self.assertEqual(len(result["not_equal"]), 0) self.assertEqual( dual.name(),