8000 Enhance Cube slicing docs by hsteptoe · Pull Request #5735 · SciTools/iris · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Enhance Cube slicing docs #5735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 23 commits into from
Apr 16, 2024
Merged

Enhance Cube slicing docs #5735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
19a52c8
Enhance examples for cube.slices()
hsteptoe Feb 7, 2024
6afcc19
Enhance docs for cube.slices_over
hsteptoe Feb 7, 2024
605ab4a
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 7, 2024
7e0e16a
Spelling and naming consistency edits
hsteptoe Feb 7, 2024
f9bed16
Fix pre-commit conflicts
hsteptoe Feb 7, 2024
0a2cc7f
Update latest.rst
hsteptoe Feb 7, 2024
9f0d9e4
Update latest.rst spelling
hsteptoe Feb 7, 2024
5f70126
Fix author name link
hsteptoe Feb 9, 2024
7f4382e
Fixing doctests
hsteptoe Feb 9, 2024
48d4feb
More docstring fixes
hsteptoe Feb 9, 2024
fe43e09
Add doctest: SKIP
hsteptoe Feb 9, 2024
a64a4ec
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 9, 2024
9159ab7
Add ruff linting exceptions
hsteptoe Feb 9, 2024
d6d42bf
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 9, 2024
d6a775b
Yet more docstring tweaks
hsteptoe Feb 9, 2024
0344ae3
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 9, 2024
8406ad0
Fix indents
hsteptoe Feb 9, 2024
3acd4f7
Merge branch 'main' into Cube-slice-docs
hsteptoe Feb 9, 2024
ad7cc92
Merge branch 'main' into Cube-slice-docs
trexfeathers Apr 4, 2024
04ff0e1
Merge branch 'SciTools:main' into Cube-slice-docs
hsteptoe Apr 9, 2024
55008a7
Fixes doctests for slices and slices_over
hsteptoe Apr 9, 2024
f06aa46
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Apr 9, 2024
13abd1a
Typo fixes
hsteptoe Apr 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8000
4 changes: 2 additions & 2 deletions docs/src/whatsnew/latest.rst
View file
Open in desktop
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
Open in desktop
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