cfdm.Field.convert

Field.convert(*identity, full_domain=True, **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 cfdm.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.

Added in version (cfdm): 1.7.0

See also

cfdm.read

Parameters:

identity: str, optional

Convert the metadata construct with the given construct key.

full_domain: bool, optional

If False then only create domain axis constructs for the domain of the new field construct. By default as much of the domain as possible is copied to the new field construct.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria. Also to configure the returned value.

Added in version (cfdm): 1.8.9.0

Returns:

Field

The new field construct.

Examples

>>> f = cfdm.read('file.nc')[0]
>>> print(f)
Field: air_temperature (ncvar%ta)
---------------------------------
Data            : air_temperature(atmosphere_hybrid_height_coordinate(1), grid_latitude(10), grid_longitude(9)) K
Cell methods    : grid_latitude(10): grid_longitude(9): mean where land (interval: 0.1 degrees) time(1): maximum
Field ancils    : air_temperature standard_error(grid_latitude(10), grid_longitude(9)) = [[0.76, ..., 0.32]] K
Dimension coords: atmosphere_hybrid_height_coordinate(1) = [1.5]
                : grid_latitude(10) = [2.2, ..., -1.76] degrees
                : grid_longitude(9) = [-4.7, ..., -1.18] degrees
                : time(1) = [2019-01-01 00:00:00]
Auxiliary coords: latitude(grid_latitude(10), grid_longitude(9)) = [[53.941, ..., 50.225]] degrees_N
                : longitude(grid_longitude(9), grid_latitude(10)) = [[2.004, ..., 8.156]] degrees_E
                : long_name:Grid latitude name(grid_latitude(10)) = [--, ..., kappa]
Cell measures   : measure%area(grid_longitude(9), grid_latitude(10)) = [[2391.9657, ..., 2392.6009]] km2
Coord references: atmosphere_hybrid_height_coordinate
                : rotated_latitude_longitude
Domain ancils   : ncvar%a(atmosphere_hybrid_height_coordinate(1)) = [10.0] m
                : ncvar%b(atmosphere_hybrid_height_coordinate(1)) = [20.0]
                : surface_altitude(grid_latitude(10), grid_longitude(9)) = [[0.0, ..., 270.0]] m
>>> x = f.convert('domainancillary2')
>>> print(x)
Field: surface_altitude (ncvar%surface_altitude)
------------------------------------------------
Data            : surface_altitude(grid_latitude(10), grid_longitude(9)) m
Dimension coords: grid_latitude(10) = [2.2, ..., -1.76] degrees
                : grid_longitude(9) = [-4.7, ..., -1.18] degrees
Auxiliary coords: latitude(grid_latitude(10), grid_longitude(9)) = [[53.941, ..., 50.225]] degrees_N
                : longitude(grid_longitude(9), grid_latitude(10)) = [[2.004, ..., 8.156]] degrees_E
                : long_name:Grid latitude name(grid_latitude(10)) = [--, ..., kappa]
Cell measures   : measure%area(grid_longitude(9), grid_latitude(10)) = [[2391.9657, ..., 2392.6009]] km2
Coord references: rotated_latitude_longitude
>>> y = f.convert('domainancillary2', full_domain=False)
>>> print(y)
Field: surface_altitude (ncvar%surface_altitude)
------------------------------------------------
Data            : surface_altitude(grid_latitude(10), grid_longitude(9)) m