Field.convert(identity, full_domain=True, cellsize=False)[source]

Convert a metadata construct into a new field construct.

The new field construct has the properties and data of the metadata construct, and domain axis constructs corresponding to the data. By default it also contains other metadata constructs (such as dimension coordinate and coordinate reference constructs) that define its domain.

The function allows a field construct to be derived directly from a netCDF variable that corresponds to a metadata construct. In this case, the new field construct will have a domain limited to that which can be inferred from the corresponding netCDF variable - typically only domain axis and dimension coordinate constructs. This will usually result in a different field construct to that created with the convert method.

New in version 3.0.0.

See also


Select the metadata construct by one of:

  • The identity or key of a construct.

A construct identity is specified by a string (e.g. 'latitude', 'long_name=time', 'ncvar%lat', etc.); or a compiled regular expression (e.g. re.compile('^atmosphere')) that selects the relevant constructs whose identities match via

Each construct has a number of identities, and is selected if any of them match any of those provided. A construct’s identities are those returned by its identities method. In the following example, the construct x has six identities:

>>> x.identities()
['time', 'long_name=Time', 'foo=bar', 'standard_name=time', 'ncvar%t', T']

A construct key may optionally have the 'key%' prefix. For example 'dimensioncoordinate2' and 'key%dimensioncoordinate2' are both acceptable keys.

Note that in the output of a print call or dump method, a construct is always described by one of its identities, and so this description may always be used as an identity argument.

Parameter example:


Parameter example:


Parameter example:


Parameter example:


Parameter example:


full_domain: bool, optional

If False then do not create a domain, other than domain axis constructs, for the new field construct. By default as much of the domain as possible is copied to the new field construct.

cellsize: bool, optional

If True then create a field construct from the selected metadata construct’s cell sizes.


The new field construct.