cfdm.core.domain

Classes

Domain(*args, **kwargs)

A domain construct of the CF data model.
class cfdm.core.domain.Domain(*args, **kwargs)[source]

Bases: FieldDomain, Properties

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.

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.core.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.core.example_field(0)
>>> d = cfdm.core.Domain.fromconstructs(f.constructs)
>>> d
<Domain: {1, 5, 8}>
>>> d = cfdm.core.Domain.fromconstructs(f.constructs.copy())
clear_properties()[source]

Remove all properties.

Added in version (cfdm): 1.7.0

See also

del_properties, del_property, properties, set_properties

Returns:
dict

The properties that have been removed.

Examples

>>> f = cfdm.core.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()
{}
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.core.Domain()
>>> e = d.copy()
del_construct(key, default=ValueError())[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 metadata constructs. However, a domain ancillary construct may be removed even if it is referenced by coordinate reference construct.

Added in version (cfdm): 1.9.0.0

See also

get_construct, constructs, has_construct, set_construct

Parameters:
key: str

The construct identifier of the metadata construct to be removed.

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:

The removed metadata construct.

Examples

>>> f.del_construct('auxiliarycoordinate2')
<AuxiliaryCoordinate: latitude(111, 106) degrees_north>
>>> f.del_construct('auxiliarycoordinate2')
ValueError: Can't get remove non-existent construct
>>> f.del_construct('auxiliarycoordinate2', default=False)
False
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

See also

get_data_axes, has_data_axes, set_data_axes

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_properties(properties)[source]

Remove properties.

Added in version (cfdm): 1.10.0.3

See also

clear_properties, del_property, properties, set_properties

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.core.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

See also

clear_properties, get_property, has_property, properties, set_property

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.core.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
get_construct(key, default=ValueError())[source]

Return a metadata construct.

Added in version (cfdm): 1.7.0

See also

constructs, del_construct, has_construct, set_construct

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(key, default=<class 'ValueError'>)[source]

Gets the keys of the axes spanned by a construct’s 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, has_data_axes, set_data_axes

Parameters:
key: str

Specify a metadata 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 keys of the domain axis constructs spanned by the data.

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
get_property(prop, default=ValueError())[source]

Return a property.

Added in version (cfdm): 1.7.0

See also

del_property, has_property, properties, set_property

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.core.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.core.Domain()
>>> f.has_bounds()
False
has_construct(key)[source]

Whether a metadata construct exists.

Added in version (cfdm): 1.7.0

See also

constructs, del_construct, get_construct, set_construct

Parameters:
key: str

The identifier of the metadata construct.

Parameter example:

key='auxiliarycoordinate0'

Returns:
bool

True if the construct exists, otherwise False.

Examples

>>> f.has_construct('dimensioncoordinate1')
True

>>> f.has_construct('dimensioncoordinate99')
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.core.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

See also

del_data_axes, get_data_axes, set_data_axes

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_property(prop)[source]

Whether a property has been set.

Added in version (cfdm): 1.7.0

See also

del_property, get_property, properties, set_property

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.core.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
properties()[source]

Return all properties.

Added in version (cfdm): 1.7.0

See also

clear_properties, get_property, has_property set_properties

Returns:
dict

The properties.

Examples

>>> f = cfdm.core.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

See also

constructs, del_construct, get_construct, set_data_axes

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_properties(properties, copy=True)[source]

Set properties.

Added in version (cfdm): 1.7.0

See also

clear_properties, properties, set_property

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.core.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

See also

del_property, get_property, has_property, properties, set_properties

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.core.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
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.core.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.core.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)>}