diff --git a/docs/iris/src/userguide/merge_and_concat.rst b/docs/iris/src/userguide/merge_and_concat.rst index 8321f4106e..b742b3ef5f 100644 --- a/docs/iris/src/userguide/merge_and_concat.rst +++ b/docs/iris/src/userguide/merge_and_concat.rst @@ -398,7 +398,7 @@ Merge Differences in the :data:`~iris.cube.Cube.attributes` the input cubes probably cause the greatest amount of merge-related difficulties. In recognition of this, Iris has a helper function, -:func:`~iris.experimental.equalise_cubes.equalise_attributes`, to equalise +:func:`~iris.util.equalise_attributes`, to equalise attributes differences in the input cubes. .. note:: @@ -407,16 +407,16 @@ attributes differences in the input cubes. :meth:`iris.cube.Cube.is_compatible` are **not** designed to give user indication of whether two cubes can be merged. -To demonstrate using :func:`~iris.experimental.equalise_cubes.equalise_attributes`, +To demonstrate using :func:`~iris.util.equalise_attributes`, let's return to our non-merging list of input cubes from the merge_cube example from earlier. -We'll call :func:`~iris.experimental.equalise_cubes.equalise_attributes` on the +We'll call :func:`~iris.util.equalise_attributes` on the input cubes before merging the input cubes using :meth:`~iris.cube.CubeList.merge_cube`: .. doctest:: merge_vs_merge_cube :options: +ELLIPSIS, +NORMALIZE_WHITESPACE - >>> from iris.experimental.equalise_cubes import equalise_attributes + >>> from iris.util import equalise_attributes >>> print(cubes) 0: air_temperature / (kelvin) (y: 4; x: 5) 1: air_temperature / (kelvin) (y: 4; x: 5) diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-13_move_experimental_equalise_cubes.txt b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-13_move_experimental_equalise_cubes.txt new file mode 100644 index 0000000000..a7ddaa441b --- /dev/null +++ b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-13_move_experimental_equalise_cubes.txt @@ -0,0 +1,3 @@ +* The :func:`iris.experimental.equalise_cubes.equalise_attributes` function has been moved from the + :mod:`iris.experimental` module into the :mod:`iris.util` module. Please use the :func:`iris.util.equalise_attributes` + function instead. diff --git a/lib/iris/experimental/equalise_cubes.py b/lib/iris/experimental/equalise_cubes.py index fc0e71f7ad..8be7175067 100644 --- a/lib/iris/experimental/equalise_cubes.py +++ b/lib/iris/experimental/equalise_cubes.py @@ -8,38 +8,23 @@ """ -import numpy as np - def equalise_attributes(cubes): """ Delete cube attributes that are not identical over all cubes in a group. - This function simply deletes any attributes which are not the same for - all the given cubes. The cubes will then have identical attributes. The - given cubes are modified in-place. + .. warning:: - Args: + This function is now **disabled**. - * cubes (iterable of :class:`iris.cube.Cube`): - A collection of cubes to compare and adjust. + The functionality has been moved to + :func:`iris.util.equalise_attributes`. """ - # Work out which attributes are identical across all the cubes. - common_keys = list(cubes[0].attributes.keys()) - for cube in cubes[1:]: - cube_keys = list(cube.attributes.keys()) - common_keys = [ - key - for key in common_keys - if ( - key in cube_keys - and np.all(cube.attributes[key] == cubes[0].attributes[key]) - ) - ] - - # Remove all the other attributes. - for cube in cubes: - for key in list(cube.attributes.keys()): - if key not in common_keys: - del cube.attributes[key] + old = "iris.experimental.equalise_cubes.equalise_attributes" + new = "iris.util.equalise_attributes" + emsg = ( + f'The function "{old}" has been moved.\n' + f'Please replace "{old}()" with "{new}()".' + ) + raise Exception(emsg) diff --git a/lib/iris/tests/unit/experimental/equalise_cubes/__init__.py b/lib/iris/tests/unit/experimental/equalise_cubes/__init__.py deleted file mode 100644 index 5d470b347b..0000000000 --- a/lib/iris/tests/unit/experimental/equalise_cubes/__init__.py +++ /dev/null @@ -1,6 +0,0 @@ -# Copyright Iris contributors -# -# This file is part of Iris and is released under the LGPL license. -# See COPYING and COPYING.LESSER in the root of the repository for full -# licensing details. -"""Unit tests for the `iris.experimental.equalise_cubes` package.""" diff --git a/lib/iris/tests/unit/experimental/equalise_cubes/test_equalise_attributes.py b/lib/iris/tests/unit/util/test_equalise_attributes.py similarity index 96% rename from lib/iris/tests/unit/experimental/equalise_cubes/test_equalise_attributes.py rename to lib/iris/tests/unit/util/test_equalise_attributes.py index 1778e770cd..6b783bf0e0 100644 --- a/lib/iris/tests/unit/experimental/equalise_cubes/test_equalise_attributes.py +++ b/lib/iris/tests/unit/util/test_equalise_attributes.py @@ -4,8 +4,7 @@ # See COPYING and COPYING.LESSER in the root of the repository for full # licensing details. """ -Unit tests for the :func:`iris.experimental.equalise_cubes.equalise_attributes` -function. +Unit tests for the :func:`iris.util.equalise_attributes` function. """ @@ -16,7 +15,7 @@ import numpy as np from iris.cube import Cube -from iris.experimental.equalise_cubes import equalise_attributes +from iris.util import equalise_attributes import iris.tests.stock diff --git a/lib/iris/util.py b/lib/iris/util.py index 8b90798538..618eff6912 100644 --- a/lib/iris/util.py +++ b/lib/iris/util.py @@ -1794,3 +1794,37 @@ def mask_cube(cube, points_to_mask): cube.data = ma.masked_array(cube.data) cube.data[points_to_mask] = ma.masked return cube + + +def equalise_attributes(cubes): + """ + Delete cube attributes that are not identical over all cubes in a group. + + This function simply deletes any attributes which are not the same for + all the given cubes. The cubes will then have identical attributes. The + given cubes are modified in-place. + + Args: + + * cubes (iterable of :class:`iris.cube.Cube`): + A collection of cubes to compare and adjust. + + """ + # Work out which attributes are identical across all the cubes. + common_keys = list(cubes[0].attributes.keys()) + for cube in cubes[1:]: + cube_keys = list(cube.attributes.keys()) + common_keys = [ + key + for key in common_keys + if ( + key in cube_keys + and np.all(cube.attributes[key] == cubes[0].attributes[key]) + ) + ] + + # Remove all the other attributes. + for cube in cubes: + for key in list(cube.attributes.keys()): + if key not in common_keys: + del cube.attributes[key]