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.

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 or unstructured, 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.