cf.Field.subspace

Field.subspace()

Return a new object which will get or set a subspace of the field.

The returned object is a SubspaceField object which may be indexed to select a subspace by axis index values (f.subspace[indices]) or called to select a subspace by metadata values (f.subspace(*exact, **metadata_values)).

Subspacing by indexing

Subspacing by indices allows a subspaced field to be defined via index values for the axes of the field’s data array.

Indices to the returned SubspaceField object have an extended Python slicing syntax, which is similar to numpy array indexing, but with three extensions:

  • Size 1 axes are never removed.

    An integer index i takes the i-th element but does not reduce the rank of the output array by one:

  • The indices for each axis work independently.

    When more than one axis’s slice is a 1-d boolean sequence or 1-d sequence of integers, then these indices work independently along each axis (similar to the way vector subscripts work in Fortran), rather than by their elements:

  • Boolean indices may be any object which exposes the numpy array interface.

Subspacing by metadata values

A subspaced field may be defined via data array values of its domain items (dimension coordinate, auciliary coordinate and cell measured objects) by calling the SubspaceField object.

f.subspace(*exact, **metadata_values) is a shorthand for f.subspace[f.indices(*exact, **metadata_values)]. See cf.Field.indices for details.

Assignment to subspaces

Elements of a field’s data array may be changed by assigning values to a subspace of the field.

Assignment is only possible to a subspace defined by indices of the returned SubspaceField object. For example, f.subspace[indices] = 0 is possible, but f.subspace(*exact, **metadata_values) = 0 is not allowed. However, assigning to a subspace defined by metadata values may be done as follows: f.subspace[f.indices(*exact, **metadata_values)] = 0.

Missing data

The treatment of missing data elements during assignment to a subspace depends on the value of field’s hardmask attribute. If it is True then masked elements will not be unmasked, otherwise masked elements may be set to any value.

In either case, unmasked elements may be set, (including missing data).

Unmasked elements may be set to missing data by assignment to the cf.masked constant or by assignment to a value which contains masked elements.

See also

cf.masked, hardmask, indices, where

Examples: 
>>> print f
Data            : air_temperature(time(12), latitude(73), longitude(96)) K
Cell methods    : time: mean
Dimensions      : time(12) = [15, ..., 345] days since 1860-1-1
                : latitude(73) = [-90, ..., 90] degrees_north
                : longitude(96) = [0, ..., 356.25] degrees_east
                : height(1) = [2] m

>>> f.shape
(12, 73, 96)
>>> f.subspace[...].shape
(12, 73, 96)
>>> f.subspace[slice(0, 12), :, 10:0:-2].shape
(12, 73, 5)
>>> lon = f.coord('longitude').array
>>> f.subspace[..., lon<180]

>>> f.shape
(12, 73, 96)
>>> f.subspace[0, ...].shape
(1, 73, 96)
>>> f.subspace[3, slice(10, 0, -2), 95].shape
(1, 5, 1)

>>> f.shape
(12, 73, 96)
>>> f.subspace[:, [0, 72], [5, 4, 3]].shape
(12, 2, 3)

>>> f.subspace().shape
(12, 73, 96)
>>> f.subspace(latitude=0).shape
(12, 1, 96)
>>> f.subspace(latitude=cf.wi(-30, 30)).shape
(12, 25, 96)
>>> f.subspace(long=cf.ge(270, 'degrees_east'), lat=cf.set([0, 2.5, 10])).shape
(12, 3, 24)
>>> f.subspace(latitude=cf.lt(0, 'degrees_north'))
(12, 36, 96)
>>> f.subspace(latitude=[cf.lt(0, 'degrees_north'), 90])
(12, 37, 96)
>>> import math
>>> f.subspace(longitude=cf.lt(math.pi, 'radian'), height=2)
(12, 73, 48)
>>> f.subspace(height=cf.gt(3))
IndexError: No indices found for 'height' values gt 3

>>> f.subspace(dim2=3.75).shape
(12, 1, 96)

>>> f.subspace[...] = 273.15

>>> f.subspace[f.indices(longitude=cf.wi(210, 270, 'degrees_east'),
...                      latitude=cf.wi(-5, 5, 'degrees_north'))] = cf.masked

>>> index = f.indices(longitude=0)
>>> f.subspace[index] = f.subspace[index] * 2