cf.Field.convert

Field.convert(*identity, full_domain=True, cellsize=False, **filter_kwargs)

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.

Only metadata constructs that can have data may be converted and they can be converted even if they do not actually have any data. Constructs such as cell methods which cannot have data cannot be converted.

The cf.read 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

cf.read, construct

Parameters

identity, filter_kwargs: optional

Select the unique construct returned by f.construct(*identity, **filter_kwargs). See construct for details.

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.

Returns

Field

The new field construct.

Examples

>>> f = cf.example_field(0)
>>> print(f)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), longitude(8)) 1
Cell methods    : area: mean
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]
>>> x = f.convert('X')
>>> print(x)
Field: longitude (ncvar%lon)
----------------------------
Data            : longitude(longitude(8)) degrees_east
Dimension coords: longitude(8) = [22.5, ..., 337.5] degrees_east
>>> print(x.array)
[ 22.5  67.5 112.5 157.5 202.5 247.5 292.5 337.5]
>>> cs = f.convert('X', cellsize=True)
>>> print(cs)
Field: longitude (ncvar%lon)
----------------------------
Data            : longitude(longitude(8)) degrees_east
Dimension coords: longitude(8) = [22.5, ..., 337.5] degrees_east
>>> print(cs.array)
[45. 45. 45. 45. 45. 45. 45. 45.]
>>> print(f.convert('X', full_domain=False))
Field: longitude (ncvar%lon)
----------------------------
Data            : longitude(ncdim%lon(8)) degrees_east