cf.Field.indices

Field.indices(*args, **kwargs)

Create indices based on domain metadata that define a subspace of the field.

The subspace is defined in “domain space” via data array values of its domain items: dimension coordinate, auxiliary coordinate, cell measure, domain ancillary and field ancillary objects.

If metadata items are not specified for an axis then a full slice (slice(None)) is assumed for that axis.

Values for size 1 axes which are not spanned by the field’s data array may be specified, but only indices for axes which span the field’s data array will be returned.

The conditions may be given in any order.

See also

where, subspace

Parameters:

args: optional

arg	Description
'exact'	Keyword parameter names are not treated as abbreviations of item identities. By default, keyword parameter names are allowed to be abbreviations of item identities.
'compress'
'envelope'
'full'

kwargs: optional

Keyword parameters identify items of the domain (such as a particular coordinate type) and its value sets conditions on their data arrays (e.g. the actual coordinate values). Indices are created which, for each axis, select where the conditions are met.

A keyword name is a string which selects a unique item of the field. The string may be any string value allowed by the description parameter of the field’s item method, which is used to select a unique domain item. See cf.Field.item for details.

Example:

The keyword lat will select the item returned by f.item('lat', role='dam'). See the exact parameter.

In general, a keyword value specifies a test on the selected item’s data array which identifies axis elements. The returned indices for this axis are the positions of these elements.

Example:

To create indices for the northern hemisphere, assuming that there is a coordinate with identity “latitude”: f.indices(latitude=cf.ge(0))

Example:

To create indices for the northern hemisphere, identifying the latitude coordinate by its long name: f.indices(**{'long_name:latitude': cf.ge(0)}). In this case it is necessary to use the ** syntax because the : character is not allowed in keyword parameter names.

If the value is a slice object then it is used as the axis indices, without testing the item’s data array.

Example:

To create indices for every even numbered element along the “Z” axis: f.indices(Z=slice(0, None, 2)).

Multidimensional items

Indices based on items which span two or more axes are possible if the result is a single element index for each of the axes spanned. In addition, two or more items must be provided, each one spanning the same axes (in any order).

Example:

To create indices for the unique location 45 degrees north, 30 degrees east when latitude and longitude are stored in 2-dimensional auxiliary coordiantes: f.indices(latitude=45, longitude=30). Note that this example would also work if latitude and longitude were stored in 1-dimensional dimensional or auxiliary coordinates, but in this case the location would not have to be unique.

exact: str, optional

Returns:

out: tuple

Examples:

These examples use the following field, which includes a dimension coordinate object with no identity (ncvar:model_level_number) and which has a data array which doesn’t span all of the domain axes:

>>> print f
eastward_wind field summary
---------------------------
Data           : eastward_wind(time(3), air_pressure(5), grid_latitude(110), grid_longitude(106)) m s-1
Cell methods   : time: mean
Axes           : time(3) = [1979-05-01 12:00:00, ..., 1979-05-03 12:00:00] gregorian
               : air_pressure(5) = [850.0, ..., 50.0] hPa
               : grid_longitude(106) = [-20.54, ..., 25.66] degrees
               : grid_latitude(110) = [23.32, ..., -24.64] degrees
Aux coords     : latitude(grid_latitude(110), grid_longitude(106)) = [[67.12, ..., 22.89]] degrees_N
               : longitude(grid_latitude(110), grid_longitude(106)) = [[-45.98, ..., 35.29]] degrees_E
Coord refs     : <CF CoordinateReference: rotated_latitude_longitude>

>>> f.indices(lat=23.32, lon=-20.54)
(slice(0, 3, 1), slice(0, 5, 1), slice(0, 1, 1), slice(0, 1, 1))

>>> f.indices(grid_lat=slice(50, 2, -2), grid_lon=[0, 1, 3, 90]) 
(slice(0, 3, 1), slice(0, 5, 1), slice(50, 2, -2), [0, 1, 3, 90])

>>> f.indices('exact', grid_latitude=slice(50, 2, -2), grid_longitude=[0, 1, 3, 90]) 
(slice(0, 3, 1), slice(0, 5, 1), slice(50, 2, -2), [0, 1, 3, 90])

>>> f.indices(grid_lon=cf.wi(0, 10, 'degrees'), air_pressure=850)
(slice(0, 3, 1), slice(0, 1, 1), slice(0, 110, 1), slice(47, 70, 1))

>>> f.indices(grid_lon=cf.wi(0, 10), air_pressure=cf.eq(85000, 'Pa')
(slice(0, 3, 1), slice(0, 1, 1), slice(0, 110, 1), slice(47, 70, 1))

>>> f.indices(grid_long=cf.gt(0, attr='lower_bounds'))
(slice(0, 3, 1), slice(0, 5, 1), slice(0, 110, 1), slice(48, 106, 1))