Skip to content

Commit

Permalink
Enhance Cube slicing docs (#5735)
Browse files Browse the repository at this point in the history 
* 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>
  • Loading branch information
@hsteptoe @pre-commit-ci @trexfeathers
3 people authored Apr 16, 2024
1 parent a09c277 commit 6cc7c3d
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 22 deletions.
4 changes: 2 additions & 2 deletions docs/src/whatsnew/latest.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
99 changes: 79 additions & 20 deletions lib/iris/cube.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
-----
Expand All @@ -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]
Expand Down Expand Up @@ -3463,29 +3490,61 @@ 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
-------
An iterator of subcubes.
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.")

Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand Down

0 comments on commit 6cc7c3d

Please sign in to comment.