cf.Field.indices

Field.indices(*exact, **kwargs)

Create data array indices based on domain metadata.

If metadata values are 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 coordinate value conditions may be given in any order.

See also

where, subspace

Parameters:

kwargs : optional

Keyword parameters identify items of the domain () and set conditions on their data arrays. 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 domain. The string may be any string value allowed by items 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 X will select the item returned by f.item('X', role='dam'). The role='dam' parameter is applied to exclude coordinate reference objects. 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 : characeter 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

By default keyword parameter names assumed considered to be regular expressions understood by the re module. If exact is the string 'exact' then keyword parameter names are not treated as regular expressions. See cf.Field.item for details.

Example:

f.indices(time=cf.dt('2001-12-1')) will identify an item with f.item('time', role='dam') whilst f.indices('exact', time=cf.dt('2001-12-1')) will idientify an item with f.item('time', role='dam', exact=True). See the kwargs parameters for details.

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))