diff --git a/lib/iris/analysis/__init__.py b/lib/iris/analysis/__init__.py index 0544cd8cb4..4c93c5aad8 100644 --- a/lib/iris/analysis/__init__.py +++ b/lib/iris/analysis/__init__.py @@ -186,58 +186,14 @@ 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. - - Return a dictionary where the key represents the statement, - "Given these cubes list the coordinates which, - when grouped by metadata, are/have..." - - Keys: - - * grouped_coords - A list of coordinate groups of all the coordinates grouped together - by their coordinate definition - * ungroupable - A list of coordinate groups which contain at least one None, - meaning not all Cubes provide an equivalent coordinate - * not_equal - A list of coordinate groups of which not all are equal - (superset of ungroupable) - * no_data_dimension - A list of coordinate groups of which all have no data dimensions on - their respective cubes - * scalar - A list of coordinate groups of which all have shape (1, ) - * non_equal_data_dimension - A list of coordinate groups of which not all have the same - data dimension on their respective cubes - * non_equal_shape - A list of coordinate groups of which not all have the same shape - * equal_data_dimension - A list of coordinate groups of which all have the same data dimension - on their respective cubes - * equal - A list of coordinate groups of which all are equal - * ungroupable_and_dimensioned - A list of coordinate groups of which not all cubes had an equivalent - (in metadata) coordinate which also describe a data dimension - * dimensioned - A list of coordinate groups of which all describe a data dimension on - their respective cubes - * ignorable - A list of scalar, ungroupable non_equal coordinate groups - * resamplable - A list of equal, different data dimensioned coordinate groups - * transposable - A list of non equal, same data dimensioned, non scalar coordinate groups + This is a generalised form of :func:`coord_comparison`. See that function + for a more detailed description. - Example usage:: - - result = coord_comparison(cube1, cube2) - print('All equal coordinates: ', result['equal']) + Additionally, this function can compare over different types of dimensional + metadata with the argument object_get. For example, :func:`coord_comparison` + effectively has object_get=:meth:`iris.cube.Cube.coords`. """ if object_get is None: @@ -397,6 +353,63 @@ def no_data_dim_fn(cube, coord): return result +def coord_comparison(*cubes): + """ + Convenience function to help compare coordinates on one or more cubes + by their metadata. + + Return a dictionary where the key represents the statement, + "Given these cubes list the coordinates which, + when grouped by metadata, are/have..." + + Keys: + + * grouped_coords + A list of coordinate groups of all the coordinates grouped together + by their coordinate definition + * ungroupable + A list of coordinate groups which contain at least one None, + meaning not all Cubes provide an equivalent coordinate + * not_equal + A list of coordinate groups of which not all are equal + (superset of ungroupable) + * no_data_dimension + A list of coordinate groups of which all have no data dimensions on + their respective cubes + * scalar + A list of coordinate groups of which all have shape (1, ) + * non_equal_data_dimension + A list of coordinate groups of which not all have the same + data dimension on their respective cubes + * non_equal_shape + A list of coordinate groups of which not all have the same shape + * equal_data_dimension + A list of coordinate groups of which all have the same data dimension + on their respective cubes + * equal + A list of coordinate groups of which all are equal + * ungroupable_and_dimensioned + A list of coordinate groups of which not all cubes had an equivalent + (in metadata) coordinate which also describe a data dimension + * dimensioned + A list of coordinate groups of which all describe a data dimension on + their respective cubes + * ignorable + A list of scalar, ungroupable non_equal coordinate groups + * resamplable + A list of equal, different data dimensioned coordinate groups + * transposable + A list of non equal, same data dimensioned, non scalar coordinate groups + + Example usage:: + + result = coord_comparison(cube1, cube2) + print('All equal coordinates: ', result['equal']) + + """ + return _dimensional_metadata_comparison(*cubes) + + class _Aggregator: """ The :class:`_Aggregator` base class provides common aggregation diff --git a/lib/iris/cube.py b/lib/iris/cube.py index 3ff77fa1ad..9f7550d0f3 100644 --- a/lib/iris/cube.py +++ b/lib/iris/cube.py @@ -3575,23 +3575,23 @@ def __eq__(self, other): ) if result: - coord_comparison = iris.analysis.coord_comparison( + comparison = 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"] + comparison["not_equal"] + or comparison["non_equal_data_dimension"] ) if result: - coord_comparison = iris.analysis.coord_comparison( + comparison = 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"] + comparison["not_equal"] + or comparison["non_equal_data_dimension"] ) # Having checked everything else, check approximate data equality.