# 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 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`.