cf.Field.indices

Field.indices(*mode, **kwargs)[source]

Create indices that define a subspace of the field construct.

The subspace is defined by identifying indices based on the metadata constructs.

Metadata constructs are selected conditions are specified on their data. Indices for subspacing are then automatically inferred from where the conditions are met.

The returned tuple of indices may be used to created a subspace by indexing the original field construct with them.

Metadata constructs and the conditions on their data are defined by keyword parameters.

  • Any domain axes that have not been identified remain unchanged.

  • Multiple domain axes may be subspaced simultaneously, and it doesn’t matter which order they are specified in.

  • Subspace criteria may be provided for size 1 domain axes that are not spanned by the field construct’s data.

  • Explicit indices may also be assigned to a domain axis identified by a metadata construct, with either a Python slice object, or a sequence of integers or booleans.

  • For a dimension that is cyclic, a subspace defined by a slice or by a Query instance is assumed to “wrap” around the edges of the data.

  • Conditions may also be applied to multi-dimensional metadata constructs. The “compress” mode is still the default mode (see the positional arguments), but because the indices may not be acting along orthogonal dimensions, some missing data may still need to be inserted into the field construct’s data.

Auxiliary masks

When creating an actual subspace with the indices, if the first element of the tuple of indices is 'mask' then the extent of the subspace is defined only by the values of elements three and onwards. In this case the second element contains an “auxiliary” data mask that is applied to the subspace after its initial creation, in order to set unselected locations to missing data.

See also

subspace, where, __getitem__, __setitem__

Parameters
mode: str, optional

There are three modes of operation, each of which provides indices for a different type of subspace:

mode

Description

'compress'

This is the default mode. Unselected locations are removed to create the returned subspace. Note that if a multi-dimensional metadata construct is being used to define the indices then some missing data may still be inserted at unselected locations.

'envelope'

The returned subspace is the smallest that contains all of the selected indices. Missing data is inserted at unselected locations within the envelope.

'full'

The returned subspace has the same domain as the original field construct. Missing data is inserted at unselected locations.
kwargs: optional

A keyword name is an identity of a metadata construct, and the keyword value provides a condition for inferring indices that apply to the dimension (or dimensions) spanned by the metadata construct’s data. Indices are created that select every location for which the metadata construct’s data satisfies the condition.

Returns
tuple

The indices meeting the conditions.

Examples:

>>> q = cf.example_field(0)
>>> print(q)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), longitude(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
>>> indices = q.indices(X=112.5)
>>> print(indices)
(slice(0, 5, 1), slice(2, 3, 1))
>>> q[indices]
<CF Field: specific_humidity(latitude(5), longitude(1)) 1>
>>> q.indices(X=112.5, latitude=cf.gt(-60))
(slice(1, 5, 1), slice(2, 3, 1))
>>> q.indices(latitude=cf.eq(-45) | cf.ge(20))
(array([1, 3, 4]), slice(0, 8, 1))
>>> q.indices(X=[1, 2, 4], Y=slice(None, None, -1))
(slice(4, None, -1), array([1, 2, 4]))
>>> q.indices(X=cf.wi(-100, 200))
(slice(0, 5, 1), slice(-2, 4, 1))
>>> q.indices(X=slice(-2, 4))
(slice(0, 5, 1), slice(-2, 4, 1))
>>> q.indices('compress', X=[1, 2, 4, 6])
(slice(0, 5, 1), array([1, 2, 4, 6]))
>>> q.indices(Y=[True, False, True, True, False])
(array([0, 2, 3]), slice(0, 8, 1))
>>> q.indices('envelope', X=[1, 2, 4, 6])
('mask', [<CF Data(1, 6): [[False, ..., False]]>], slice(0, 5, 1), slice(1, 7, 1))
>>> indices = q.indices('full', X=[1, 2, 4, 6])
('mask', [<CF Data(1, 8): [[True, ..., True]]>], slice(0, 5, 1), slice(0, 8, 1))
>>> print(indices)
>>> print(q)
<CF Field: specific_humidity(latitude(5), longitude(8)) 1>

>>> print(a)
Field: air_potential_temperature (ncvar%air_potential_temperature)
------------------------------------------------------------------
Data            : air_potential_temperature(time(120), latitude(5), longitude(8)) K
Cell methods    : area: mean
Dimension coords: time(120) = [1959-12-16 12:00:00, ..., 1969-11-16 00:00:00]
                : latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : air_pressure(1) = [850.0] hPa
>>> a.indices(T=410.5)
(slice(2, 3, 1), slice(0, 5, 1), slice(0, 8, 1))
>>> a.indices(T=cf.dt('1960-04-16'))
(slice(4, 5, 1), slice(0, 5, 1), slice(0, 8, 1))
>>> indices = a.indices(T=cf.wi(cf.dt('1962-11-01'),
...                             cf.dt('1967-03-17 07:30')))
>>> print(indices)
(slice(35, 88, 1), slice(0, 5, 1), slice(0, 8, 1))
>>> a[indices]
<CF Field: air_potential_temperature(time(53), latitude(5), longitude(8)) K>

>>> print(t)
Field: air_temperature (ncvar%ta)
---------------------------------
Data            : air_temperature(atmosphere_hybrid_height_coordinate(1), grid_latitude(10), grid_longitude(9)) K
Cell methods    : grid_latitude(10): grid_longitude(9): mean where land (interval: 0.1 degrees) time(1): maximum
Field ancils    : air_temperature standard_error(grid_latitude(10), grid_longitude(9)) = [[0.76, ..., 0.32]] K
Dimension coords: atmosphere_hybrid_height_coordinate(1) = [1.5]
                : grid_latitude(10) = [2.2, ..., -1.76] degrees
                : grid_longitude(9) = [-4.7, ..., -1.18] degrees
                : time(1) = [2019-01-01 00:00:00]
Auxiliary coords: latitude(grid_latitude(10), grid_longitude(9)) = [[53.941, ..., 50.225]] degrees_N
                : longitude(grid_longitude(9), grid_latitude(10)) = [[2.004, ..., 8.156]] degrees_E
                : long_name=Grid latitude name(grid_latitude(10)) = [--, ..., b'kappa']
Cell measures   : measure:area(grid_longitude(9), grid_latitude(10)) = [[2391.9657, ..., 2392.6009]] km2
Coord references: grid_mapping_name:rotated_latitude_longitude
                : standard_name:atmosphere_hybrid_height_coordinate
Domain ancils   : ncvar%a(atmosphere_hybrid_height_coordinate(1)) = [10.0] m
                : ncvar%b(atmosphere_hybrid_height_coordinate(1)) = [20.0]
                : surface_altitude(grid_latitude(10), grid_longitude(9)) = [[0.0, ..., 270.0]] m
>>> indices = t.indices(latitude=cf.wi(51, 53))
>>> print(indices)
('mask', [<CF Data(1, 5, 9): [[[False, ..., False]]]>], slice(0, 1, 1), slice(3, 8, 1), slice(0, 9, 1))
>>> t[indices]
<CF Field: air_temperature(atmosphere_hybrid_height_coordinate(1), grid_latitude(5), grid_longitude(9)) K>