cfdm.domain¶

Classes

Domain(*args, **kwargs)

A domain construct of the CF data model.

class cfdm.domain.Domain(*args, **kwargs)[source]¶

Bases: FieldDomain, NetCDFVariable, NetCDFGeometry, NetCDFGlobalAttributes, NetCDFGroupAttributes, NetCDFComponents, NetCDFUnreferenced, NetCDFMeshVariable, Properties, Files, Domain

A domain construct of the CF data model.

The domain represents a set of discrete “locations” in what generally would be a multi-dimensional space, either in the real world or in a model’s simulated world. The data array elements of a field construct correspond to individual location of a domain.

The domain construct is defined collectively by the following constructs of the CF data model: domain axis, dimension coordinate, auxiliary coordinate, cell measure, coordinate reference, and domain ancillary constructs; as well as properties to describe the domain.

NetCDF interface

The netCDF variable name may be accessed with the nc_set_variable, nc_get_variable, nc_del_variable, and nc_has_variable methods.

The netCDF variable group structure may be accessed with the nc_set_variable, nc_get_variable, nc_variable_groups, nc_clear_variable_groups, and nc_set_variable_groups methods.

The selection of properties to be written as netCDF global attributes may be accessed with the nc_global_attributes, nc_clear_global_attributes, and nc_set_global_attribute methods.

The netCDF group attributes may be accessed with the nc_group_attributes, nc_clear_group_attributes, nc_set_group_attribute, and nc_set_group_attributes methods.

The netCDF geometry variable name and group structure may be accessed with the nc_set_geometry_variable, nc_get_geometry_variable, nc_geometry_variable_groups, nc_clear_variable_groups, and nc_set_geometry_variable_groups methods.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF variable, dimension and sample dimension names and group structures for such components may be set or removed consistently across all such components with the nc_del_component_variable, nc_set_component_variable, nc_set_component_variable_groups, nc_clear_component_variable_groups, nc_del_component_dimension, nc_set_component_dimension, nc_set_component_dimension_groups, nc_clear_component_dimension_groups, nc_del_component_sample_dimension, nc_set_component_sample_dimension, nc_set_component_sample_dimension_groups, and nc_clear_component_sample_dimension_groups methods.

Added in version (cfdm): 1.7.0

Initialisation

Parameters:

properties: dict, optional

Set descriptive properties. The dictionary keys are property names, with corresponding values.

Properties may also be set after initialisation with the set_properties and set_property methods.

Parameter example:

properties={'long_name': 'Domain for model'}

source: optional

Convert source, which can be any type of object, to a Domain instance.

All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the Domain API. Any parameters that can not be retrieved from source in this way are assumed to have their default value.

Note that if x is also a Domain instance then cfdm.Domain(source=x) is equivalent to x.copy().

A new domain may also be instantiated with the fromconstructs class method.

copy: bool, optional

If True (the default) then deep copy the input parameters prior to initialisation. By default the parameters are not deep copied.

classmethod fromconstructs(constructs, copy=False)[source]¶

Return a new domain containing the given metadata constructs.

The new domain acts as a view to the given constructs, i.e. changes to the domain, such as the addition or removal of a construct, will also affect the input Constructs instance.

Added in version (cfdm): 1.7.0

Parameters:

constructs: Constructs: The constructs from which to create the new domain. Cell method and field ancillary constructs are ignored.
copy: bool, optional: If True then deep copy the metadata constructs prior to initialisation. By default the metadata constructs are not copied. Note that even when copy is True, the input Constructs container is not copied.

Returns:

Domain: The domain created from a view of the constructs.

Examples

>>> f = cfdm.example_field(0)
>>> d = cfdm.Domain.fromconstructs(f.constructs)
>>> d
<Domain: {1, 5, 8}>
>>> d = cfdm.Domain.fromconstructs(f.constructs.copy())

apply_masking(inplace=False)[source]¶

Apply masking as defined by the CF conventions.

Masking is applied to all metadata constructs with data.

Masking is applied according to any of the following criteria that are applicable:

where data elements are equal to the value of the missing_value property;
where data elements are equal to the value of the _FillValue property;
where data elements are strictly less than the value of the valid_min property;
where data elements are strictly greater than the value of the valid_max property;
where data elements are within the inclusive range specified by the two values of valid_range property.

If any of the above properties have not been set the no masking is applied for that method.

Elements that are already masked remain so.

Note

If using the apply_masking method on a construct that has been read from a dataset with the mask=False parameter to the read function, then the mask defined in the dataset can only be recreated if the missing_value, _FillValue, valid_min, valid_max, and valid_range properties have not been updated.

Added in version (cfdm): 1.8.9.0

See also

cfdm.Data.apply_masking, read, write

Parameters:

inplace: bool, optional: If True then do the operation in-place and return None.

Returns:

Domain or None: A new domain construct with masked values, or None if the operation was in-place.

Examples

>>> d = cfdm.example_domain(0)
>>> x = d.construct('longitude')
>>> x.data[[0, -1]] = cfdm.masked
>>> print(x.data.array)
[-- 67.5 112.5 157.5 202.5 247.5 292.5 --]
>>> cfdm.write(d, 'masked.nc')
>>> no_mask = cfdm.read('masked.nc', domain=True, mask=False)[0]
>>> no_mask_x = no_mask.construct('longitude')
>>> print(no_mask_x.data.array)
[9.96920997e+36 6.75000000e+01 1.12500000e+02 1.57500000e+02
 2.02500000e+02 2.47500000e+02 2.92500000e+02 9.96920997e+36]
