From f93b9661e4a52fb6f4f4a319db4e514e7a3404a0 Mon Sep 17 00:00:00 2001 From: Will Benfold Date: Wed, 15 Sep 2021 15:20:58 +0100 Subject: [PATCH 1/6] Update to loading docs to cover absence of 'or' for constraints --- docs/src/userguide/loading_iris_cubes.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/src/userguide/loading_iris_cubes.rst b/docs/src/userguide/loading_iris_cubes.rst index 37c8fc3c12..8eb70a94f4 100644 --- a/docs/src/userguide/loading_iris_cubes.rst +++ b/docs/src/userguide/loading_iris_cubes.rst @@ -215,6 +215,14 @@ 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. This is because "or" constraints could lead to a cube which did + not cover a hyper-rectangular region if these constraints were on + different coordinates. If an "or" type constraint on a single coordinate + is useful then it may be obtained by passing a function to :class:`iris.Constraint`. + 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 From 84836f2277f4fbad74affaee250f090c938d50ca Mon Sep 17 00:00:00 2001 From: Will Benfold Date: Thu, 16 Sep 2021 10:55:05 +0100 Subject: [PATCH 2/6] Updated whats new --- docs/src/whatsnew/latest.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 34c1c56fe7..9e6ce18c3b 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -96,6 +96,9 @@ 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 `. (:pull:`4321`) + 💼 Internal =========== From e500a3c0bf1326848997b399e8d0bdb44b09fae3 Mon Sep 17 00:00:00 2001 From: Will Benfold Date: Fri, 17 Sep 2021 12:07:51 +0100 Subject: [PATCH 3/6] Moved more detailed explanation to Constraints class --- docs/src/userguide/loading_iris_cubes.rst | 14 +++++++++----- docs/src/whatsnew/latest.rst | 3 ++- lib/iris/_constraints.py | 20 ++++++++++++++++++++ 3 files changed, 31 insertions(+), 6 deletions(-) diff --git a/docs/src/userguide/loading_iris_cubes.rst b/docs/src/userguide/loading_iris_cubes.rst index 8eb70a94f4..a66af12b9c 100644 --- a/docs/src/userguide/loading_iris_cubes.rst +++ b/docs/src/userguide/loading_iris_cubes.rst @@ -217,11 +217,15 @@ constraint to ``load``:: .. note:: - Whilst ``&`` is supported, the ``|`` that might reasonably be expected - is not. This is because "or" constraints could lead to a cube which did - not cover a hyper-rectangular region if these constraints were on - different coordinates. If an "or" type constraint on a single coordinate - is useful then it may be obtained by passing a function to :class:`iris.Constraint`. + 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, diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 9e6ce18c3b..fc95eb2da2 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -97,7 +97,8 @@ This document explains the changes made to Iris for this release section `. (:pull:`4314`) #. `@wjbenfold`_ added explanation about the absence of | operator for - :class:`iris.Constraint` to :ref:`userguide loading section `. (:pull:`4321`) + :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..a0f4571f86 100644 --- a/lib/iris/_constraints.py +++ b/lib/iris/_constraints.py @@ -73,6 +73,26 @@ 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`. + + A constraint covering multiple ranges of the same coordinate may be + used to generate a single cube like so:: + + 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`. From 567646ac94ce4d06cbb9d86e37be06cd59cae63d Mon Sep 17 00:00:00 2001 From: Will Benfold Date: Fri, 17 Sep 2021 15:46:20 +0100 Subject: [PATCH 4/6] Mention extract_cubes() as well as load() --- lib/iris/_constraints.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/iris/_constraints.py b/lib/iris/_constraints.py index a0f4571f86..d8802b849d 100644 --- a/lib/iris/_constraints.py +++ b/lib/iris/_constraints.py @@ -83,7 +83,8 @@ def __init__(self, name=None, cube_func=None, coord_values=None, **kwargs): 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`. + the same coordinate, use :py:func:`iris.load_cubes` or + :py:func:`iris.cube.CubeList.extract_cubes`. A constraint covering multiple ranges of the same coordinate may be used to generate a single cube like so:: From aa1ed44faaeb53ba4b128b3214d3ca410de9834f Mon Sep 17 00:00:00 2001 From: Will Benfold Date: Mon, 20 Sep 2021 09:22:55 +0100 Subject: [PATCH 5/6] Amend description of example to fix discrepancy --- lib/iris/_constraints.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/iris/_constraints.py b/lib/iris/_constraints.py index d8802b849d..9a032b01f7 100644 --- a/lib/iris/_constraints.py +++ b/lib/iris/_constraints.py @@ -87,7 +87,7 @@ def __init__(self, name=None, cube_func=None, coord_values=None, **kwargs): :py:func:`iris.cube.CubeList.extract_cubes`. A constraint covering multiple ranges of the same coordinate may be - used to generate a single cube like so:: + created like so:: def latitude_bands(cell): return (0 < cell < 30) or (60 < cell < 90) From 6ab437ac01c52c096e1e06e930d6bc937bcc6807 Mon Sep 17 00:00:00 2001 From: Will Benfold Date: Mon, 20 Sep 2021 09:25:55 +0100 Subject: [PATCH 6/6] Amended again --- lib/iris/_constraints.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/iris/_constraints.py b/lib/iris/_constraints.py index 9a032b01f7..4e23793e1d 100644 --- a/lib/iris/_constraints.py +++ b/lib/iris/_constraints.py @@ -86,8 +86,8 @@ def __init__(self, name=None, cube_func=None, coord_values=None, **kwargs): the same coordinate, use :py:func:`iris.load_cubes` or :py:func:`iris.cube.CubeList.extract_cubes`. - A constraint covering multiple ranges of the same coordinate may be - created like so:: + 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)