cf.Field.subspace

Field.subspace

Create a subspace of the field.

The subspace retains all of the metadata of the original field, with those metadata items that contain data arrays also subspaced.

A subspace may be defined in “metadata-space” via conditionss on the data array values of its domain items: dimension coordinate, auxiliary coordinate, cell measure, domain ancillary and field ancillary objects.

Alternatively, a subspace may be defined be in “index-space” via explicit indices for the data array using an extended Python slicing syntax.

See also

indices, where, __getitem__

Size one axes

Size one axes in the data array of the subspaced field are always retained, but may be subsequently removed with the field’s squeeze method:

Defining a subspace in metadata-space

Defining a subspace in metadata-space has the following features

  • Axes to be subspaced may identified by metadata, rather than their position in the data array.
  • The position in the data array of each axis need not be known and the axes to be subspaced may be given in any order.
  • Axes for which no subspacing is required need not be specified.
  • Size one axes of the domain which are not spanned by the data array may be specified.
  • The field may be subspaced according to conditions on multidimensional items.

Subspacing in metadata-space is configured with the following parameters:

Parameters:
positional arguments: optional

Configure the type of subspace that is created. Zero or one of:

argument Description
'compress' The default. Create the smallest possible subspace that contains the selected elements. As many non-selected elements are discarded as possible, meaning that the subspace may not form a contiguous block of the original field. The subspace may still contain non-selected elements, which are set to missing data.
'envelope' Create the smallest subspace that contains the selected elements and forms a contiguous block of the original field. Interior, non-selected elements are set to missing data.
'full' Create a subspace that is the same size as the original field, but with all non-selected elements set to missing data.

In addition the following optional argument specifies how to interpret the keyword parameter names:

argument Description
'exact' Keyword parameters names are not treated as abbreviations of item identities. By default, keyword parameters names are allowed to be abbreviations of item identities.
Example:

To create a subspace that is the same size as the original field, but with missing data at non-selected elements: f.subspace('full', **kwargs), where **kwargs are the positional parameters that define the selected elements.

keyword parameters: optional

Keyword parameter names identify items of the domain (such as a particular coordinate type) and their values set conditions on their data arrays (e.g. the actual coordinate values). These conditions define the subspace that is created.

Keyword names

A keyword name selects a unique item of the field. The name may be any 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(description='lat'). See the exact positional argument.

Example:

The keyword 'T' will select the item returned by f.item(description='T').

Example:

The keyword 'dim2' will select the item that has this internal identifier f.item(description='dim2'). This can be useful in the absence of any more meaningful metadata. A full list of internal identifiers may be found with the field’s items method.

Keyword values

A keyword value specifies a selection on the selected item’s data array which identifies the axis elements to be be included in the subspace.

If the value is a cf.Query object then then the query is applied to the item’s data array to create the subspace.

Example:

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

Example:

To create a subspace for the time 2018-08-27: f.subspace(T=cf.dteq('2018-08-27'))

Example:

To create a subspace for the northern hemisphere, identifying the latitude coordinate by its long name: f.subspace(**{'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 list of integers then these are used as the axis indices, without testing the item’s data array.

Example:

To create a subspace using the first, third, fourth and last indices of the “X” axis: f.subspace(X=[0, 2, 3, -1]).

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 a subspace from every even numbered index along the “Z” axis: f.subspace(Z=slice(0, None, 2)).

If the value is anything other thaqn a cf.Query, list or slice object then, the subspace is defined by where the data array equals that value. I.e. f.subspace(name=x) is equivalent to f.subspace(name=cf.eq(x)).

Example:

To create a subspace where latitude is 52 degrees north: f.subspace(latitude=52). Note that this assumes that the latitude coordinate are in units of degrees north. If this were not known, either of f.subspace(latitude=cf.Data(52, 'degrees_north')) and f.subspace(latitude=cf.eq(52, 'degrees_north')) would guarantee the correct result.
Returns:
out: cf.Field

An independent field containing the subspace of the original field.

Multidimensional items

Subspaces defined by items which span two or more axes are allowed.

Example:
The subspace for the Nino Region 3 created by f.subspace(latitude=cf.wi(-5, 5), longitude=cf.wi(90, 150)) will work equally well if the latitude and longitude coordinates are stored in 1-d or 2-d arrays. In the latter case it is possble that the coordinates are curvilinear, in which case the subspace may contain missing data for the non-selected elements.

Subspacing multiple axes simultaneously

To subspace multiple axes simultaneously, simply provide multiple keyword arguments.

Example:
To create an eastern hemisphere tropical subspace: f.subspace(X=cf.wi(0, 180), latitude=cf.wi(-30, 30)).

Defining a subspace in index-space

Subspacing in index-space uses an extended Python slicing syntax, which is similar to numpy array indexing. Extensions to the numpy indexing functionality are:

  • 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, such as the field’s coordinate objects.
Returns:
out: cf.Field

An independent field containing the subspace of the original field.
Examples: 
>>> f
<CF Field: air_temperature(time(12), latitude(73), longitude(96)) K>
>>> f.subspace[:, [0, 72], [5, 4, 3]]
<CF Field: air_temperature(time(12), latitude(2), longitude(3)) K>
>>> f.subspace[:, f.coord('latitude')<0]
<CF Field: air_temperature(time(12), latitude(36), longitude(96)) K>

Assignment to the data array

A subspace defined in index-space may have its data array values changed by assignment:

>>> f
<CF Field: air_temperature(time(12), latitude(73), longitude(96)) K>
>>> f.subspace[0:6] = f.subspace[6:12]
>>> f.subspace[..., 0:48] = -99

To assign to a subspace defined in metadata-space, the equivalent index-space indices must first be found with the field’s indices method, and then the assignment may be applied in index-space:

>>> index = f.indices(longitude=cf.lt(180))
>>> f.subspace[index] = cf.masked

Note that the indices method accepts the same positional and keyword arguments as subspace.