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 coordinate object array values (f.subspace(**coordinate_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 two important 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:
When advanced indexing is used on more than one axis, the advanced indices 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:
Subspacing by coordinate values
Subspacing by values of one dimensionsal coordinate objects allows a subspaced field to be defined via coordinate values of its domain.
Coordinate objects and their values are provided as keyword arguments to a call to the returned SubspaceField object. Coordinate objects may be identified by their identities, as returned by their identity methods. See cf.Field.indices for details, since f.subspace(**coordinate_values) is exactly equivalent to f.subspace[f.indices(**coordinate_values)].
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(**coordinate_values) = 0 is not allowed. However, assigning to a subspace defined by coordinate values may be done as follows: f.subspace[f.indices(**coordinate_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 notbe 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.
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.suspace[index] * 2