diff --git a/docs/src/userguide/loading_iris_cubes.rst b/docs/src/userguide/loading_iris_cubes.rst index 37c8fc3c12..a66af12b9c 100644 --- a/docs/src/userguide/loading_iris_cubes.rst +++ b/docs/src/userguide/loading_iris_cubes.rst @@ -215,6 +215,18 @@ constraint to ``load``:: level_10 = iris.Constraint(model_level_number=10) cubes = iris.load(filename, forecast_6 & level_10) +.. note:: + + Whilst ``&`` is supported, the ``|`` that might reasonably be expected is + not. Explanation as to why is in the :class:`iris.Constraint` reference + documentation. + + For an example of constraining to multiple ranges of the same coordinate to + generate one cube, see the :class:`iris.Constraint` reference documentation. + + To generate multiple cubes, each constrained to a different range of the + same coordinate, use :py:func:`iris.load_cubes`. + As well as being able to combine constraints using ``&``, the :class:`iris.Constraint` class can accept multiple arguments, and a list of values can be given to constrain a coordinate to one of diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 34c1c56fe7..fc95eb2da2 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -96,6 +96,10 @@ This document explains the changes made to Iris for this release #. `@wjbenfold`_ improved readability in :ref:`userguide interpolation section `. (:pull:`4314`) +#. `@wjbenfold`_ added explanation about the absence of | operator for + :class:`iris.Constraint` to :ref:`userguide loading section + ` and to api reference documentation. (:pull:`4321`) + 💼 Internal =========== diff --git a/lib/iris/_constraints.py b/lib/iris/_constraints.py index 46d9af8e7e..4e23793e1d 100644 --- a/lib/iris/_constraints.py +++ b/lib/iris/_constraints.py @@ -73,6 +73,27 @@ def __init__(self, name=None, cube_func=None, coord_values=None, **kwargs): model_level_number=[10, 12]) & Constraint(ensemble_member=2) + .. note:: + Whilst ``&`` is supported, the ``|`` that might reasonably be expected + is not. This is because each constraint describes a boxlike region, and + thus the intersection of these constraints (obtained with ``&``) will + also describe a boxlike region. Allowing the union of two constraints + (with the ``|`` symbol) would allow the description of a non-boxlike + region. These are difficult to describe with cubes and so it would be + ambiguous what should be extracted. + + To generate multiple cubes, each constrained to a different range of + the same coordinate, use :py:func:`iris.load_cubes` or + :py:func:`iris.cube.CubeList.extract_cubes`. + + A cube can be constrained to multiple ranges within the same coordinate + using something like the following constraint:: + + def latitude_bands(cell): + return (0 < cell < 30) or (60 < cell < 90) + + Constraint(cube_func=latitude_bands) + Constraint filtering is performed at the cell level. For further details on how cell comparisons are performed see :class:`iris.coords.Cell`.