cfdm.core.domain¶
Classes
|
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 thencfdm.core.Domain(source=x)
is equivalent tox.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.
- 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 tocopy.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
- 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())
- 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)>}