iris.common.metadata
Provides the infrastructure to support the common metadata API.
In this module:
Metadata container for a AncillaryVariableMetadata
.
- class iris.common.metadata.AncillaryVariableMetadata(_cls, standard_name, long_name, var_name, units, attributes)[source]
Create new instance of AncillaryVariableMetadataNamedtuple(standard_name, long_name, var_name, units, attributes)
- __eq__(other)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
- Returns
Boolean.
- combine(other, lenient=None)[source]
Return a new metadata instance created by combining each of the associated metadata members.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance.
- count(value, /)
Return number of occurrences of value.
- difference(other, lenient=None)[source]
Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.
A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance of member differences or None.
- equal(other, lenient=None)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Boolean.
- classmethod from_metadata(other)
Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.
Non-common metadata members are set to
None
.Args:
- other (metadata):
A metadata instance of any type.
- Returns
New metadata instance.
- index(value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
- name(default=None, token=False)
Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
- classmethod token(name)
Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.
Args:
- name:
The string name to verify
- Returns
The provided name if valid, otherwise None.
- DEFAULT_NAME = 'unknown'
- attributes
Alias for field number 4
- long_name
Alias for field number 1
- standard_name
Alias for field number 0
- units
Alias for field number 3
- var_name
Alias for field number 2
Container for common metadata.
- class iris.common.metadata.BaseMetadata(_cls, standard_name, long_name, var_name, units, attributes)[source]
Create new instance of BaseMetadataNamedtuple(standard_name, long_name, var_name, units, attributes)
- __eq__(other)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
- Returns
Boolean.
- combine(other, lenient=None)[source]
Return a new metadata instance created by combining each of the associated metadata members.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance.
- count(value, /)
Return number of occurrences of value.
- difference(other, lenient=None)[source]
Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.
A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance of member differences or None.
- equal(other, lenient=None)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Boolean.
- classmethod from_metadata(other)[source]
Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.
Non-common metadata members are set to
None
.Args:
- other (metadata):
A metadata instance of any type.
- Returns
New metadata instance.
- index(value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
- name(default=None, token=False)[source]
Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
- classmethod token(name)[source]
Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.
Args:
- name:
The string name to verify
- Returns
The provided name if valid, otherwise None.
- DEFAULT_NAME = 'unknown'
- attributes
Alias for field number 4
- long_name
Alias for field number 1
- standard_name
Alias for field number 0
- units
Alias for field number 3
- var_name
Alias for field number 2
Metadata container for a CellMeasure
.
- class iris.common.metadata.CellMeasureMetadata(_cls, standard_name, long_name, var_name, units, attributes, measure)[source]
Create new instance of CellMeasureMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, measure)
- __eq__(other)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
- Returns
Boolean.
- combine(other, lenient=None)[source]
Return a new metadata instance created by combining each of the associated metadata members.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance.
- count(value, /)
Return number of occurrences of value.
- difference(other, lenient=None)[source]
Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.
A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance of member differences or None.
- equal(other, lenient=None)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Boolean.
- classmethod from_metadata(other)
Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.
Non-common metadata members are set to
None
.Args:
- other (metadata):
A metadata instance of any type.
- Returns
New metadata instance.
- index(value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
- name(default=None, token=False)
Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
- classmethod token(name)
Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.
Args:
- name:
The string name to verify
- Returns
The provided name if valid, otherwise None.
- DEFAULT_NAME = 'unknown'
- attributes
Alias for field number 4
- long_name
Alias for field number 1
- measure
Alias for field number 5
- standard_name
Alias for field number 0
- units
Alias for field number 3
- var_name
Alias for field number 2
Metadata container for a Coord
.
- class iris.common.metadata.CoordMetadata(_cls, standard_name, long_name, var_name, units, attributes, coord_system, climatological)[source]
Create new instance of CoordMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, coord_system, climatological)
- __eq__(other)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
- Returns
Boolean.
- combine(other, lenient=None)[source]
Return a new metadata instance created by combining each of the associated metadata members.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance.
- count(value, /)
Return number of occurrences of value.
- difference(other, lenient=None)[source]
Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.
A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance of member differences or None.
- equal(other, lenient=None)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Boolean.
- classmethod from_metadata(other)
Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.
Non-common metadata members are set to
None
.Args:
- other (metadata):
A metadata instance of any type.
- Returns
New metadata instance.
- index(value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
- name(default=None, token=False)
Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
- classmethod token(name)
Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.
Args:
- name:
The string name to verify
- Returns
The provided name if valid, otherwise None.
- DEFAULT_NAME = 'unknown'
- attributes
Alias for field number 4
- climatological
Alias for field number 6
- coord_system
Alias for field number 5
- long_name
Alias for field number 1
- standard_name
Alias for field number 0
- units
Alias for field number 3
- var_name
Alias for field number 2
Metadata container for a Cube
.
- class iris.common.metadata.CubeMetadata(_cls, standard_name, long_name, var_name, units, attributes, cell_methods)[source]
Create new instance of CubeMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, cell_methods)
- __eq__(other)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
- Returns
Boolean.
- combine(other, lenient=None)[source]
Return a new metadata instance created by combining each of the associated metadata members.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance.
- count(value, /)
Return number of occurrences of value.
- difference(other, lenient=None)[source]
Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.
A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance of member differences or None.
- equal(other, lenient=None)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Boolean.
- classmethod from_metadata(other)
Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.
Non-common metadata members are set to
None
.Args:
- other (metadata):
A metadata instance of any type.
- Returns
New metadata instance.
- index(value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
- name(default=None, token=False)[source]
Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
- classmethod token(name)
Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.
Args:
- name:
The string name to verify
- Returns
The provided name if valid, otherwise None.
- DEFAULT_NAME = 'unknown'
- attributes
Alias for field number 4
- cell_methods
Alias for field number 5
- long_name
Alias for field number 1
- standard_name
Alias for field number 0
- units
Alias for field number 3
- var_name
Alias for field number 2
Metadata container for a DimCoord
- class iris.common.metadata.DimCoordMetadata(_cls, standard_name, long_name, var_name, units, attributes, coord_system, climatological, circular)[source]
Create new instance of DimCoordMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, coord_system, climatological, circular)
- __eq__(other)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
- Returns
Boolean.
- combine(other, lenient=None)[source]
Return a new metadata instance created by combining each of the associated metadata members.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance.
- count(value, /)
Return number of occurrences of value.
- difference(other, lenient=None)[source]
Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.
A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Metadata instance of member differences or None.
- equal(other, lenient=None)[source]
Determine whether the associated metadata members are equivalent.
Args:
- other (metadata):
A metadata instance of the same type.
Kwargs:
- lenient (boolean):
Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.
- Returns
Boolean.
- classmethod from_metadata(other)
Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.
Non-common metadata members are set to
None
.Args:
- other (metadata):
A metadata instance of any type.
- Returns
New metadata instance.
- index(value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
- name(default=None, token=False)
Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
- classmethod token(name)
Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.
Args:
- name:
The string name to verify
- Returns
The provided name if valid, otherwise None.
- DEFAULT_NAME = 'unknown'
- attributes
Alias for field number 4
- circular
Alias for field number 7
- climatological
Alias for field number 6
- coord_system
Alias for field number 5
- long_name
Alias for field number 1
- standard_name
Alias for field number 0
- units
Alias for field number 3
- var_name
Alias for field number 2
- iris.common.metadata.SERVICES
Convenience collection of lenient metadata services.
- iris.common.metadata.SERVICES_COMBINE
Built-in mutable sequence.
If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
- iris.common.metadata.SERVICES_DIFFERENCE
Convenience collection of lenient metadata difference services.
- iris.common.metadata.SERVICES_EQUAL
Convenience collection of lenient metadata equality services.
- iris.common.metadata.hexdigest(item)[source]
Calculate a hexidecimal string hash representation of the provided item.
Calculates a 64-bit non-cryptographic hash of the provided item, using the extremely fast
xxhash
hashing algorithm, and returns the hexdigest string representation of the hash.This provides a means to compare large and/or complex objects through simple string hexdigest comparison.
Args:
- item (object):
The item that requires to have its hexdigest calculated.
- Returns
The string hexidecimal representation of the item’s 64-bit hash.
- iris.common.metadata.metadata_filter(instances, item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None)[source]
Filter a collection of objects by their metadata to fit the given metadata criteria.
Criteria can be either specific properties or other objects with metadata to be matched.
Args:
- instances:
One or more objects to be filtered.
Kwargs:
- item:
Either,
a
standard_name
,long_name
, orvar_name
which is compared against thename()
.a coordinate or metadata instance equal to that of the desired objects e.g.,
DimCoord
orCoordMetadata
.
- standard_name:
The CF standard name of the desired object. If
None
, does not check forstandard_name
.
- long_name:
An unconstrained description of the object. If
None
, does not check forlong_name
.
- var_name:
The NetCDF variable name of the desired object. If
None
, does not check forvar_name
.
- attributes:
A dictionary of attributes desired on the object. If
None
, does not check forattributes
.
- axis:
The desired object’s axis, see
guess_coord_axis()
. IfNone
, does not check foraxis
. Accepts the valuesX
,Y
,Z
andT
(case-insensitive).
- Returns
A list of the objects supplied in the
instances
argument, limited to only those that matched the given criteria.
- iris.common.metadata.metadata_manager_factory(cls, **kwargs)[source]
A class instance factory function responsible for manufacturing metadata instances dynamically at runtime.
The factory instances returned by the factory are capable of managing their metadata state, which can be proxied by the owning container.
Args:
- cls:
A subclass of
BaseMetadata
, defining the metadata to be managed.
Kwargs:
- kwargs:
Initial values for the manufactured metadata instance. Unspecified fields will default to a value of ‘None’.
- Returns
A manager instance for the provided metadata
cls
.