cf.Domain.subspace

Domain.subspace(*config, **kwargs)

Create a subspace of the field construct.

Creation of a new domain construct which spans a subspace of the domain of an existing domain construct is achieved by identifying indices based on the metadata constructs (subspacing by metadata). The new domain construct is created with the same properties as the original domain construct.

Subspacing by metadata

Subspacing by metadata selects metadata constructs and specifies conditions on their data. Indices for subspacing are then automatically inferred from where the conditions are met.

Metadata constructs and the conditions on their data are defined by keyword parameters.

• Any domain axes that have not been identified remain unchanged.

• Multiple domain axes may be subspaced simultaneously, and it doesn’t matter which order they are specified in.

• Explicit indices may also be assigned to a domain axis identified by a metadata construct, with either a Python slice object, or a sequence of integers or booleans.

• For a dimension that is cyclic, a subspace defined by a slice or by a Query instance is assumed to “wrap” around the edges of the data.

• Conditions may also be applied to multi-dimensional metadata constructs. The “compress” mode is still the default mode (see the positional arguments), but because the indices may not be acting along orthogonal dimensions, some missing data may still need to be inserted into the field construct’s data.

Halos

If a halo is defined via a positional argument, then each subspaced axis will be extended to include that many extra elements at each “side” of the axis. The number of extra elements will be automatically reduced if including the full amount defined by the halo would extend the subspace beyond the axis limits.

New in version 3.11.0.

See also

indices, cf.Field.subspace

Parameters

config: optional

Configure the subspace by specifying the mode of operation (mode) and any halo to be added to the subspaced axes (halo), with positional arguments in the format mode, or halo, or mode, halo, or with no positional arguments at all.

A mode of operation is given as a str, and a halo as a non-negative int (or any object that can be converted to one):

mode	Description
Not provided	If no positional arguments are provided then assume the 'compress' mode of operation with no halo added to the subspaced axes.
mode	Define the mode of operation with no halo added to the subspaced axes.
mode, halo	Define a mode of operation, as well as a halo to be added to the subspaced axes.
halo	Assume the 'compress' mode of operation and define a halo to be added to the subspaced axes.

Valid modes are:

• 'compress' This is the default.

  Unselected locations are removed to create the subspace. If the result is not hyperrectangular then the minimum amount of unselected locations required to make it so will also be specially selected.

• 'envelope'

  The subspace is the smallest hyperrectangular subspace that contains all of the selected locations.

kwargs: optional

A keyword name is an identity of a metadata construct, and the keyword value provides a condition for inferring indices that apply to the dimension (or dimensions) spanned by the metadata construct’s data. Indices are created that select every location for which the metadata construct’s data satisfies the condition.

Returns

Domain or bool

An independent domain construct containing the subspace of the original domain. If the 'test' positional argument has been set then return True or False depending on whether or not it is possible to create specified subspace.

Examples

>>> d = cf.example_field(0).domain
>>> print(d)
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
>>> print(d.subspace(X=112.5))
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(1) = [112.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]

>>> print(d.indices(X=112.5, Y=cf.wi(-60, 30)))
Dimension coords: latitude(2) = [-45.0, 0.0] degrees_north
                : longitude(1) = [112.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]

>>> print(d.indices(X=[-1, 0], Y=slice(1, -1))
Dimension coords: latitude(3) = [-45.0, 0.0, 45.0] degrees_north
               : longitude(2) = [337.5, 22.5] degrees_east
               : time(1) = [2019-01-01 00:00:00]