>>> masked = no_mask.apply_masking()
>>> masked_x = masked.construct('longitude')
>>> print(masked_x.data.array)
[-- 67.5 112.5 157.5 202.5 247.5

auxiliary_coordinate(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Select an auxiliary coordinate construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.10.0.0

See also

construct, auxiliary_coordinates

Parameters:

identity: optional

Select auxiliary coordinate constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all auxiliary coordinate constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(1)
>>> f.auxiliary_coordinate('latitude')
<AuxiliaryCoordinate: latitude(10, 9) degrees_N>
>>> f.auxiliary_coordinate('latitude', key=True)
'auxiliarycoordinate0'
>>> f.auxiliary_coordinate('latitude', item=True)
('auxiliarycoordinate0', <AuxiliaryCoordinate: latitude(10, 9) degrees_N>)

auxiliary_coordinates(*identities, **filter_kwargs)[source]¶

Return auxiliary coordinate constructs.

Note that f.auxiliary_coordinates(*identities, **filter_kwargs) is equivalent to f.constructs.filter(filter_by_type=["auxiliary_coordinate"], filter_by_identity=identities, **filter_kwargs).

Added in version (cfdm): 1.7.0

See also

constructs, auxiliary_coordinate

Parameters:

identities: optional

Select auxiliary coordinate constructs that have an identity, defined by their identities methods, that matches any of the given values.

If no identities are provided then all auxiliary coordinate constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

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:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

>>> f.auxiliary_coordinates()
Constructs:
{}

>>> f.auxiliary_coordinates()
Constructs:
{'auxiliarycoordinate0': <AuxiliaryCoordinate: latitude(10, 9) degrees_N>,
 'auxiliarycoordinate1': <AuxiliaryCoordinate: longitude(9, 10) degrees_E>,
 'auxiliarycoordinate2': <AuxiliaryCoordinate: long_name:Grid latitude name(10) >}

cell_connectivities(*identities, **filter_kwargs)[source]¶

Select cell connectivity constructs.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.11.0.0

See also

construct, cell_connectivity

Note that f.cell_connectivities(*identities, **filter_kwargs) is equivalent to f.constructs.filter(filter_by_type=["cell_connectivity"], filter_by_identity=identities, **filter_kwargs).

Parameters:

identities: optional

Select cell connectivity constructs that have an identity, defined by their identities methods, that matches any of the given values.

If no identities are provided then all cell connectivity constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

filter_kwargs: optional

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

Returns:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

>>> f = cfdm.example_domain(8)
>>> print(f.cell_connectivities())
Constructs:
{'cellconnectivity0': <CellConnectivity: connectivity:edge(3) >}

cell_connectivity(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Select a cell connectivity construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.11.0.0

See also

construct, cell_connectivities

Parameters:

identity: optional

Select cell connectivity constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all cell connectivity constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct. If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(8)
>>> f.cell_connectivity()
<CellConnectivity: connectivity:edge(3) >
>>> f.cell_connectivity('connectivity:edge', key=True)
'cellconnectivity0'
>>> f.cell_connectivity('connectivity:edge', item=True)
('cellconnectivity0', <CellConnectivity: connectivity:edge(3) >)

cell_measure(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Select a cell measure construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.10.0.0

See also

construct, cell_measures

Parameters:

identity: optional

Select cell measure constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all cell measure constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(1)
>>> f.cell_measure()
<CellMeasure: measure:area(9, 10) km2>
>>> f.cell_measure('measure:area', key=True)
'cellmeasure0'
>>> f.cell_measure('measure:area', item=True)
('cellmeasure0', <CellMeasure: measure:area(9, 10) km2>)

cell_measures(*identities, **filter_kwargs)[source]¶

Return cell measure constructs.

f.cell_measures(*identities, **filter_kwargs) is equivalent to f.constructs.filter(filter_by_type=["cell_measure"], filter_by_identity=identities, **filter_kwargs).

Added in version (cfdm): 1.7.0

See also

constructs, cell_measure

Parameters:

identities: optional

Select cell measure constructs that have an identity, defined by their identities methods, that matches any of the given values.

If no identities are provided then all cell measure constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

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:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

>>> f = cfdm.example_domain(1)
>>> print(f.cell_measures())
Constructs:
{'cellmeasure0': <CellMeasure: measure%area(9, 10) km2>}

clear_properties()[source]¶

Remove all properties.

Added in version (cfdm): 1.7.0

Returns:

dict: The properties that have been removed.

Examples

>>> f = cfdm.Domain()
>>> f.properties()
{}
>>> f.set_properties({'standard_name': 'air_pressure',
...                   'long_name': 'Air Pressure'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure'}
>>> f.set_properties({'standard_name': 'air_pressure', 'foo': 'bar'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.clear_properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.properties()
{}

climatological_time_axes()[source]¶

Return all axes which are climatological time axes.

This is ascertained by inspecting the values returned by each coordinate construct’s is_climatology method.

Added in version (cfdm): 1.8.9.0

Returns:

set: The keys of the domain axis constructs that are climatological time axes.

Examples

>>> d = cfdm.example_domain(0)
>>> d.climatological_time_axes()
set()

construct(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Return a metadata construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.7.0

Parameters:

identity: optional

Select constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

Added in version (cfdm): 1.10.0.0

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

Added in version (cfdm): 1.10.0.0

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Added in version (cfdm): 1.8.9.0

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(0)

Select the construct that has the “standard_name” property of ‘latitude’:

>>> print(f.constructs.filter_by_property(standard_name=None))
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: long_name=time(1) days since 2018-12-01 >}
>>> f.construct('latitude')
<DimensionCoordinate: latitude(5) degrees_north>

Attempt to select a unique construct whose “standard_name” start with the letter ‘l’:

>>> import re
>>> f.construct(re.compile('^l'))
Traceback
    ...
ValueError: Domain.construct() can't return 2 constructs
>>> f.construct(re.compile('^l'), default='no unique construct')
'no unique construct'

construct_item(*identity, default=ValueError(), **filter_kwargs)[source]¶

Return a metadata construct and its identifier.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

f.construct_item(*args, **kwargs) is an alias for f.construct(*args, item=True, **kwargs). See construct for details.

Added in version (cfdm): 1.8.9.0

See also

construct, construct_key

Parameters:

identity: optional

Select constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Added in version (cfdm): 1.8.9.0

Returns:

tuple: The selected construct and its construct identifier.

Examples

>>> f = cfdm.example_domain(0)

Select the construct that has the “standard_name” property of ‘latitude’:

>>> print(f.constructs.filter_by_property(standard_name=None))
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: long_name=time(1) days since 2018-12-01 >}
>>> f.construct_item('latitude')
('dimensioncoordinate1', <DimensionCoordinate: latitude(5) degrees_north>)

Attempt to select a unique construct whose “standard_name” start with the letter ‘l’:

>>> import re
>>> f.construct(re.compile('^l'))
Traceback
    ...
ValueError: Domain.construct() can't return 2 constructs
>>> f.construct(re.compile('^l'), default='no unique construct')
'no unique construct'

construct_key(*identity, default=ValueError(), **filter_kwargs)[source]¶

Return the identifier of a metadata construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

f.construct_key(*args, **kwargs) is an alias for f.construct(*args, itekey=True, **kwargs). See construct for details.

Added in version (cfdm): 1.7.0

See also

construct, construct_item

Parameters:

identity: optional

Select constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Added in version (cfdm): 1.8.9.0

Returns:

str: The identifier of the selected construct.

Examples

>>> f = cfdm.example_domain(0)

Select the construct that has the “standard_name” property of ‘latitude’:

>>> print(f.constructs.filter_by_property(standard_name=None))
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: long_name=time(1) days since 2018-12-01 >}
>>> f.construct_key('latitude')
'dimensioncoordinate1'

Attempt to select a unique construct whose “standard_name” start with the letter ‘l’:

>>> import re
>>> f.construct(re.compile('^l'))
Traceback
    ...
ValueError: Domain.construct() can't return 2 constructs
>>> f.construct(re.compile('^l'), default='no unique construct')
'no unique construct'

coordinate(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Select a dimension or auxiliary coordinate construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.10.0.0

See also

construct, coordinates

Parameters:

identity: optional

Select dimension or auxiliary coordinate constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all dimension or auxiliary coordinate constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(1)
>>> f.coordinate('latitude')
<AuxiliaryCoordinate: latitude(10, 9) degrees_N>
>>> f.coordinate('grid_latitude')
<DimensionCoordinate: grid_latitude(10) degrees>
>>> f.coordinate('grid_latitude', key=True)
'dimensioncoordinate1'
>>> f.coordinate('grid_latitude', item=True)
('dimensioncoordinate1', <DimensionCoordinate: grid_latitude(10) degrees>)

coordinate_reference(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Return a coordinate reference construct, or its key.

Added in version (cfdm): 1.10.0.0

See also

construct, coordinate_references

Parameters:

identity: optional

Select coordinate reference constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no identities are provided then all coordinate reference constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(1)
>>> f.coordinate_reference('grid_mapping_name:rotated_latitude_longitude')
<CoordinateReference: grid_mapping_name:rotated_latitude_longitude>
>>> f.coordinate_reference('grid_mapping_name:rotated_latitude_longitude', key=True)
'coordinatereference1'
>>> f.coordinate_reference('grid_mapping_name:rotated_latitude_longitude', item=True)
('coordinatereference1',
 <CoordinateReference: grid_mapping_name:rotated_latitude_longitude>)

coordinate_references(*identities, **filter_kwargs)[source]¶

Return coordinate reference constructs.

Added in version (cfdm): 1.7.0

See also

constructs, coordinate_reference

Parameters:

identities: optional

Select coordinate reference constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no identities are provided then all coordinate reference constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

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:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

>>> f.coordinate_references()
Constructs:
{}

>>> f.coordinate_references()
Constructs:
{'coordinatereference0': <CoordinateReference: atmosphere_hybrid_height_coordinate>,
 'coordinatereference1': <CoordinateReference: rotated_latitude_longitude>}

coordinates(*identities, **filter_kwargs)[source]¶

Return dimension and auxiliary coordinate constructs.

Note that f.coordinates(*identities, **filter_kwargs) is equivalent to f.constructs.filter(filter_by_type=["dimension_coordinate", "auxiliary_coordinate"], filter_by_identity=identities, **filter_kwargs).

Added in version (cfdm): 1.7.0

Parameters:

identities: optional

Select dimension and auxiliary coordinate constructs that have an identity, defined by their identities methods, that matches any of the given values.

If no identities are provided then all dimension and auxiliary coordinate constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

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:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

>>> f = cfdm.example_field(7)
>>> print(f)
Field: eastward_wind (ncvar%ua)
-------------------------------
Data            : eastward_wind(time(3), air_pressure(1), grid_latitude(4), grid_longitude(5)) m s-1
Cell methods    : time(3): mean
Dimension coords: time(3) = [1979-05-01 12:00:00, 1979-05-02 12:00:00, 1979-05-03 12:00:00] gregorian
                : air_pressure(1) = [850.0] hPa
                : grid_latitude(4) = [0.44, ..., -0.88] degrees
                : grid_longitude(5) = [-1.18, ..., 0.58] degrees
Auxiliary coords: latitude(grid_latitude(4), grid_longitude(5)) = [[52.4243, ..., 51.1163]] degrees_north
                : longitude(grid_latitude(4), grid_longitude(5)) = [[8.0648, ..., 10.9238]] degrees_east
Coord references: grid_mapping_name:rotated_latitude_longitude
>>> f.coordinates()
<Constructs: auxiliary_coordinate(2), dimension_coordinate(4)>
>>> print(f.coordinates())
Constructs:
{'auxiliarycoordinate0': <AuxiliaryCoordinate: latitude(4, 5) degrees_north>,
 'auxiliarycoordinate1': <AuxiliaryCoordinate: longitude(4, 5) degrees_east>,
 'dimensioncoordinate0': <DimensionCoordinate: time(3) days since 1979-1-1 gregorian>,
 'dimensioncoordinate1': <DimensionCoordinate: air_pressure(1) hPa>,
 'dimensioncoordinate2': <DimensionCoordinate: grid_latitude(4) degrees>,
 'dimensioncoordinate3': <DimensionCoordinate: grid_longitude(5) degrees>}

copy(data=True)[source]¶

Return a deep copy.

d.copy() is equivalent to copy.deepcopy(d).

Added in version (cfdm): 1.7.0

See also

fromconstructs

Parameters:

data: bool, optional: If True (the default) then copy data contained in the metadata construct(s), else the data is not copied.

Returns:

Domain: The deep copy.

Examples

>>> d = cfdm.Domain()
>>> e = d.copy()

creation_commands(representative_data=False, namespace=None, indent=0, string=True, name='domain', data_name='data', header=True, _domain=True)[source]¶

Return the commands that would create the domain construct.

Construct keys

The key parameter of the output set_construct commands is utilised in order minimise the number of commands needed to implement cross-referencing between constructs (e.g. between a coordinate reference construct and coordinate constructs). This is usually not necessary when building domain constructs, as by default the set_construct method returns a unique construct key for the construct being set.

Added in version (cfdm): 1.9.0.0

Parameters:

representative_data: bool, optional

Return one-line representations of Data instances, which are not executable code but prevent the data being converted in its entirety to a string representation.

namespace: str, optional

The name space containing classes of the cfdm package. This is prefixed to the class name in commands that instantiate instances of cfdm objects. By default, or if None, the name space is assumed to be consistent with cfdm being imported as import cfdm.

Parameter example:: If cfdm was imported as import cfdm as xyz then set namespace='xyz'
Parameter example:: If cfdm was imported as from cfdm import * then set namespace=''

indent: int, optional

Indent each line by this many spaces. By default no indentation is applied. Ignored if string is False.

string: bool, optional

If False then return each command as an element of a list. By default the commands are concatenated into a string, with a new line inserted between each command.

header: bool, optional

If True (the default) output a comment describing the components. If False no such comment is returned.

Returns:

str or list: The commands in a string, with a new line inserted between each command. If string is False then the separate commands are returned as each element of a list.

Examples

>>> f = cfdm.example_domain(0)
>>> print(d.creation_commands())
#
# domain:
domain = cfdm.Domain()
#
# domain_axis: ncdim%lat
c = cfdm.DomainAxis()
c.set_size(5)
c.nc_set_dimension('lat')
domain.set_construct(c, key='domainaxis0', copy=False)
#
# domain_axis: ncdim%lon
c = cfdm.DomainAxis()
c.set_size(8)
c.nc_set_dimension('lon')
domain.set_construct(c, key='domainaxis1', copy=False)
#
# domain_axis:
c = cfdm.DomainAxis()
c.set_size(1)
domain.set_construct(c, key='domainaxis2', copy=False)
#
# dimension_coordinate: latitude
c = cfdm.DimensionCoordinate()
c.set_properties({'units': 'degrees_north', 'standard_name': 'latitude'})
c.nc_set_variable('lat')
data = cfdm.Data([-75.0, -45.0, 0.0, 45.0, 75.0], units='degrees_north', dtype='f8')
c.set_data(data)
b = cfdm.Bounds()
b.nc_set_variable('lat_bnds')
data = cfdm.Data([[-90.0, -60.0], [-60.0, -30.0], [-30.0, 30.0], [30.0, 60.0], [60.0, 90.0]], units='degrees_north', dtype='f8')
b.set_data(data)
c.set_bounds(b)
domain.set_construct(c, axes=('domainaxis0',), key='dimensioncoordinate0', copy=False)
#
# dimension_coordinate: longitude
c = cfdm.DimensionCoordinate()
c.set_properties({'units': 'degrees_east', 'standard_name': 'longitude'})
c.nc_set_variable('lon')
data = cfdm.Data([22.5, 67.5, 112.5, 157.5, 202.5, 247.5, 292.5, 337.5], units='degrees_east', dtype='f8')
c.set_data(data)
b = cfdm.Bounds()
b.nc_set_variable('lon_bnds')
data = cfdm.Data([[0.0, 45.0], [45.0, 90.0], [90.0, 135.0], [135.0, 180.0], [180.0, 225.0], [225.0, 270.0], [270.0, 315.0], [315.0, 360.0]], units='degrees_east', dtype='f8')
b.set_data(data)
c.set_bounds(b)
domain.set_construct(c, axes=('domainaxis1',), key='dimensioncoordinate1', copy=False)
#
# dimension_coordinate: time
c = cfdm.DimensionCoordinate()
c.set_properties({'units': 'days since 2018-12-01', 'standard_name': 'time'})
c.nc_set_variable('time')
data = cfdm.Data([31.0], units='days since 2018-12-01', dtype='f8')
c.set_data(data)
domain.set_construct(c, axes=('domainaxis2',), key='dimensioncoordinate2', copy=False)
>>> print(d.creation_commands(representative_data=True, namespace='',
...                           indent=4, header=False))
    domain = Domain()
    c = DomainAxis()
    c.set_size(5)
    c.nc_set_dimension('lat')
    domain.set_construct(c, key='domainaxis0', copy=False)
    c = DomainAxis()
    c.set_size(8)
    c.nc_set_dimension('lon')
    domain.set_construct(c, key='domainaxis1', copy=False)
    c = DomainAxis()
    c.set_size(1)
    domain.set_construct(c, key='domainaxis2', copy=False)
    c = DimensionCoordinate()
    c.set_properties({'units': 'degrees_north', 'standard_name': 'latitude'})
    c.nc_set_variable('lat')
    data = <Data(5): [-75.0, ..., 75.0] degrees_north>  # Representative data
    c.set_data(data)
    b = Bounds()
    b.nc_set_variable('lat_bnds')
    data = <Data(5, 2): [[-90.0, ..., 90.0]] degrees_north>  # Representative data
    b.set_data(data)
    c.set_bounds(b)
    domain.set_construct(c, axes=('domainaxis0',), key='dimensioncoordinate0', copy=False)
    c = DimensionCoordinate()
    c.set_properties({'units': 'degrees_east', 'standard_name': 'longitude'})
    c.nc_set_variable('lon')
    data = <Data(8): [22.5, ..., 337.5] degrees_east>  # Representative data
    c.set_data(data)
    b = Bounds()
    b.nc_set_variable('lon_bnds')
    data = <Data(8, 2): [[0.0, ..., 360.0]] degrees_east>  # Representative data
    b.set_data(data)
    c.set_bounds(b)
    domain.set_construct(c, axes=('domainaxis1',), key='dimensioncoordinate1', copy=False)
    c = DimensionCoordinate()
    c.set_properties({'units': 'days since 2018-12-01', 'standard_name': 'time'})
    c.nc_set_variable('time')
    data = <Data(1): [2019-01-01 00:00:00]>  # Representative data
    c.set_data(data)
    domain.set_construct(c, axes=('domainaxis2',), key='dimensioncoordinate2', copy=False)

dataset_compliance(display=False)[source]¶

Return the dataset compliance report.

A report of problems encountered whilst reading the construct from a dataset.

If the dataset is partially CF-compliant to the extent that it is not possible to unambiguously map an element of the netCDF dataset to an element of the CF data model, then a construct is still returned by the read function, but may be incomplete.

Such “structural” non-compliance would occur, for example, if the coordinates attribute of a CF-netCDF data variable refers to another variable that does not exist, or refers to a variable that spans a netCDF dimension that does not apply to the data variable.

Other types of non-compliance are not checked, such whether or not controlled vocabularies have been adhered to.

When a dictionary is returned, the compliance report may be updated by changing the dictionary in-place.

Added in version (cfdm): 1.7.0

See also

cfdm.read, _set_dataset_compliance

Parameters:

display: bool, optional: If True print the compliance report. By default the report is returned as a dictionary.

Returns:

None or dict: The report. If display is True then the report is printed and None is returned. Otherwise the report is returned as a dictionary.

Examples

If no problems were encountered, an empty dictionary is returned:

>>> f = cfdm.example_field(1)
>>> cfdm.write(f, 'example.nc')
>>> g = cfdm.read('example.nc')[0]
>>> g.dataset_compliance()
{}

del_construct(*identity, default=ValueError(), **filter_kwargs)[source]¶

Remove a metadata construct.

If a domain axis construct is selected for removal then it can’t be spanned by any data arrays of the field nor metadata constructs, nor be referenced by any cell method constructs. However, a domain ancillary construct may be removed even if it is referenced by coordinate reference construct.

Added in version (cfdm): 1.7.0

Parameters:

identity:

Select the unique construct that has the identity, defined by its identities method, that matches the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

default: optional

Return the value of the default parameter if the data axes have not been set.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Added in version (cfdm): 1.8.9.0

Returns:

The removed metadata construct.

Examples

>>> f = cfdm.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]
>>> f.del_construct('time')
<DimensionCoordinate: time(1) days since 2018-12-01 >
>>> f.del_construct('time')
Traceback (most recent call last):
    ...
ValueError: Can't find unique construct to remove
>>> f.del_construct('time', default='No time')
'No time'
>>> f.del_construct('dimensioncoordinate1')
<DimensionCoordinate: longitude(8) degrees_east>
>>> print(f)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), ncdim%lon(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north

del_data_axes(key, default=ValueError())[source]¶

Removes the keys of the axes spanned by the construct data.

Specifically, removes the keys of the domain axis constructs spanned by the data of a metadata construct.

Added in version (cfdm): 1.7.0

Parameters:

key: str

Specify a metadata construct, instead of the field construct.

Parameter example:: key='auxiliarycoordinate0'

default: optional

Return the value of the default parameter if the data axes have not been set.

If set to an Exception instance then it will be raised instead.

Returns:

tuple: The removed keys of the domain axis constructs spanned by the data.

Examples

>>> f.del_data_axes(key='dimensioncoordinate2')
('domainaxis1',)

>>> f.has_data_axes(key='auxiliarycoordinate0')
False
>>> f.has_data_axes(key='auxiliarycoordinate0', default='no axes')
'no axes'

del_mesh_id(default=ValueError())[source]¶

Remove the UGRID mesh topology identifier.

Different field constructs with the same mesh topology identifier may be assumed to have domains with a shared UGRID mesh topology.

Added in version (cfdm): 1.11.0.0

Parameters:

default: optional

Return the value of the default parameter if the mesh topology identifier has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The removed mesh topology identifier.

Examples

>>> c = cfdm.Domain()
>>> c.set_mesh_id('df71b85a99894af094411e7cd21c5d68')
>>> c.has_mesh_id()
True
>>> c.get_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.del_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.has_mesh_id()
False
>>> print(c.del_mesh_id(None))
None
>>> print(c.get_mesh_id(None))
None

del_properties(properties)[source]¶

Remove properties.

Added in version (cfdm): 1.10.0.3

Parameters:

properties: (sequence of) str

The names of the properties to be removed. If the Domain does not have a particular property then that property is ignored. No properties are removed if properties is an empty sequence.

Parameter example:: 'long_name'
Parameter example:: ['long_name', 'comment']

Returns:

dict: The removed property values, keyed by property name.

Examples

>>> f = cfdm.Domain()
>>> f.set_properties({'project': 'CMIP7', 'comment': 'model'})
>>> removed_properties = f.del_properties('project')
>>> removed_properties
{'project': 'CMIP7'}
>>> f.properties()
{'comment': 'model'}
>>> f.set_properties(removed_properties)
>>> f.properties()
{'comment': 'model', 'project': 'CMIP7'}
>>> f.del_properties('foo')
{}

del_property(prop, default=ValueError())[source]¶

Remove a property.

Added in version (cfdm): 1.7.0

Parameters:

prop: str

The name of the property to be removed.

Parameter example:: prop='long_name'

default: optional

Return the value of the default parameter if the property has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The removed property value.

Examples

>>> f = cfdm.Domain()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

dimension_coordinate(*identity, key=False, default=ValueError(), item=False, **filter_kwargs)[source]¶

Select a dimension coordinate construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.10.0.0

See also

construct, dimension_coordinates

Parameters:

identity: optional

Select dimension coordinate constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all dimension coordinate constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(1)
>>> f.dimension_coordinate('grid_latitude')
<DimensionCoordinate: grid_latitude(10) degrees>
>>> f.coordinate('grid_latitude', key=True)
'dimensioncoordinate1'
>>> f.coordinate('grid_latitude', item=True)
('dimensioncoordinate1', <DimensionCoordinate: grid_latitude(10) degrees>)

dimension_coordinates(*identities, **filter_kwargs)[source]¶

Return dimension coordinate constructs.

Note that f.dimension_coordinates(*identities, **filter_kwargs) is equivalent to f.constructs.filter(filter_by_type=["dimension_coordinate"], filter_by_identity=identities, **filter_kwargs).

Added in version (cfdm): 1.7.0

See also

constructs, dimension_coordinate

Parameters:

identities: optional

Select dimension coordinate constructs that have an identity, defined by their identities methods, that matches any of the given values.

If no identities are provided then all dimension coordinate constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

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:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

>>> f.dimension_coordinates()
Constructs:
{}

>>> f.dimension_coordinates()
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: atmosphere_hybrid_height_coordinate(1) >,
 'dimensioncoordinate1': <DimensionCoordinate: grid_latitude(10) degrees>,
 'dimensioncoordinate2': <DimensionCoordinate: grid_longitude(9) degrees>,
 'dimensioncoordinate3': <DimensionCoordinate: time(1) days since 2018-12-01 >}

domain_ancillaries(*identities, **filter_kwargs)[source]¶

Return domain ancillary constructs.

Note that f.domain_ancillaries(*identities, **filter_kwargs) is equivalent to f.constructs.filter(filter_by_type=["domain_ancillary"], filter_by_identity=identities, **filter_kwargs).

Added in version (cfdm): 1.7.0

See also

constructs, domain_ancillary

Parameters:

identities: optional

Select domain ancillary constructs that have an identity, defined by their identities methods, that matches any of the given values.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

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:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

>>> f.domain_ancillaries()
Constructs:
{}

>>> f.domain_ancillaries()
Constructs:
{'domainancillary0': <DomainAncillary: ncvar%a(1) m>,
 'domainancillary1': <DomainAncillary: ncvar%b(1) >,
 'domainancillary2': <DomainAncillary: surface_altitude(10, 9) m>}

domain_ancillary(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Select a domain ancillary construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.10.0.0

See also

construct, domain_ancillaries

Parameters:

identity: optional

Select domain ancillary constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all domain ancillary constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(1)
>>> f.domain_ancillary('surface_altitude')
<DomainAncillary: surface_altitude(10, 9) m>
>>> f.domain_ancillary('surface_altitude', key=True)
'domainancillary2'
>>> f.domain_ancillary('surface_altitude', item=True)
('domainancillary2', <DomainAncillary: surface_altitude(10, 9) m>)

domain_axes(*identities, **filter_kwargs)[source]¶

Return domain axis constructs.

Added in version (cfdm): 1.7.0

See also

constructs, domain_axis

Parameters:

identities: tuple, optional

Select domain axis constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

Additionally, if for a given value, f.coordinates(value, filter_by_naxes=(1,)) returns 1-d coordinate constructs that all span the same domain axis construct then that domain axis construct is selected. See coordinates for details.

Additionally, if there is an associated Field data array and a value matches the integer position of an array dimension, then the corresponding domain axis construct is selected.

If no values are provided then all domain axis constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

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:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples

domain_axis(*identity, key=False, default=ValueError(), item=False, **filter_kwargs)[source]¶

Select a domain axis construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.10.0.0

See also

construct, domain_axes

Parameters:

identities: tuple, optional

Select domain axis constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

Additionally, if for a given value, f.coordinates(value, filter_by_naxes=(1,)) returns 1-d coordinate constructs that all span the same domain axis construct then that domain axis construct is selected. See coordinates for details.

Additionally, if there is a Field data array and a value matches the integer position of an array dimension, then the corresponding domain axis construct is selected.

If no values are provided then all domain axis constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(1)
>>> f.domain_axis('domainaxis0')
<DomainAxis: size(1)>
>>> f.domain_axis('domainaxis0', key=True)
'domainaxis0'
>>> f.domain_axis('domainaxis0', item=True)
('domainaxis0', <DomainAxis: size(1)>)

domain_axis_key(*identity, default=ValueError(), **filter_kwargs)[source]¶

Returns the domain axis key spanned by 1-d coordinates.

Specifically, returns the key of the domain axis construct that is spanned by 1-d coordinate constructs.

Parameters:

identity: optional

Select the 1-d dimension coordinate constructs that have an identity, defined by their identities methods, that matches any of the given values.

If no values are provided then all 1-d dimension coordinate constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Added in version (cfdm): 1.8.9.0

Returns:

str: The key of the domain axis construct that is spanned by the data of the selected 1-d coordinate constructs.

Examples

>>> print(f.constructs())
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: time(1) days since 1964-01-21 00:00:00 >,
 'dimensioncoordinate1': <DimensionCoordinate: pressure(23) mbar>,
 'dimensioncoordinate2': <DimensionCoordinate: latitude(160) degrees_north>,
 'dimensioncoordinate3': <DimensionCoordinate: longitude(320) degrees_east>,
 'domainaxis0': <DomainAxis: size(1)>,
 'domainaxis1': <DomainAxis: size(23)>,
 'domainaxis2': <DomainAxis: size(160)>,
 'domainaxis3': <DomainAxis: size(320)>}
>>> f.domain.domain_axis_key('time')
'domainaxis0'
>>> f.domain.domain_axis_key('longitude')
'domainaxis3'

domain_topologies(*identities, **filter_kwargs)[source]¶

Return domain topology constructs.

Note that f.domain_topologies(*identities, **filter_kwargs) is equivalent to

f.constructs.filter(filter_by_type=["domain_topology"], filter_by_identity=identities, **filter_kwargs).

Added in version (cfdm): 1.11.0.0

See also

constructs, domain_topology

Parameters:

identities: optional

Select domain topology constructs that have an identity, defined by their identities methods, that matches any of the given values.

If no identities are provided then all domain topology constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected constructs in a new Constructs object, unless modified by any filter_kwargs parameters. The returned object will contain no constructs if none were selected.

Examples:

>>> f = cfdm.example_domain(8)
>>> print(f.domain_topologies())
Constructs:
{'domaintopology0': <DomainTopology: 'cell:face(3) >}

domain_topology(*identity, default=ValueError(), key=False, item=False, **filter_kwargs)[source]¶

Select a domain topology construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

Added in version (cfdm): 1.11.0.0

See also

construct, domain_topologies

Parameters:

identity: optional

Select domain topology constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all domain topology constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

If True then return the selected construct identifier. By default the construct itself is returned.

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns:

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_domain(8)
>>> f.domain_topology()
<DomainTopology: cell:face(3) >
>>> f.domain_topology('cell:face', key=True)
'domaintopology0'
>>> f.domain_topology('cell:face', item=True)
('domaintopology0', <DomainTopology: cell:face(3) >)

dump(data=None, display=True, _omit_properties=(), _prefix='', _title=None, _create_title=True, _level=0)[source]¶

A full description of the domain construct.

Returns a description of all properties, including those of metadata constructs and their components, and provides selected values of all data arrays.

Added in version (cfdm): 1.7.0

Parameters:

data: bool or None, optional

If True then show the first and last data elements (and possibly others, depending on the data shape) when displaying data. This can take a long time if getting these data elements needs an expensive computation, possibly including a slow read from local or remote disk.

If False then do not show such data elements, unless data elements have been previously cached, thereby avoiding a potentially high computational cost.

If None (the default) then the value of data will be taken from the cfdm.display_data function.

Note that whenever data elements are displayed, they are cached for fast future retrieval.

Added in version (cfdm): 1.13.0.0

display: bool, optional

If False then return the description as a string. By default the description is printed.

Returns:

str or None: The description. If display is True then the description is printed and None is returned. Otherwise the description is returned as a string.

equals(**kwargs)[source]¶

Whether two constructs are the same.

Equality is strict by default. This means that for two constructs to be considered equal they must have corresponding metadata constructs and for each pair of constructs:

the same descriptive properties must be present, with the same values and data types, and vector-valued properties must also have same the size and be element-wise equal (see the ignore_properties and ignore_data_type parameters), and

if there are data arrays then they must have same shape and data type, the same missing data mask, and be element-wise equal (see the ignore_data_type parameter).

Two real numbers x and y are considered equal if |x-y|<=atol+rtol|y|, where atol (the tolerance on absolute differences) and rtol (the tolerance on relative differences) are positive, typically very small numbers. See the atol and rtol parameters.

Any compression is ignored by default, with only the arrays in their uncompressed forms being compared. See the ignore_compression parameter.

Any type of object may be tested but, in general, equality is only possible with another field construct, or a subclass of one. See the ignore_type parameter.

NetCDF elements, such as netCDF variable and dimension names, do not constitute part of the CF data model and so are not checked.

Added in version (cfdm): 1.7.0

Parameters:

other:

The object to compare for equality.

atol: number, optional

The tolerance on absolute differences between real numbers. The default value is set by the cfdm.atol function.

rtol: number, optional

The tolerance on relative differences between real numbers. The default value is set by the cfdm.rtol function.

ignore_fill_value: bool, optional

If True then all _FillValue and missing_value properties are omitted from the comparison.

ignore_properties: (sequence of) str, optional

The names of properties of the construct (not the metadata constructs) to omit from the comparison. Note that the Conventions property is always omitted.

ignore_data_type: bool, optional

If True then ignore the data types in all numerical comparisons. By default different numerical data types imply inequality, regardless of whether the elements are within the tolerance for equality.

ignore_compression: bool, optional

If False then the compression type and, if applicable, the underlying compressed arrays must be the same, as well as the arrays in their uncompressed forms. By default only the arrays in their uncompressed forms are compared.

ignore_type: bool, optional

Any type of object may be tested but, in general, equality is only possible with another Domain instance, or a subclass of one. If ignore_type is True then cfdm.Domain(source=other) is tested, rather than the other defined by the other parameter.

verbose: int or str or None, optional

If an integer from -1 to 3, or an equivalent string equal ignoring case to one of:

'DISABLE' (0)
'WARNING' (1)
'INFO' (2)
'DETAIL' (3)
'DEBUG' (-1)

set for the duration of the method call only as the minimum cut-off for the verboseness level of displayed output (log) messages, regardless of the globally-configured cfdm.log_level. Note that increasing numerical value corresponds to increasing verbosity, with the exception of -1 as a special case of maximal and extreme verbosity.

Otherwise, if None (the default value), output messages will be shown according to the value of the cfdm.log_level setting.

Overall, the higher a non-negative integer or equivalent string that is set (up to a maximum of 3/'DETAIL') for increasing verbosity, the more description that is printed to convey information about the operation.

Returns:

bool: Whether the two constructs are equal.

Examples

>>> f.equals(f)
True
>>> f.equals(f.copy())
True
>>> f.equals(f[...])
True
>>> f.equals('a string, not a construct')
False

>>> g = f.copy()
>>> g.set_property('foo', 'bar')
>>> f.equals(g)
False
>>> f.equals(g, verbose=3)
Domain: Non-common property name: foo
Domain: Different properties
False

get_construct(key, default=ValueError())[source]¶

Return a metadata construct.

Added in version (cfdm): 1.7.0

Parameters:

key: str

The key of the metadata construct.

Parameter example:: key='domainaxis1'

default: optional

Return the value of the default parameter if the construct does not exist.

If set to an Exception instance then it will be raised instead.

Returns:

The metadata construct.

Examples

>>> f.constructs()
{'auxiliarycoordinate0': <AuxiliaryCoordinate: latitude(10, 9) degree_N>,
 'auxiliarycoordinate1': <AuxiliaryCoordinate: longitude(9, 10) degreeE>,
 'auxiliarycoordinate2': <AuxiliaryCoordinate: long_name:greek_letters(10) >,
 'coordinatereference1': <CoordinateReference: rotated_latitude_longitude>,
 'dimensioncoordinate1': <DimensionCoordinate: grid_latitude(10) degrees>,
 'dimensioncoordinate2': <DimensionCoordinate: grid_longitude(9) degrees>,
 'domainaxis1': <DomainAxis: 10>,
 'domainaxis2': <DomainAxis: 9>}
>>> f.get_construct('dimensioncoordinate1')
<DimensionCoordinate: grid_latitude(10) degrees>

get_data_axes(*identity, default=ValueError(), **filter_kwargs)[source]¶

Gets the keys of the axes spanned by the construct data.

Specifically, returns the keys of the domain axis constructs spanned by the data of a metadata construct.

Added in version (cfdm): 1.7.0

See also

del_data_axes, set_data_axes

Parameters:

identity, filter_kwargs: optional

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

Added in version (cfdm): 1.10.0.0

default: optional

Return the value of the default parameter if the data axes have not been set.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Added in version (cfdm): 1.10.0.0

Returns:

tuple: The keys of the domain axis constructs spanned by the data.

Examples

>>> d = cfdm.example_domain(0)
>>> d.get_data_axes('latitude')
('domainaxis0',)
>>> d.get_data_axes('time')
('domainaxis2',)
>>> d.has_data_axes()
True
>>> d.del_data_axes()
('domainaxis0', 'domainaxis1')
>>> d.has_data_axes()
False
>>> d.get_data_axes(default='no axes')
'no axes'

get_filenames(normalise=True)[source]¶

Return the file names containing the metadata construct data.

Parameters:

normalise: bool, optional: If True then normalise to an absolute path. If False (the default) then no normalisation is done.

Added in version (cfdm): 1.12.0.0

Returns:

set: The file names in normalised, absolute form. If all of the data are in memory then an empty set is returned.

Examples

>>> d = cfdm.example_domain(0)
>>> cfdm.write(d, 'temp_file.nc')
>>> e = cfdm.read('temp_file.nc', domain=True)[0]
>>> e.get_filenames()
{'temp_file.nc'}

get_mesh_id(default=ValueError())[source]¶

Return the UGRID mesh topology identifier.

Different field constructs with the same mesh topology identifier may be assumed to have domains with a shared UGRID mesh topology.

Added in version (cfdm): 1.11.0.0

Parameters:

default: optional

Return the value of the default parameter if the mesh topology identifier has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The value of the mesh topology identifier.

Examples

>>> c = cfdm.Domain()
>>> c.set_mesh_id('df71b85a99894af094411e7cd21c5d68')
>>> c.has_mesh_id()
True
>>> c.get_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.del_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.has_mesh_id()
False
>>> print(c.del_mesh_id(None))
None
>>> print(c.get_mesh_id(None))
None

get_original_filenames()[source]¶

The names of files containing the original data and metadata.

The original files are those that contain some or all of the data and metadata when it was first instantiated, and are necessary (but perhaps not sufficient) to recreate the Domain should the need arise. The cfdm.read function automatically records the original file names on all data that it creates.

The original files of any constituent components are also included.

In-place changes to the Domain will not generally change the collection of original files. However if the Domain was produced by combining other objects that also store their original file names, then the returned files will be the collection of original files from all contributing sources.

Added in version (cfdm): 1.10.0.1

Returns:

set: The original file names in normalised absolute form. If there are no original files then an empty set will be returned.

get_property(prop, default=ValueError())[source]¶

Return a property.

Added in version (cfdm): 1.7.0

Parameters:

prop: str

The name of the property to be returned.

Parameter example:: prop='standard_name'

default: optional

Return the value of the default parameter if the property has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The value of the property.

Examples

>>> f = cfdm.Domain()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

has_bounds()[source]¶

Whether or not there are cell bounds.

This is always False.

Added in version (cfdm): 1.9.0.0

See also

has_data

Returns:: False

Examples

>>> f = cfdm.Domain()
>>> f.has_bounds()
False

has_construct(*identity, **filter_kwargs)[source]¶

Whether a unique metadata construct exists.

Added in version (cfdm): 1.7.0

Parameters:

identity:

Select the unique construct that has the identity, defined by its identities method, that matches the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

Added in version (cfdm): 1.8.9.0

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Added in version (cfdm): 1.8.9.0

Returns:

Whether or not a unique construct can be identified.

Examples

>>> f = cfdm.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]
>>> f.has_construct('time')
True
>>> f.del_construct('altitude')
False

has_data()[source]¶

Whether or not the construct has data.

Domain instances never have data.

Added in version (cfdm): 1.9.0.0

Returns:: False

Examples

>>> f = cfdm.Domain()
>>> f.has_data()
False

has_data_axes(key)[source]¶

Whether the axes spanned by the construct data have been set.

Specifically, whether the domain axis constructs spanned by the data of a metadata construct have been set.

Added in version (cfdm): 1.7.0

Parameters:

key: str

Specify a metadata construct.

Parameter example:: key='domainancillary1'

Returns:

bool: True if domain axis constructs that span the data been set, otherwise False.

Examples

>>> f.set_data_axes(['domainaxis0', 'domainaxis1'])
>>> f.get_data_axes()
('domainaxis0', 'domainaxis1')
>>> f.del_data_axes()
('domainaxis0', 'domainaxis1')
>>> print(f.del_dataxes(None))
None
>>> print(f.get_data_axes(default=None))
None

has_geometry()[source]¶

Return whether or not any coordinates have cell geometries.

Added in version (cfdm): 1.8.0

Returns:

bool: True if there are geometries, otherwise False.

Examples

>>> f = cfdm.Domain()
>>> f.has_geometry()
False

has_mesh_id()[source]¶

Whether the UGRID mesh topology identifier has been set.

Different field constructs with the same mesh topology identifier may be assumed to have domains with a shared UGRID mesh topology.

Added in version (cfdm): 1.11.0.0

Returns:

bool: True if the mesh topology identifier has been set, otherwise False.

Examples

>>> c = cfdm.Domain()
>>> c.set_mesh_id('df71b85a99894af094411e7cd21c5d68')
>>> c.has_mesh_id()
True
>>> c.get_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.del_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.has_mesh_id()
False
>>> print(c.del_mesh_id(None))
None
>>> print(c.get_mesh_id(None))
None

has_property(prop)[source]¶

Whether a property has been set.

Added in version (cfdm): 1.7.0

Parameters:

prop: str

The name of the property.

Parameter example:: prop='long_name'

Returns:

bool: True if the property has been set, otherwise False.

Examples

>>> f = cfdm.Domain()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

identities()[source]¶

Return all possible identities.

The identities comprise:

The cf_role property, preceded by 'cf_role='.
The long_name property, preceded by 'long_name='.
All other properties, preceded by the property name and a equals e.g. 'foo=bar'.
The netCDF variable name, preceded by 'ncvar%'.

Added in version (cfdm): 1.9.0.0

See also

identity

Returns:

list: The identities.

Examples

>>> d = cfdm.Domain()
>>> d.set_properties({'foo': 'bar',
...                   'long_name': 'Domain for model'})
>>> d.nc_set_variable('dom1')
>>> d.identities()
['long_name=Domain for model', 'foo=bar', 'ncvar%dom1']

identity(default='')[source]¶

Return the canonical identity.

By default the identity is the first found of the following:

The cf_role property, preceded by 'cf_role='.
The long_name property, preceded by 'long_name='.
The netCDF variable name, preceded by 'ncvar%'.
The value of the default parameter.

Added in version (cfdm): 1.9.0.0

See also

identities

Parameters:

default: optional: If no identity can be found then return the value of the default parameter.

Returns:

The identity.

Examples

>>> d = cfdm.Domain()
>>> d.set_properties({'foo': 'bar',
...                   'long_name': 'Domain for model'})
>>> d.nc_set_variable('dom1')
>>> d.identity()
'long_name=Domain for model'
>>> d.del_property('long_name')
'long_name=Domain for model'
>>> d.identity(default='no identity')
'ncvar%dom1'
>>> d.identity()
'ncvar%dom1'
>>> d.nc_del_variable()
'dom1'
>>> d.identity()
''
>>> d.identity(default='no identity')
'no identity'

nc_clear_component_dimension_groups(component)[source]¶

Remove the netCDF dimension groups of components.

Removes the netCDF dimension groups for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

Returns:

None

Examples

>>> f.nc_clear_component_dimension_groups('interior_ring')

nc_clear_component_sample_dimension_groups(component)[source]¶

Remove the netCDF sample dimension groups of components.

Removes the netCDF sample dimension groups for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

Returns:

None

Examples

>>> f.nc_del_component_sample_dimension_groups('count')

nc_clear_component_variable_groups(component)[source]¶

Remove the netCDF variable groups of components.

Removes the netCDF variable groups for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'node_count'`	Node count variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays
`'list'`	List variables for compression by gathering

Returns:

None

Examples

>>> f.nc_clear_component_variable_groups('interior_ring')

nc_clear_geometry_variable_groups()[source]¶

Remove the netCDF geometry variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for removing the group structure is to set the netCDF variable name, with nc_set_geometry_variable, with no / characters.

Added in version (cfdm): 1.8.6

Returns:

tuple of str: The removed group structure.

Examples

>>> f.nc_set_geometry_variable('geometry1')
>>> f.nc_geometry_variable_groups()
()
>>> f.nc_set_geometry_variable_groups(['forecast', 'model'])
>>> f.nc_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_get_geometry_variable()
'/forecast/model/geometry1'
>>> f.nc_clear_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_get_geometry_variable()
'geometry1'

>>> f.nc_set_geometry_variable('/forecast/model/geometry1')
>>> f.nc_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_del_geometry_variable('/forecast/model/geometry1')
'/forecast/model/geometry1'
>>> f.nc_geometry_variable_groups()
()

nc_clear_global_attributes()[source]¶

Removes properties to write as netCDF global attributes.

When multiple field constructs are being written to the same file, it is only possible to create a netCDF global attribute from a property that has identical values for each field construct. If any field construct’s property has a different value then the property will not be written as a netCDF global attribute, even if it has been selected as such, but will appear instead as attributes on the netCDF data variables corresponding to each field construct.

The standard description-of-file-contents properties are always written as netCDF global attributes, if possible, so selecting them is optional.

Added in version (cfdm): 1.7.0

Returns:

dict: The removed selection of properties requested for writing to netCDF global attributes.

Examples

>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None}
>>> f.nc_set_global_attribute('foo')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None, 'foo': None}
>>> f.nc_set_global_attribute('comment', 'global comment')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': None}
>>> f.nc_clear_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': None}
>>> f.nc_global_attributes()
{}

nc_clear_group_attributes()[source]¶

Removes properties to write as netCDF group attributes.

Added in version (cfdm): 1.8.6

Returns:

dict: The removed selection of properties requested for writing to netCDF group attributes.

Examples

>>> f.nc_group_attributes()
{'comment': None}
>>> f.nc_set_group_attribute('foo')
>>> f.nc_group_attributes()
{'comment': None, 'foo': None}
>>> f.nc_set_group_attribute('foo', 'bar')
>>> f.nc_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes(values=True)
{'comment': 'forecast comment', 'foo': 'bar'}
>>> f.nc_clear_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes()
{}

nc_clear_mesh_variable_groups()[source]¶

Remove the netCDF mesh variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for removing the group structure is to set the netCDF mesh variable name, with nc_set_mesh_variable, with no / characters.

Added in version (cfdm): 1.13.1.0

Returns:

tuple of str: The removed group structure.

Examples

>>> f.nc_set_mesh_variable('time')
>>> f.nc_mesh_variable_groups()
()
>>> f.nc_set_mesh_variable_groups(['forecast', 'model'])
>>> f.nc_mesh_variable_groups()
('forecast', 'model')
>>> f.nc_get_mesh_variable()
'/forecast/model/time'
>>> f.nc_clear_mesh_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_mesh_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_mesh_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_mesh_variable_groups()
()

nc_clear_variable_groups()[source]¶

Remove the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for removing the group structure is to set the netCDF variable name, with nc_set_variable, with no / characters.

Added in version (cfdm): 1.8.6

Returns:

tuple of str: The removed group structure.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()

nc_del_component_dimension(component)[source]¶

Remove the netCDF dimension name of components.

Removes the netCDF dimension name for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

Returns:

None

Examples

>>> f.nc_del_component_dimension('interior_ring')

nc_del_component_sample_dimension(component)[source]¶

Remove the netCDF sample dimension name of components.

Removes the netCDF sample dimension name for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

Returns:

None

Examples

>>> f.nc_del_component_sample_dimension('count')

nc_del_component_variable(component)[source]¶

Remove the netCDF variable name of components.

Removes the netCDF variable name for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'node_count'`	Node count variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays
`'list'`	List variables for compression by gathering

Returns:

None

Examples

>>> f.nc_del_component_variable('interior_ring')

nc_del_geometry_variable(default=ValueError())[source]¶

Remove the netCDF geometry container variable name.

Added in version (cfdm): 1.8.0

Parameters:

default: optional: Return the value of the default parameter if the netCDF dimension name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The removed netCDF geometry container variable name.

Examples

>>> f.nc_set_geometry_variable('geometry')
>>> f.nc_has_geometry_variable()
True
>>> f.nc_get_geometry_variable()
'geometry'
>>> f.nc_del_geometry_variable()
'geometry'
>>> f.nc_has_geometry_variable()
False
>>> print(f.nc_get_geometry_variable(None))
None
>>> print(f.nc_del_geometry_variable(None))
None

nc_del_mesh_variable(default=ValueError())[source]¶

Remove the netCDF mesh variable name.

Added in version (cfdm): 1.13.1.0

Parameters:

default: optional: Return the value of the default parameter if the netCDF mesh variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The removed netCDF mesh variable name.

Examples

>>> f.nc_set_mesh_variable('mesh1')
>>> f.nc_has_mesh_variable()
True
>>> f.nc_get_mesh_variable()
'mesh1'
>>> f.nc_del_mesh_variable()
'mesh1'
>>> f.nc_has_mesh_variable()
False
>>> print(f.nc_get_mesh_variable(None))
None
>>> print(f.nc_del_mesh_variable(None))
None

nc_del_variable(default=ValueError())[source]¶

Remove the netCDF variable name.

Added in version (cfdm): 1.7.0

Parameters:

default: optional: Return the value of the default parameter if the netCDF variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The removed netCDF variable name.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_geometry_variable_groups()[source]¶

Return the netCDF geometry variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

Added in version (cfdm): 1.8.6

See also

nc_clear_geometry_variable_groups,

nc_set_geometry_variable_groups

Returns:

tuple of str: The group structure.

Examples

>>> f.nc_set_geometry_variable('geometry1')
>>> f.nc_geometry_variable_groups()
()
>>> f.nc_set_geometry_variable_groups(['forecast', 'model'])
>>> f.nc_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_get_geometry_variable()
'/forecast/model/geometry1'
>>> f.nc_clear_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_get_geometry_variable()
'geometry1'

>>> f.nc_set_geometry_variable('/forecast/model/geometry1')
>>> f.nc_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_del_geometry_variable('/forecast/model/geometry1')
'/forecast/model/geometry1'
>>> f.nc_geometry_variable_groups()
()

nc_get_geometry_variable(default=ValueError())[source]¶

Return the netCDF geometry container variable name.

Added in version (cfdm): 1.8.0

Parameters:

default: optional: Return the value of the default parameter if the netCDF dimension name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The netCDF geometry container variable name.

Examples

>>> f.nc_set_geometry_variable('geometry')
>>> f.nc_has_geometry_variable()
True
>>> f.nc_get_geometry_variable()
'geometry'
>>> f.nc_del_geometry_variable()
'geometry'
>>> f.nc_has_geometry_variable()
False
>>> print(f.nc_get_geometry_variable(None))
None
>>> print(f.nc_del_geometry_variable(None))
None

nc_get_mesh_variable(default=ValueError())[source]¶

Return the netCDF mesh variable name.

Added in version (cfdm): 1.13.1.0

Parameters:

default: optional: Return the value of the default parameter if the netCDF mesh variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The netCDF mesh variable name. If unset then default is returned, if provided.

Examples

>>> f.nc_set_mesh_variable('mesh1')
>>> f.nc_has_mesh_variable()
True
>>> f.nc_get_mesh_variable()
'mesh1'
>>> f.nc_del_mesh_variable()
'mesh1'
>>> f.nc_has_mesh_variable()
False
>>> print(f.nc_get_mesh_variable(None))
None
>>> print(f.nc_del_mesh_variable(None))
None

nc_get_variable(default=ValueError())[source]¶

Return the netCDF variable name.

Added in version (cfdm): 1.7.0

Parameters:

default: optional: Return the value of the default parameter if the netCDF variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The netCDF variable name. If unset then default is returned, if provided.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_global_attributes(values=False)[source]¶

Returns properties to write as netCDF global attributes.

When multiple field constructs are being written to the same file, it is only possible to create a netCDF global attribute from a property that has identical values for each field construct. If any field construct’s property has a different value then the property will not be written as a netCDF global attribute, even if it has been selected as such, but will appear instead as attributes on the netCDF data variables corresponding to each field construct.

The standard description-of-file-contents properties are always written as netCDF global attributes, if possible, so selecting them is optional.

Added in version (cfdm): 1.7.0

Parameters:

values: bool, optional: Return the value (rather than None) for any global attribute that has, by definition, the same value as a construct property.

Added in version (cfdm): 1.8.2

Returns:

dict: The selection of properties requested for writing to netCDF global attributes.

Examples

>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None}
>>> f.nc_set_global_attribute('foo')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None, 'foo': None}
>>> f.nc_set_global_attribute('comment', 'global comment')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': None}
>>> f.nc_global_attributes(values=True)
{'Conventions': 'CF-1.12', 'comment': 'global_comment', 'foo': 'bar'}
>>> f.nc_clear_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': None}
>>> f.nc_global_attributes()
{}

nc_group_attributes(values=False)[source]¶

Returns properties to write as netCDF group attributes.

Added in version (cfdm): 1.8.6

Parameters:

values: bool, optional: Return the value (rather than None) for any group attribute that has, by definition, the same value as a construct property.

Returns:

dict: The selection of properties requested for writing to netCDF group attributes.

Examples

>>> f.nc_group_attributes()
{'comment': None}
>>> f.nc_set_group_attribute('foo')
>>> f.nc_group_attributes()
{'comment': None, 'foo': None}
>>> f.nc_set_group_attribute('foo', 'bar')
>>> f.nc_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes(values=True)
{'comment': 'forecast comment', 'foo': 'bar'}
>>> f.nc_clear_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes()
{}

nc_has_geometry_variable()[source]¶

Whether a netCDF geometry container variable has a name.

Added in version (cfdm): 1.8.0

Returns:

bool: True if the netCDF geometry container variable name has been set, otherwise False.

Examples

>>> f.nc_set_geometry_variable('geometry')
>>> f.nc_has_geometry_variable()
True
>>> f.nc_get_geometry_variable()
'geometry'
>>> f.nc_del_geometry_variable()
'geometry'
>>> f.nc_has_geometry_variable()
False
>>> print(f.nc_get_geometry_variable(None))
None
>>> print(f.nc_del_geometry_variable(None))
None

nc_has_mesh_variable()[source]¶

Whether the netCDF mesh variable name is set.

Added in version (cfdm): 1.13.1.0

Returns:

bool: True if the netCDF mesh variable name has been set, otherwise False.

Examples

>>> f.nc_set_mesh_variable('mesh1')
>>> f.nc_has_mesh_variable()
True
>>> f.nc_get_mesh_variable()
'mesh1'
>>> f.nc_del_mesh_variable()
'mesh1'
>>> f.nc_has_mesh_variable()
False
>>> print(f.nc_get_mesh_variable(None))
None
>>> print(f.nc_del_mesh_variable(None))
None

nc_has_variable()[source]¶

Whether the netCDF variable name has been set.

Added in version (cfdm): 1.7.0

Returns:

bool: True if the netCDF variable name has been set, otherwise False.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_mesh_variable_groups()[source]¶

Return the netCDF mesh variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

Added in version (cfdm): 1.13.1.0

Returns:

tuple of str: The group structure.

Examples

>>> f.nc_set_mesh_variable('time')
>>> f.nc_mesh_variable_groups()
()
>>> f.nc_set_mesh_variable_groups(['forecast', 'model'])
>>> f.nc_mesh_variable_groups()
('forecast', 'model')
>>> f.nc_get_mesh_variable()
'/forecast/model/time'
>>> f.nc_clear_mesh_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_mesh_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_mesh_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_mesh_variable_groups()
()

nc_set_component_dimension(component, value)[source]¶

Set the netCDF dimension name of components.

Sets the netCDF dimension name for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

value: str

The netCDF dimension name to be set for each component.

Returns:

None

Examples

>>> f.nc_set_component_dimension('interior_ring', 'part')

nc_set_component_dimension_groups(component, groups)[source]¶

Set the netCDF dimension groups of components.

Sets the netCDF dimension groups for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

groups: sequence of str

The new group structure for each component.

Returns:

None

Examples

>>> f.nc_set_component_dimension_groups('interior_ring', ['forecast'])

nc_set_component_sample_dimension(component, value)[source]¶

Set the netCDF sample dimension name of components.

Sets the netCDF sample dimension name for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

value: str

The netCDF sample_dimension name to be set for each component.

Returns:

None

Examples

>>> f.nc_set_component_sample_dimension('count', 'obs')

nc_set_component_sample_dimension_groups(component, groups)[source]¶

Set the netCDF sample dimension groups of components.

Sets the netCDF sample dimension groups for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays

groups: sequence of str

The new group structure for each component.

Returns:

None

Examples

>>> f.nc_set_component_sample_dimension_groups('count', ['forecast'])

nc_set_component_variable(component, value)[source]¶

Set the netCDF variable name for components.

Sets the netCDF variable name for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'node_count'`	Node count variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays
`'list'`	List variables for compression by gathering

value: str

The netCDF variable name to be set for each component.

Returns:

None

Examples

>>> f.nc_set_component_variable('interior_ring', 'interiorring_1')

nc_set_component_variable_groups(component, groups)[source]¶

Set the netCDF variable groups of components.

Sets the netCDF variable groups for all components of a given type.

Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF names can be set on all such occurrences individually, or preferably by using this method to ensure consistency across all such components.

Added in version (cfdm): 1.8.6.0

Parameters:

component: str

Specify the component type. One of:

component	Description
`'interior_ring'`	Interior ring variables for geometry coordinates
`'node_count'`	Node count variables for geometry coordinates
`'part_node_count'`	Part node count variables for geometry coordinates
`'count'`	Count variables for contiguous ragged arrays
`'index'`	Index variables for indexed ragged arrays
`'list'`	List variables for compression by gathering

groups: sequence of str

The new group structure for each component.

Returns:

None

Examples

>>> f.nc_set_component_variable_groups('interior_ring', ['forecast'])

nc_set_geometry_variable(value)[source]¶

Set the netCDF geometry container variable name.

If there are any / (slash) characters in the netCDF name then these act as delimiters for a group hierarchy. By default, or if the name starts with a / character and contains no others, the name is assumed to be in the root group.

Added in version (cfdm): 1.8.0

Parameters:

value: str: The value for the netCDF geometry container variable name.

Returns:

None

Examples

>>> f.nc_set_geometry_variable('geometry')
>>> f.nc_has_geometry_variable()
True
>>> f.nc_get_geometry_variable()
'geometry'
>>> f.nc_del_geometry_variable()
'geometry'
>>> f.nc_has_geometry_variable()
False
>>> print(f.nc_get_geometry_variable(None))
None
>>> print(f.nc_del_geometry_variable(None))
None

nc_set_geometry_variable_groups(groups)[source]¶

Set the netCDF geometry variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for setting the group structure is to set the netCDF variable name, with nc_set_geometry_variable, with the group structure delimited by / characters.

Added in version (cfdm): 1.8.6

Parameters:

groups: sequence of str: The new group structure.

Returns:

tuple of str: The group structure prior to being reset.

Examples

>>> f.nc_set_geometry_variable('geometry1')
>>> f.nc_geometry_variable_groups()
()
>>> f.nc_set_geometry_variable_groups(['forecast', 'model'])
>>> f.nc_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_get_geometry_variable()
'/forecast/model/geometry1'
>>> f.nc_clear_geometry_variable_groups()
('forecast', 'model')
>>> f.nc_get_geometry_variable()
'geometry1'

>>> f.nc_set_geometry_variable('/forecast/model/geometry1')
>>> f.nc_geometry__variablegroups()
('forecast', 'model')
>>> f.nc_del_geometry_variable('/forecast/model/geometry1')
'/forecast/model/geometry1'
>>> f.nc_geometry_variable_groups()
()

nc_set_global_attribute(prop, value=None)[source]¶

Select a property to be written as a netCDF global attribute.

When multiple field constructs are being written to the same file, it is only possible to create a netCDF global attribute from a property that has identical values for each field construct. If any field construct’s property has a different value then the property will not be written as a netCDF global attribute, even if it has been selected as such, but will appear instead as attributes on the netCDF data variables corresponding to each field construct.

The standard description-of-file-contents properties are always written as netCDF global attributes, if possible, so selecting them is optional.

Added in version (cfdm): 1.7.0

Parameters:

prop: str: Select the property to be written (if possible) as a netCDF global attribute.
value: optional: The value of the netCDF global attribute, which will be created (if possible) in addition to the property as written to a netCDF data variable. If unset (or None) then this acts as an instruction to write the property (if possible) to a netCDF global attribute instead of to a netCDF data variable.

Returns:

None

Examples

>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None}
>>> f.nc_set_global_attribute('foo')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None, 'foo': None}
>>> f.nc_set_global_attribute('comment', 'global comment')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': None}
>>> f.nc_clear_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': None}
>>> f.nc_global_attributes()
{}

nc_set_global_attributes(properties, copy=True)[source]¶

Set properties to be written as netCDF global attributes.

When multiple field constructs are being written to the same file, it is only possible to create a netCDF global attribute from a property that has identical values for each field construct. If any field construct’s property has a different value then the property will not be written as a netCDF global attribute, even if it has been selected as such, but will appear instead as attributes on the netCDF data variables corresponding to each field construct.

The standard description-of-file-contents properties are always written as netCDF global attributes, if possible, so selecting them is optional.

Added in version (cfdm): 1.7.10

Parameters:

properties: dict

Set the properties be written as a netCDF global attribute from the dictionary supplied. The value of a netCDF global attribute, which will be created (if possible) in addition to the property as written to a netCDF data variable. If a value of None is used then this acts as an instruction to write the property (if possible) to a netCDF global attribute instead of to a netCDF data variable.

Parameter example:: properties={'Conventions': None, 'project': 'research'}

copy: bool, optional

If False then any property values provided by the properties parameter are not copied before insertion. By default they are deep copied.

Returns:

None

Examples

>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None}
>>> f.nc_set_global_attributes({})
>>> f.nc_set_global_attributes({'foo': None})
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': None, 'foo': None}
>>> f.nc_set_global_attributes('comment', 'global comment')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': None}
>>> f.nc_set_global_attributes('foo', 'bar')
>>> f.nc_global_attributes()
{'Conventions': None, 'comment': 'global_comment', 'foo': 'bar'}

nc_set_group_attribute(prop, value=None)[source]¶

Select a property to be written as a netCDF group attribute.

Added in version (cfdm): 1.8.6

Parameters:

prop: str: Select the property to be written (if possible) as a netCDF group attribute.
value: optional: The value of the netCDF group attribute, which will be created (if possible) in addition to the property as written to a netCDF data variable. If unset (or None) then this acts as an instruction to write the property (if possible) to a netCDF group attribute instead of to a netCDF data variable.

Returns:

None

Examples

>>> f.nc_group_attributes()
{'comment': None}
>>> f.nc_set_group_attribute('foo')
>>> f.nc_group_attributes()
{'comment': None, 'foo': None}
>>> f.nc_set_group_attribute('foo', 'bar')
>>> f.nc_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes(values=True)
{'comment': 'forecast comment', 'foo': 'bar'}
>>> f.nc_clear_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes()
{}

nc_set_group_attributes(properties, copy=True)[source]¶

Set properties to be written as netCDF group attributes.

Added in version (cfdm): 1.8.6

Parameters:

properties: dict

Set the properties be written as a netCDF group attribute from the dictionary supplied. The value of a netCDF group attribute, which will be created (if possible) in addition to the property as written to a netCDF data variable. If a value of None is used then this acts as an instruction to write the property (if possible) to a netCDF group attribute instead of to a netCDF data variable.

Parameter example:: properties={'Conventions': None, 'project': 'research'}

copy: bool, optional

If False then any property values provided by the properties parameter are not copied before insertion. By default they are deep copied.

Returns:

None

Examples

>>> f.nc_group_attributes()
{'comment': None}
>>> f.nc_set_group_attribute('foo')
>>> f.nc_group_attributes()
{'comment': None, 'foo': None}
>>> f.nc_set_group_attribute('foo', 'bar')
>>> f.nc_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes(values=True)
{'comment': 'forecast comment', 'foo': 'bar'}
>>> f.nc_clear_group_attributes()
{'comment': None, 'foo': 'bar'}
>>> f.nc_group_attributes()
{}

nc_set_mesh_variable(value)[source]¶

Set the netCDF mesh variable name.

If there are any / (slash) characters in the netCDF name then these act as delimiters for a group hierarchy. By default, or if the name starts with a / character and contains no others, the name is assumed to be in the root group.

Added in version (cfdm): 1.13.1.0

Parameters:

value: str: The value for the netCDF mesh variable name.

Returns:

None

Examples

>>> f.nc_set_mesh_variable('mesh1')
>>> f.nc_has_mesh_variable()
True
>>> f.nc_get_mesh_variable()
'mesh1'
>>> f.nc_del_mesh_variable()
'mesh1'
>>> f.nc_has_mesh_variable()
False
>>> print(f.nc_get_mesh_variable(None))
None
>>> print(f.nc_del_mesh_variable(None))
None

nc_set_mesh_variable_groups(groups)[source]¶

Set the netCDF mesh_variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for setting the group structure is to set the netCDF mesh variable name, with nc_set_mesh_variable, with the group structure delimited by / characters.

Added in version (cfdm): 1.13.1.0

Parameters:

groups: sequence of str: The new group structure.

Returns:

tuple of str: The group structure prior to being reset.

Examples

>>> f.nc_set_mesh_variable('time')
>>> f.nc_mesh_variable_groups()
()
>>> f.nc_set_mesh_variable_groups(['forecast', 'model'])
>>> f.nc_mesh_variable_groups()
('forecast', 'model')
>>> f.nc_get_mesh_variable()
'/forecast/model/time'
>>> f.nc_clear_mesh_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_mesh_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_mesh_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_mesh_variable_groups()
()

nc_set_variable(value)[source]¶

Set the netCDF variable name.

If there are any / (slash) characters in the netCDF name then these act as delimiters for a group hierarchy. By default, or if the name starts with a / character and contains no others, the name is assumed to be in the root group.

Added in version (cfdm): 1.7.0

Parameters:

value: str: The value for the netCDF variable name.

Returns:

None

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_set_variable_groups(groups)[source]¶

Set the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for setting the group structure is to set the netCDF variable name, with nc_set_variable, with the group structure delimited by / characters.

Added in version (cfdm): 1.8.6

Parameters:

groups: sequence of str: The new group structure.

Returns:

tuple of str: The group structure prior to being reset.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()

nc_variable_groups()[source]¶

Return the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

Added in version (cfdm): 1.8.6

Returns:

tuple of str: The group structure.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()

node_coordinates(persist=False)[source]¶

Create the node coordinates for a UGRID mesh topology.

For face and edge cells, the nodes are the cell vertices. For point cells, the nodes are the same points.

Added in version (cfdm): 1.13.1.0

See also

(cfdm) domain_topology

Parameters:

persist: bool, optional: If True then persist into memory the data of the returned node coordinates. If False (the default) then don’t do this.

Returns:

list: The node coordinates, stored in zero or more cfdm.AuxiliaryCoordinate constructs.

Examples:

Face cells:

>>> f = cfdm.example_field(8)
>>> print(f)
Field: air_temperature (ncvar%ta)
---------------------------------
Data            : air_temperature(time(2), ncdim%nMesh2_face(3)) K
Cell methods    : time(2): point (interval: 3600 s)
Dimension coords: time(2) = [2016-01-02 01:00:00, 2016-01-02 11:00:00] gregorian
Auxiliary coords: longitude(ncdim%nMesh2_face(3)) = [-44.0, -44.0, -42.0] degrees_east
                : latitude(ncdim%nMesh2_face(3)) = [34.0, 32.0, 34.0] degrees_north
Topologies      : cell:face(ncdim%nMesh2_face(3), 4) = [[2, ..., --]]
Connectivities  : connectivity:edge(ncdim%nMesh2_face(3), 5) = [[0, ..., --]]
>>> f.node_coordinates()
[<AuxiliaryCoordinate: longitude(7) degrees_east>,
 <AuxiliaryCoordinate: latitude(7) degrees_north>]

Point cells:

>>> f = cfdm.example_field(10)
>>> print(f)
Field: air_pressure (ncvar%pa)
------------------------------
Data            : air_pressure(time(2), ncdim%nMesh2_node(7)) hPa
Cell methods    : time(2): point (interval: 3600 s)
Dimension coords: time(2) = [2016-01-02 01:00:00, 2016-01-02 11:00:00] gregorian
Auxiliary coords: longitude(ncdim%nMesh2_node(7)) = [-45.0, ..., -40.0] degrees_east
                : latitude(ncdim%nMesh2_node(7)) = [35.0, ..., 34.0] degrees_north
Topologies      : cell:point(ncdim%nMesh2_node(7), 5) = [[0, ..., --]]
>>> f.node_coordinates()
[<AuxiliaryCoordinate: longitude(7) degrees_east>,
 <AuxiliaryCoordinate: latitude(7) degrees_north>]

persist(inplace=False)[source]¶

Persist data into memory.

Persisting turns an underlying lazy dask array into an equivalent chunked dask array, but now with the results fully computed and cached in memory. This can avoid the expense of re-reading the data from disk, or re-computing it, when the data is accessed on multiple occasions.

Performance

persist causes delayed operations to be computed.

Added in version (cfdm): 1.12.0.0

See also

cfdm.Data.persist

Parameters:

inplace: bool, optional: If True then do the operation in-place and return None.

Returns:

Domain or None: The domain construct with persisted metadata. If the operation was in-place then None is returned.

properties()[source]¶

Return all properties.

Added in version (cfdm): 1.7.0

Returns:

dict: The properties.

Examples

>>> f = cfdm.Domain()
>>> f.properties()
{}
>>> f.set_properties({'standard_name': 'air_pressure',
...                   'long_name': 'Air Pressure'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure'}
>>> f.set_properties({'standard_name': 'air_pressure', 'foo': 'bar'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.clear_properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.properties()
{}

set_construct(construct, key=None, axes=None, copy=True)[source]¶

Set a metadata construct.

Added in version (cfdm): 1.7.0

Parameters:

construct:

The metadata construct to be inserted.

key: str, optional

The construct identifier to be used for the construct. If not set then a new, unique identifier is created automatically. If the identifier already exists then the existing construct will be replaced.

Parameter example:: key='cellmeasure0'

axes: (sequence of) str, optional

The construct identifiers of the domain axis constructs spanned by the data array. An exception is raised if used for a metadata construct that can not have a data array, i.e. domain axis, cell method and coordinate reference constructs.

Parameter example:: axes='domainaxis1'
Parameter example:: axes=['domainaxis1']
Parameter example:: axes=['domainaxis1', 'domainaxis0']

copy: bool, optional

If True then set a copy of the construct. By default the construct is copied.

Returns:

str: The construct identifier for the construct.

Examples

>>> key = f.set_construct(c)
>>> key = f.set_construct(c, copy=False)
>>> key = f.set_construct(c, axes='domainaxis2')
>>> key = f.set_construct(c, key='cellmeasure0')

set_data_axes(axes, key)[source]¶

Sets domain axis constructs spanned by the construct data.

Added in version (cfdm): 1.7.0

See also

data, del_data_axes, get_data, get_data_axes, has_data_axes

Parameters:

axes: sequence of str

The identifiers of the domain axis constructs spanned by the data of the field or of a metadata construct.

Parameter example:: axes='domainaxis1'
Parameter example:: axes=['domainaxis1']
Parameter example:: axes=['domainaxis1', 'domainaxis0']

key: str

Specify a metadata construct.

Parameter example:: key='domainancillary1'

Returns:

None

Examples

>>> f.set_data_axes(['domainaxis0', 'domainaxis1'])
>>> f.get_data_axes()
('domainaxis0', 'domainaxis1')
>>> f.del_data_axes()
('domainaxis0', 'domainaxis1')
>>> print(f.del_dataxes(None))
None
>>> print(f.get_data_axes(None))
None

set_mesh_id(mesh_id)[source]¶

Set a UGRID mesh topology identifier.

Different field constructs with the same mesh topology identifier may be assumed to have domains with a shared UGRID mesh topology.

Added in version (cfdm): 1.11.0.0

Parameters:

mesh_id: str: The value for the mesh topology identifier.

Returns:

None

Examples

>>> c = cfdm.Domain()
>>> c.set_mesh_id('df71b85a99894af094411e7cd21c5d68')
>>> c.has_mesh_id()
True
>>> c.get_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.del_mesh_id()
'df71b85a99894af094411e7cd21c5d68'
>>> c.has_mesh_id()
False
>>> print(c.del_mesh_id(None))
None
>>> print(c.get_mesh_id(None))
None

set_properties(properties, copy=True)[source]¶

Set properties.

Added in version (cfdm): 1.7.0

Parameters:

properties: dict

Store the properties from the dictionary supplied.

Parameter example:: properties={'standard_name': 'altitude', 'foo': 'bar'}

copy: bool, optional

If False then any property values provided by the properties parameter are not copied before insertion. By default they are deep copied.

Returns:

None

Examples

>>> f = cfdm.Domain()
>>> f.properties()
{}
>>> f.set_properties({'standard_name': 'air_pressure',
...                   'long_name': 'Air Pressure'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure'}
>>> f.set_properties({'standard_name': 'air_pressure', 'foo': 'bar'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.clear_properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.properties()
{}

set_property(prop, value, copy=True)[source]¶

Set a property.

Added in version (cfdm): 1.7.0

Parameters:

prop: str: The name of the property to be set.
value:: The value for the property.
copy: bool, optional: If True then set a deep copy of value.

Returns:

None

Examples

>>> f = cfdm.Domain()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

to_xarray(group=True)[source]¶

Convert the Domain to an xarray dataset.

If the cf_xarray package (https://cf-xarray.readthedocs.io) is installed then the cf_xarray accessors that allow some interpretation of CF attributes will be present on xarray.DataArray and xarray.Dataset objects.

Note that ds = f.to_xarray() is identical to ds = cfdm.write(f, fmt='XARRAY'); and multiple domains may be written to the same xarray dataset with cfdm.write (e.g. ds = cfdm.write([f, g], fmt='XARRAY')). Also, cfdm.write allows a mixture of fields and domains to be written to the same xarray dataset.

An xarray dataset can be converted to one or more fields with f = cfdm.read(ds), or domains with f = cfdm.read(ds, domain=True).

Added in version (cfdm): 1.13.2.0

See also

cfdm.write, cfdm.read

Parameter:

group: bool, optional: If False then create a “flat” dataset, i.e. one with only the root group, regardless of any group structure specified by the netCDF interfaces of the domain and its components. If True (the default) then any sub-groups will be created and populated.

Returns:

xarray.Dataset or xarray.DataTree

The equivalent xarray dataset.

If there are no sub-groups of the root group, or if group is False, then an xarray.Dataset is returned.

If there are sub-groups of the root group and group is True, then an xarray.DataTree is returned.

uncompress(inplace=False)[source]¶

Uncompress the domain construct.

Compression saves space by identifying and removing unwanted missing data. Such compression techniques store the data more efficiently and result in no precision loss. Whether or not the metadata constructs are compressed does not alter its functionality nor external appearance.

Any compressed metadata constructs are uncompressed, and all other metadata constructs are unchanged.

Added in version (cfdm): 1.10.0.0

See also

compress TODO

Parameters:

inplace: bool, optional: If True then do the operation in-place and return None.

Returns:

Domain or None: The uncompressed domain construct, or None if the operation was in-place.

Examples

>>> e = d.uncompress()
>>> e.equals(d)
True

property construct_type¶

Return a description of the construct type.

Added in version (cfdm): 1.9.0.0

Returns:

str: The construct type.

Examples

>>> d = cfdm.Domain()
>>> d.construct_type
'domain'

property constructs¶

Return the metadata constructs.

Added in version (cfdm): 1.7.0

Returns:

Constructs: The constructs.

Examples

>>> d = cfdm.example_field(0)
>>> print(d.constructs)
Constructs:
{'cellmethod0': <CellMethod: area: mean>,
 'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: time(1) days since 2018-12-01 >,
 'domainaxis0': <DomainAxis: size(5)>,
 'domainaxis1': <DomainAxis: size(8)>,
 'domainaxis2': <DomainAxis: size(1)>}

cfdm 1.13.3.0

Related Topics

cfdm.domain¶