From 6cc7c3df60f00689f5d4d5b3ed8ad218b90a59e0 Mon Sep 17 00:00:00 2001 From: Hamish Steptoe Date: Tue, 16 Apr 2024 09:39:54 +0100 Subject: [PATCH] Enhance Cube slicing docs (#5735) * Enhance examples for cube.slices() * Enhance docs for cube.slices_over * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Spelling and naming consistency edits * Update latest.rst * Update latest.rst spelling * Fix author name link * Fixing doctests * More docstring fixes * Add doctest: SKIP Adding `# doctest: SKIP` statements to multiline prints * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add ruff linting exceptions Add ruff linting exceptions to avoid getting stuck in a failing test loop * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Yet more docstring tweaks * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Fix indents * Fixes doctests for slices and slices_over * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Typo fixes --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Martin Yeo <40734014+trexfeathers@users.noreply.github.com> --- docs/src/whatsnew/latest.rst | 4 +- lib/iris/cube.py | 99 ++++++++++++++++++++++++++++-------- 2 files changed, 81 insertions(+), 22 deletions(-) diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index fc189a4495..29818ded77 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -77,7 +77,7 @@ This document explains the changes made to Iris for this release 📚 Documentation ================ -#. N/A +#. `@hsteptoe`_ added more detailed examples to :class:`~iris.cube.Cube` functions :func:`~iris.cube.Cube.slices` and :func:`~iris.cube.Cube.slices_over`. (:pull:`5735`) 💼 Internal @@ -90,7 +90,7 @@ This document explains the changes made to Iris for this release Whatsnew author names (@github name) in alphabetical order. Note that, core dev names are automatically included by the common_links.inc: - +.. _@hsteptoe: https://github.com/hsteptoe .. comment diff --git a/lib/iris/cube.py b/lib/iris/cube.py index ca3039cb5b..fecbcaf0da 100644 --- a/lib/iris/cube.py +++ b/lib/iris/cube.py @@ -3403,10 +3403,37 @@ def slices_over(self, ref_to_slice): Examples -------- - For example, to get all subcubes along the time dimension:: - - for sub_cube in cube.slices_over('time'): - print(sub_cube) + For example, for a cube with dimensions `realization`, `time`, `latitude` and + `longitude`: + + >>> fname = iris.sample_data_path('GloSea4', 'ensemble_01[01].pp') + >>> cube = iris.load_cube(fname, 'surface_temperature') + >>> print(cube.summary(shorten=True)) + surface_temperature / (K) (realization: 2; time: 6; latitude: 145; longitude: 192) + + To get all 12x2D longitude/latitude subcubes: + + >>> for sub_cube in cube.slices_over(['realization', 'time']): + ... print(sub_cube.summary(shorten=True)) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + surface_temperature / (K) (latitude: 145; longitude: 192) + + To get realizations as 2x3D separate subcubes, using the `realization` dimension index: + + >>> for sub_cube in cube.slices_over(0): + ... print(sub_cube.summary(shorten=True)) + surface_temperature / (K) (time: 6; latitude: 145; longitude: 192) + surface_temperature / (K) (time: 6; latitude: 145; longitude: 192) Notes ----- @@ -3421,7 +3448,7 @@ def slices_over(self, ref_to_slice): iris.cube.Cube.slices : Return an iterator of all subcubes given the coordinates or dimension indices. - """ + """ # noqa: D214, D406, D407, D410, D411 # Required to handle a mix between types. if _is_single_item(ref_to_slice): ref_to_slice = [ref_to_slice] @@ -3463,10 +3490,9 @@ def slices(self, ref_to_slice, ordered=True): A mix of input types can also be provided. They must all be orthogonal (i.e. point to different dimensions). ordered : bool, default=True - If True, the order which the coords to slice or data_dims - are given will be the order in which they represent the data in - the resulting cube slices. If False, the order will follow that of - the source cube. Default is True. + If True, subcube dimensions are ordered to match the dimension order + in `ref_to_slice`. If False, the order will follow that of + the source cube. Returns ------- @@ -3474,18 +3500,51 @@ def slices(self, ref_to_slice, ordered=True): Examples -------- - For example, to get all 2d longitude/latitude subcubes from a - multi-dimensional cube:: - - for sub_cube in cube.slices(['longitude', 'latitude']): - print(sub_cube) + For example, for a cube with dimensions `realization`, `time`, `latitude` and + `longitude`: + + >>> fname = iris.sample_data_path('GloSea4', 'ensemble_01[01].pp') + >>> cube = iris.load_cube(fname, 'surface_temperature') + >>> print(cube.summary(shorten=True)) + surface_temperature / (K) (realization: 2; time: 6; latitude: 145; longitude: 192) + + To get all 12x2D longitude/latitude subcubes: + + >>> for sub_cube in cube.slices(['longitude', 'latitude']): + ... print(sub_cube.summary(shorten=True)) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + surface_temperature / (K) (longitude: 192; latitude: 145) + + + .. warning:: + Note that the dimension order returned in the sub_cubes matches the order specified + in the ``cube.slices`` call, *not* the order of the dimensions in the original cube. + + To get all realizations as 2x3D separate subcubes, using the `time`, `latitude` + and `longitude` dimensions' indices: + + >>> for sub_cube in cube.slices([1, 2, 3]): + ... print(sub_cube.summary(shorten=True)) + surface_temperature / (K) (time: 6; latitude: 145; longitude: 192) + surface_temperature / (K) (time: 6; latitude: 145; longitude: 192) See Also -------- - iris.cube.Cube.slices : - Return an iterator of all subcubes given the coordinates or dimension indices. + iris.cube.Cube.slices_over : + Return an iterator of all subcubes along a given coordinate or + dimension index. - """ + """ # noqa: D214, D406, D407, D410, D411 if not isinstance(ordered, bool): raise TypeError("'ordered' argument to slices must be boolean.") @@ -4512,8 +4571,8 @@ def rolling_window(self, coord, aggregator, window, **kwargs): -------- >>> import iris, iris.analysis >>> fname = iris.sample_data_path('GloSea4', 'ensemble_010.pp') - >>> air_press = iris.load_cube(fname, 'surface_temperature') - >>> print(air_press) + >>> cube = iris.load_cube(fname, 'surface_temperature') + >>> print(cube) surface_temperature / (K) \ (time: 6; latitude: 145; longitude: 192) Dimension coordinates: @@ -4537,7 +4596,7 @@ def rolling_window(self, coord, aggregator, window, **kwargs): 'Data from Met Office Unified Model' um_version '7.6' - >>> print(air_press.rolling_window('time', iris.analysis.MEAN, 3)) + >>> print(cube.rolling_window('time', iris.analysis.MEAN, 3)) surface_temperature / (K) \ (time: 4; latitude: 145; longitude: 192) Dimension coordinates: