cfdm.constructs

Classes

Constructs([auxiliary_coordinate, ...])

A container for metadata constructs.

class cfdm.constructs.Constructs(auxiliary_coordinate=None, dimension_coordinate=None, domain_ancillary=None, field_ancillary=None, cell_measure=None, coordinate_reference=None, domain_axis=None, domain_topology=None, cell_connectivity=None, cell_method=None, source=None, copy=True, _use_data=True, _view=False, _ignore=())

Bases: Container, Constructs

A container for metadata constructs.

The container has similarities to a dict in that it presents the metadata constructs as key/value pairs, where the key is the unique identifier that corresponds to a metadata construct value; is indexable by metadata construct identifier; and provides a subset of the usual dictionary methods: get, items, keys, and values. The number of constructs (which may be zero) can be found via the Python len function. The container can be converted to an actual dict with the todict method.

Filtering

A subset of the metadata constructs can be defined and returned in a new Constructs instance by using the various filter methods. See filter for more details.

Calling

Calling a Constructs instance also creates a new Constructs instance that contains a subset of the metadata constructs, primarily selecting by construct identity. For instance, selecting constructs that have an identity of ‘latitude’ could be done by either x = c('latitude') or x = c.filter_by_identity('latitude'). More generally, c(*identities, **filter_kwargs) is equivalent to c.filter(filter_by_identity=identities, **filter_kwargs).

Metadata constructs

The following metadata constructs can be included:

• domain axis constructs

• dimension coordinate constructs

• auxiliary coordinate constructs

• coordinate reference constructs

• domain ancillary constructs

• cell measure constructs

• domain topology constructs

• cell connectivity constructs

• cell method constructs

• field ancillary constructs

Added in version (cfdm): 1.7.0

Initialisation

Parameters:

auxiliary_coordinate: str, optional

The base name for keys of auxiliary coordinate constructs.

Parameter example:

auxiliary_coordinate='auxiliarycoordinate'

dimension_coordinate: str, optional

The base name for keys of dimension coordinate constructs.

Parameter example:

dimension_coordinate='dimensioncoordinate'

domain_ancillary: str, optional

The base name for keys of domain ancillary constructs.

Parameter example:

domain_ancillary='domainancillary'

field_ancillary: str, optional

The base name for keys of field ancillary constructs.

Parameter example:

field_ancillary='fieldancillary'

cell_measure: str, optional

The base name for keys of cell measure constructs.

Parameter example:

cell_measure='cellmeasure'

coordinate_reference: str, optional

The base name for keys of coordinate reference constructs.

Parameter example:

coordinate_reference='coordinatereference'

domain_axis: str, optional

The base name for keys of domain axis constructs.

Parameter example:

domain_axis='domainaxis'

domain_topology: str, optional

The base name for keys of domain topology constructs.

Parameter example:

'domaintopology'

Added in version (cfdm): 1.11.0.0

cell_connectivity: str, optional

The base name for keys of cell connectivity constructs.

Parameter example:

'cellconnectivity'

Added in version (cfdm): 1.11.0.0

cell_method: str, optional

The base name for keys of cell method constructs.

Parameter example:

cell_method='cellmethod'

source: optional

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

All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the Constructs 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 Constructs instance then cfdm.Constructs(source=x) is equivalent to x.copy().

copy: bool, optional

If True (the default) then deep copy metadata constructs from those of source prior to initialisation, else they are not deep copied.

_ignore: sequence of str, optional

Ignores the given construct types.

Parameter example:

_ignore=('cell_method', 'field_ancillary')

clear_filters_applied()

Remove the history of filters that have been applied.

This method does not change the metadata constructs, it just forgets the history of any filters that have previously been applied. Use inverse_filter or unfilter retrieve previously filtered constructs.

The removed history is returned in a tuple. The last element of the tuple describes the last filter applied. Each element is a single-entry dictionary whose key is the name of the filter method that was used, with a value that gives the arguments that were passed to the call of that method. If no filters have been applied then the tuple is empty.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, unfilter

Returns:

tuple

The removed history of filters that have been applied, ordered from first to last. If no filters have been applied then the tuple is empty.

Examples

>>> c.filters_applied()
({'filter_by_naxes': (3, 1)},
 {'filter_by_identity': ('grid_longitude',)})
>>> c.clear_filters_applied()
({'filter_by_naxes': (3, 1)},
 {'filter_by_identity': ('grid_longitude',)})
>>> c.filters_applied()
()

construct_type(key)

Return the type of a construct for a given key.

Added in version (cfdm): 1.7.0

See also

construct_types

Parameters:

key: str

A construct identifier.

Returns:

str or None

The construct type, or None if the key is not present.

construct_types()

Return all of the construct types for all keys.

Added in version (cfdm): 1.7.0

See also

construct_type

copy(data=True)

Return a deep copy.

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

Added in version (cfdm): 1.7.0

Parameters:

data: bool, optional

If True (the default) then copy data contained in the metadata constructs.

Returns:

Constructs

The deep copy.

Examples

>>> g = f.copy()
>>> g = f.copy(data=False)

data_axes()

Returns the axes spanned by the data.

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

Added in version (cfdm): 1.7.0

Returns:

dict

The keys of the domain axes constructs spanned by metadata construct data.

Examples

>>> f = cfdm.example_field(0)
>>> c = f.constructs
>>> print(c)
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)>}
>>> c.data_axes()
{'dimensioncoordinate0': ('domainaxis0',),
 'dimensioncoordinate1': ('domainaxis1',),
 'dimensioncoordinate2': ('domainaxis2',)}

domain_axes(*identities, **filter_kwargs)

Return domain axis constructs.

Added in version (cfdm): 1.8.9.0

See also

constructs

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, c.filter(filter_by_type=["dimension_coordinate", "auxiliary_coordinate"], filter_by_naxes=(1,), filter_by_identity=(value,)) returns 1-d coordinate constructs that all span the same domain axis construct then that domain axis construct is selected. See filter 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 ~re.Pattern.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)

Return the canonical identity for a domain axis construct.

The identity is the first found of the following:

1. The canonical identity of a dimension coordinate construct that span the domain axis construct.

2. The identity of a one-dimensional auxiliary coordinate construct that spans the domain axis construct. This will either be the value of a standard_name, cf_role (preceded by 'cf_role=') or axis (preceded by 'axis=') property, as appropriate.

3. The netCDF dimension name, preceded by ‘ncdim%’.

4. The domain axis construct key, preceded by ‘key%’.

Parameters:

key: str

The construct key for the domain axis construct.

Parameter example:

key='domainaxis2'

Returns:

str

The identity.

Examples

>>> c.domain_axis_identity('domainaxis1')
'longitude'
>>> c.domain_axis_identity('domainaxis2')
'axis=Y'
>>> c.domain_axis_identity('domainaxis3')
'cf_role=timeseries_id'
>>> c.domain_axis_identity('domainaxis4')
'key%domainaxis4')

equals(other, rtol=None, atol=None, verbose=None, ignore_data_type=False, ignore_fill_value=False, ignore_compression=True, _ignore_type=False, _return_axis_map=False)

Whether two Constructs instances are the same.

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 equality is only possible with another Constructs construct, or a subclass of one.

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 the _FillValue and missing_value properties are omitted from the comparison for the metadata constructs.

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 the arrays in their uncompressed forms are compared.

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 instances are equal.

Examples

>>> x.equals(x)
True
>>> x.equals(x.copy())
True
>>> x.equals('something else')
False

filter(axis_mode='and', property_mode='and', todict=False, cached=None, _identity_config={}, **filters)

Select metadata constructs by a chain of filters.

This method allows multiple filters defined by the “filter_by_*” methods to be chained in an alternative manner to calling the individual methods in sequence.

For instance, to select the domain axis constructs with size 73 or 96

>>> c2 = c.filter(filter_by_type=['domain_axis'],
...               filter_by_size=[73, 96])

is equivalent to

>>> c2 = c.filter_by_type('domain_axis')
>>> c2 = c2.filter_by_size(73, 96)

When the results are requested as a dictionary as opposed to a Constructs object (see the todict parameter), using the filter method to call two or more filters is faster than calling the individual methods in sequence. For instance

>>> d = c.filter(filter_by_type=['dimension_coordinate'],
...              filter_by_identity=['time'],
...              todict=True)

is equivalent to, but faster than

>>> c2 = c.filter_by_type('dimension_coordinate')
>>> d = c2.filter_by_identity('time', todict=True)

Added in version (cfdm): 1.8.9.0

See also

filter_by_axis, filter_by_cell, filter_by_connectivity, filter_by_data, filter_by_identity, filter_by_key, filter_by_measure, filter_by_method, filter_by_identity, filter_by_naxes, filter_by_ncdim, filter_by_ncvar, filter_by_property, filter_by_type, filters_applied, inverse_filter, unfilter, clear_filters_applied

Parameters:

filters: optional

Keyword arguments defining the filters to apply. Each filter keyword defines a filter method, and its value provides the arguments for that method.

For instance, filter_by_type=['domain_axis'] will cause the filter_by_type method to be called with positional arguments *['domain_axis'].

The filters are applied in the same order that the keyword arguments appear.

Valid keywords and their values are:

Keyword	Value
filter_by_axis	A sequence as expected by the axes parameter of filter_by_axis
filter_by_cell	A sequence as expected by the cells parameter of filter_by_cell
filter_by_connectivity	A sequence as expected by the connectivity parameter of filter_by_connectivities
filter_by_data	Any value is allowed which will be ignored, as filter_by_data does not have any positional arguments.
filter_by_identity	A sequence as expected by the identities parameter of filter_by_identity
filter_by_key	A sequence as expected by the keys parameter of filter_by_key
filter_by_measure	A sequence as expected by the measures parameter of filter_by_measure
filter_by_method	A sequence as expected by the methods parameter of filter_by_method
filter_by_naxes	A sequence as expected by the naxes parameter of filter_by_naxes
filter_by_ncdim	A sequence as expected by the ncdims parameter of filter_by_ncdim
filter_by_ncvar	A sequence as expected by the ncvars parameter of filter_by_ncvar
filter_by_property	A dictionary as expected by the properties parameter of filter_by_property
filter_by_size	A sequence as expected by the sizes parameter of filter_by_size
filter_by_type	A sequence as expected by the types parameter of filter_by_type

axis_mode: str, optional

Provide a value for the axis_mode parameter of the filter_by_axis method. By default axis_mode is 'and'.

property_mode: str, optional

Provide a value for the property_mode parameter of the filter_by_property method. By default property_mode is 'and'.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

cached: optional

If any value other than None then return cached without selecting any constructs.

_identity_config: optional

Provide a value for the _config parameter of the filter_by_identity method.

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

filter_by_axis(*axes, axis_mode='and', todict=False, cached=None)

Select metadata constructs by axes spanned by their data.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

mode: str

Deprecated at version 1.8.9.0. Use the axis_mode parameter instead.

axes: optional

Select constructs that whose data spans the domain axis constructs specified by the given values. A value may be:

• A domain axis construct identifier, with or without the 'key%' prefix.

• The unique domain axis construct spanned by all of the 1-d coordinate constructs returned by, for a given value, c.filter(filter_by_type=["dimension_coordinate", "auxiliary_coordinate"], filter_by_naxes=(1,), filter_by_identity=(value,)). See filter for details.

• 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 specified.

• A unique domain axis construct identity, defined by its !identities methods. In this case a value may be any object that can match via the == operator, or a re.Pattern object that matches via its ~re.Pattern.search method.

If no axes are provided then all constructs that do, or could have data, spanning any domain axes constructs, are selected.

axis_mode: str

Define the relationship between the given domain axes and the constructs’ data.

axis_mode	Description
'and'	A construct is selected if it spans all of the given domain axes, and possibly others.
'or'	A construct is selected if it spans any of the domain axes, and possibly others.
exact	A construct is selected if it spans all of the given domain axes, and no others.
subset	A construct is selected if it spans a subset of the given domain axes, and no others.

By default axis_mode is 'and'.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select constructs whose data spans the “domainaxis1” domain axis construct:

>>> d = c.filter_by_axis('domainaxis1')

Select constructs whose data does not span the “domainaxis2” domain axis construct:

>>> d = c.filter_by_axis('domainaxis2').inverse_filter()

Select constructs whose data spans the “domainaxis1”, but not the “domainaxis2” domain axis constructs:

>>> d = c.filter_by_axis('domainaxis1')
>>> d = d.filter_by_axis('domainaxis2')
>>> d  = d.inverse_filter(1)

Select constructs whose data spans the “domainaxis1” or the “domainaxis2” domain axis constructs:

>>> d = c.filter_by_axis('domainaxis1', 'domainaxis2', axis_mode="or")

filter_by_cell(*cells, todict=False, cached=None)

Select domain topology constructs by cell type.

Added in version (cfdm): 1.11.0.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

cells: optional

Select domain topology constructs that have a cell type, defined by their !get_cell methods, that matches any of the given values.

If no cell types 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 ~re.Pattern.search method.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

cached: optional

If any value other than None then return cached without selecting any constructs.

Returns:

Constructs or dict or cached

The selected domain topology constructs, or a cached valued.

Examples

>>> print(t.constructs.filter_by_type('domain_topology')
Constructs:
{'domaintopology0': <DomainTopology: cell:face>}

Select domain topology constructs that have a cell type of “face”:

>>> print(c.filter_by_cell('face')
Constructs:
{'domaintopology0': <DomainTopology: cell:face>}

Select domain topology constructs that have a cell type of ‘face’ or ‘edge’:

>>> print(c.filter_by_cell('face', 'edge')
Constructs:
{'domaintopology0': <DomainTopology: cell:face>}

Select domain topology constructs that have a cell type that ends with “e”:

>>> print(c.filter_by_cell(re.compile('e$')))
Constructs:
{'domaintopology0': <DomainTopology: cell:face>}

Select domain topology constructs that have a cell type of any value:

>>> print(c.filter_by_cell())
Constructs:
{'domaintopology0': <DomainTopology: cell:face>}

filter_by_connectivity(*connectivities, todict=False, cached=None)

Select cell connectivity constructs by connectivity type.

Added in version (cfdm): 1.11.0.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

connectivities: optional

Select cell connectivity constructs that have a connectivity type, defined by their !get_connectivity methods, that matches any of the given values.

If no connectivities 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 ~re.Pattern.search method.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

cached: optional

If any value other than None then return cached without selecting any constructs.

Returns:

Constructs or dict or cached

The selected cell connectivity constructs, or a cached value.

Examples

>>> print(t.constructs.filter_by_type('cell_connectivity')
Constructs:
{'cellconnectivity0': <CellConnectivity: connectivity:edge(13824) >,
 'cellconnectivity1': <CellConnectivity: connectivity:node(13824) >}

Select cell connectivity constructs that have a connectivity type of “edge”:

>>> print(c.filter_by_connectivity('edge')
Constructs:
{'cellconnectivity0': <CellConnectivity: connectivity:edge(13824) >,

Select cell connectivity constructs that have a connectivity type of ‘edge’ or ‘node’:

>>> print(c.filter_by_connectivity('edge', 'node')
Constructs:
{'cellconnectivity0': <CellConnectivity: connectivity:edge(13824) >,
 'cellconnectivity1': <CellConnectivity: connectivity:node(13824) >}

Select cell connectivity constructs that have a connectivity type that starts with “n”:

>>> print(c.filter_by_connectivity(re.compile('^n')))
Constructs:
{'cellconnectivity1': <CellConnectivity: connectivity:node(13824) >}

Select cell connectivity constructs that have a connectivity type of any value:

>>> print(c.filter_by_connectivity())
Constructs:
{'cellconnectivity0': <CellConnectivity: connectivity:edge(13824) >,
 'cellconnectivity1': <CellConnectivity: connectivity:node(13824) >}

filter_by_data(todict=False, cached=None)

Selects metadata constructs that could contain data.

Selection is not based on whether they actually have data, rather by whether the construct supports the inclusion of data. For example, constructs selected by this method will all have a !get_data method.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select constructs that could contain data:

>>> d = c.filter_by_data()

filter_by_identity(*identities, todict=False, cached=None, _config={})

Select metadata constructs by identity.

Calling a Constructs instance is an alias for filter_by_identity.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

identities: optional

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

• A metadata construct identity.

  A construct has a number of string-valued identities

  defined by its !identities method, and is selected if any of them match the identity parameter. identity may be a string that equals one of a construct’s identities; or a re.Pattern object that matches one of a construct’s identities via re.search.

  Note that in the output of a dump method or print call, a metadata construct is always described by one of its identities, and so this description may always be used as an identity value.

• The key of a metadata construct

Parameter example:

identity='latitude'

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its ~re.Pattern.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.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

_config: optional

Additional parameters for configuring the application of a construct’s identities method.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select constructs that have a standard_name property of ‘latitude’:

>>> d = c.filter_by_identity('latitude')

Select constructs that have a long_name property of ‘Height’:

>>> d = c.filter_by_identity('long_name=Height')

Select constructs that have a standard_name property of ‘latitude’ or a “foo” property of ‘bar’:

>>> d = c.filter_by_identity('latitude', 'foo=bar')

Select constructs that have a netCDF variable name of ‘time’:

>>> d = c.filter_by_identity('ncvar%time')

filter_by_key(*keys, todict=False, cached=None)

Select metadata constructs by key.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

key: optional

Select constructs that have a construct identifier (e.g. 'dimensioncoordinate1') that matches any of the given values.

If no keys 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 ~re.Pattern.search method.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select the construct with key ‘domainancillary0’:

>>> d = c.filter_by_key('domainancillary0')

Select the constructs with keys ‘dimensioncoordinate1’ or ‘fieldancillary0’:

>>> d = c.filter_by_key('dimensioncoordinate1', 'fieldancillary0')

filter_by_measure(*measures, todict=False, cached=None)

Select cell measure constructs by measure.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

measures: optional

Select cell measure constructs that have a measure, defined by their !get_measure methods, that matches any of the given values.

If no measures 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 ~re.Pattern.search method.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Constructs

The selected cell measure constructs and their construct keys.

Examples

>>> print(t.constructs.filter_by_type('measure'))
Constructs:
{'cellmeasure0': <CellMeasure: measure:area(9, 10) km2>,
 'cellmeasure1': <CellMeasure: measure:volume(3, 9, 10) m3>}

Select cell measure constructs that have a measure of ‘area’:

>>> print(c.filter_by_measure('area'))
Constructs:
{'cellmeasure0': <CellMeasure: measure:area(9, 10) km2>}

Select cell measure constructs that have a measure of ‘area’ or ‘volume’:

>>> print(c.filter_by_measure('area', 'volume'))
Constructs:
{'cellmeasure0': <CellMeasure: measure:area(9, 10) km2>,
 'cellmeasure1': <CellMeasure: measure:volume(3, 9, 10) m3>}

Select cell measure constructs that have a measure of start with the letter “a” or “v”:

>>> print(c.filter_by_measure(re.compile('^a|v')))
Constructs:
{'cellmeasure0': <CellMeasure: measure:area(9, 10) km2>,
 'cellmeasure1': <CellMeasure: measure:volume(3, 9, 10) m3>}

Select cell measure constructs that have a measure of any value:

>>> print(c.filer_by_measure())
Constructs:
{'cellmeasure0': <CellMeasure: measure:area(9, 10) km2>,
 'cellmeasure1': <CellMeasure: measure:volume(3, 9, 10) m3>}

filter_by_method(*methods, todict=False, cached=None)

Select cell method constructs by method.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

methods: optional

Select cell method constructs that have a method, defined by their !get_method methods, that matches any of the given values.

If no methods are provided then all cell method constructs are selected.

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

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

>>> print(c.constructs.filter_by_type('cell_method'))
Constructs:
{'cellmethod0': <CellMethod: domainaxis1: domainaxis2: mean where land (interval: 0.1 degrees)>,
 'cellmethod1': <CellMethod: domainaxis3: maximum>}

Select cell method constructs that have a method of ‘mean’:

>>> print(c.filter_by_method('mean'))
Constructs:
{'cellmethod0': <CellMethod: domainaxis1: domainaxis2: mean where land (interval: 0.1 degrees)>}

Select cell method constructs that have a method of ‘mean’ or ‘maximum’:

>>> print(c.filter_by_method('mean', 'maximum'))
Constructs:
{'cellmethod0': <CellMethod: domainaxis1: domainaxis2: mean where land (interval: 0.1 degrees)>,
 'cellmethod1': <CellMethod: domainaxis3: maximum>}

Select cell method constructs that have a method that contain the letter ‘x’:

>>> import re
>>> print(c.filter_by_method(re.compile('x')))
Constructs:
{'cellmethod1': <CellMethod: domainaxis3: maximum>}

Select cell method constructs that have a method of any value:

>>> print(c.filter_by_method())
Constructs:
{'cellmethod0': <CellMethod: domainaxis1: domainaxis2: mean where land (interval: 0.1 degrees)>,
 'cellmethod1': <CellMethod: domainaxis3: maximum>}

filter_by_naxes(*naxes, todict=False, cached=None)

Selects constructs by the number of axes their data spans.

Specifically, selects metadata constructs by the number of domain axis constructs spanned by their data.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

naxes: optional

Select constructs that have data whose number of dimensions matches any of the given values.

If no values are provided then all constructs that do or could have data, spanning any domain axes constructs, are selected.

A value may be any object that can match an integer via ==.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select constructs that contain data that spans two domain axis constructs:

>>> d = c.filter_by_naxes(2)

Select constructs that contain data that spans one or two domain axis constructs:

>>> d = c.filter_by_ncdim(1, 2)

filter_by_ncdim(*ncdims, todict=False, cached=None)

Select domain axis constructs by netCDF dimension name.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

ncdims: optional

Select constructs that have a netCDF dimension name, defined by their !nc_get_dimension methods, that match any of the given values.

If no netCDF dimension names are provided then all constructs that do or could have a netCDF dimension name are selected.

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

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select the domain axis constructs with netCDF dimension name ‘time’:

>>> d = c.filter_by_ncdim('time')

Select the domain axis constructs with netCDF dimension name ‘time’ or ‘lat’:

>>> d = c.filter_by_ncdim('time', 'lat')

filter_by_ncvar(*ncvars, todict=False, cached=None)

Select domain axis constructs by netCDF variable name.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

ncvars: optional

Select constructs that have a netCDF variable name, defined by their !nc_get_variable methods, that match any of the given values.

If no netCDF variable names are provided then all constructs that do or could have a netCDF variable name are selected.

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

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select the constructs with netCDF variable name ‘time’:

>>> d = c.filter_by_ncvar('time')

Select the constructs with netCDF variable name ‘time’ or ‘lat’:

>>> d = c.filter_by_ncvar('time', 'lat')

filter_by_property(*property_mode, **properties)

Select metadata constructs by property.

Unlike the other “filter_by_” methods, this method has no todict or cached parameters. To get the results as a dictionary, use the todict method on the result, or for faster performance use the filter method. For instance, to get a dictionary of all constructs with a long_name of 'time' you could do c.filter_by_property(long_name="time").todict(), or the faster d = c.filter(filter_by_property={"long_name": "time"}, todict=True). To return a cached result, you have to use the filter method: c.filter(filter_by_property={"long_name": "time"}, cached=x).

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

property_mode: optional

Define the behaviour when multiple properties are provided:

property_mode	Description
'and'	A construct is selected if it matches all of the given properties.
'or'	A construct is selected when at least one of its properties matches.

By default property_mode is 'and'.

properties: optional

Select constructs that have a CF property, defined by their !properties methods, that matches any of the given values.

A property names and their given values are specified by keyword argument names and values.

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

The special value of None selects any construct that has that property, regardless of the construct’s property value.

If no properties are provided then all constructs that do or could have CF properties, with any values, are selected.

Returns:

Constructs

The selected constructs.

Examples

Select constructs that have a standard_name of ‘latitude’:

>>> d = c.filter_by_property(standard_name='latitude')

Select constructs that have a long_name of ‘height’ and units of ‘m’:

>>> d = c.filter_by_property(long_name='height', units='m')

Select constructs that have a long_name of ‘height’ or a foo of ‘bar’:

>>> d = c.filter_by_property('or', long_name='height', foo='bar')

Select constructs that have a standard_name which contains start with the string ‘air’:

>>> import re
>>> d = c.filter_by_property(standard_name=re.compile('^air'))

filter_by_size(*sizes, todict=False, cached=None)

Select domain axis constructs by size.

Added in version (cfdm): 1.7.3

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

sizes: optional

Select domain axis constructs that have sizes, defined by their !get_size methods, that match any of the given values.

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

A value may be any object that can match an integer via ==.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select domain axis constructs that have a size of 1:

>>> d = c.filter_by_size(1)

Select domain axis constructs that have a size of 1 or 96:

>>> d = c.filter_by_size(1, 96)

filter_by_type(*types, todict=False, cached=None)

Select metadata constructs by type.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters:

types: optional

Select constructs that have are of any of the given types.

A type is specified by one of the following strings:

type	Construct selected
'domain_ancillary'	Domain ancillary constructs
'dimension_coordinate'	Dimension coordinate constructs
'domain_axis'	Domain axis constructs
'auxiliary_coordinate'	Auxiliary coordinate constructs
'cell_measure'	Cell measure constructs
'coordinate_reference'	Coordinate reference constructs
'domain_topology'	Domain topology constructs
'cell_connectivity'	Cell connectivity constructs
'cell_method'	Cell method constructs
'field_ancillary'	Field ancillary constructs

If no types are provided then all constructs are selected.

todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

Added in version (cfdm): 1.8.9.0

cached: optional

If any value other than None then return cached without selecting any constructs.

Added in version (cfdm): 1.8.9.0

Returns:

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select dimension coordinate constructs:

>>> d = c.filter_by_type('dimension_coordinate')

Select dimension coordinate and field ancillary constructs:

>>> d = c.filter_by_type('dimension_coordinate', 'field_ancillary')

filters_applied()

A history of filters that have been applied.

The history is returned in a tuple. The last element of the tuple describes the last filter applied. Each element is a single-entry dictionary whose key is the name of the filter method that was used, with a value that gives the arguments that were passed to the call of that method. If no filters have been applied then the tuple is empty.

Added in version (cfdm): 1.7.0

See also

filter, inverse_filter, clear_filters_applied, unfilter

Returns:

tuple

The history of filters that have been applied, ordered from first to last. If no filters have been applied then the tuple is empty.

Examples

>>> print(c)
{'auxiliarycoordinate0': <AuxiliaryCoordinate: latitude(10, 9) degrees_N>,
 'auxiliarycoordinate1': <AuxiliaryCoordinate: longitude(9, 10) degrees_E>,
 'coordinatereference1': <CoordinateReference: grid_mapping_name:rotated_latitude_longitude>,
 'dimensioncoordinate1': <DimensionCoordinate: grid_latitude(10) degrees>,
 'dimensioncoordinate2': <DimensionCoordinate: grid_longitude(9) degrees>,
 'domainaxis1': <DomainAxis: size(10)>,
 'domainaxis2': <DomainAxis: size(9)>}
>>> c.filters_applied()
()
>>> c = c.filter_by_type('dimension_coordinate', 'auxiliary_coordinate')
>>> c.filters_applied()
({'filter_by_type': ('dimension_coordinate', 'auxiliary_coordinate')},)
>>> c = c.filter_by_property(units='degrees')
>>> c.filters_applied()
({'filter_by_type': ('dimension_coordinate', 'auxiliary_coordinate')},
 {'filter_by_property': ((), {'units': 'degrees'})})
>>> c = c.filter_by_property('or', standard_name='grid_latitude', axis='Y')
>>> c.filters_applied()
({'filter_by_type': ('dimension_coordinate', 'auxiliary_coordinate')},
 {'filter_by_property': ((), {'units': 'degrees'})},
 {'filter_by_property': (('or',), {'axis': 'Y', 'standard_name': 'grid_latitude'})})
>>> print(c)
Constructs:
{'dimensioncoordinate1': <DimensionCoordinate: grid_latitude(10) degrees>}

get(key, default=None)

Returns the construct for the key, else default.

Added in version (cfdm): 1.7.0

See also

items, keys, values

get_data_axes(key, default=ValueError())

Return 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.8.9.0

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.

inverse_filter(depth=None)

Return the inverse of previous filters.

By default, the inverse comprises all of the constructs that were not selected by all previously applied filters. If no filters have been applied, then this will result in empty Constructs instance being returned.

If the depth parameter is set to N then the inverse is relative to the constructs selected by the N-th most recently applied filter.

A history of the filters that have been applied is returned in a tuple by the filters_applied method. The last element of the tuple describes the last filter applied. If no filters have been applied then the tuple is empty.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, clear_filters_applied, unfilter

Parameters:

depth: int, optional

If set to N then the inverse is relative to the constructs selected by the N-th most recently applied filter. By default the inverse is relative to the constructs selected by all previously applied filters. N may be larger than the total number of filters applied, which results in the default behaviour.

Returns:

Constructs

The constructs, and their construct keys, that were not selected by the last filter applied. If no filtering has been applied, or the last filter was an inverse filter, then an empty Constructs instance is returned.

Examples

>>> print(c)
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)>}
>>> print(c.inverse_filter())
Constructs:
{}
>>> d = c.filter_by_type('dimension_coordinate', 'cell_method')
>>> print(d)
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 >}
>>> print(d.inverse_filter())
Constructs:
{'domainaxis0': <DomainAxis: size(5)>,
 'domainaxis1': <DomainAxis: size(8)>,
 'domainaxis2': <DomainAxis: size(1)>}
>>> e = d.filter_by_method('mean')
>>> print(e)
Constructs:
{'cellmethod0': <CellMethod: area: mean>}
>>> print(e.inverse_filter(1))
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: time(1) days since 2018-12-01 >}
>>> print(e.inverse_filter())
Constructs:
{'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)>}
>>> print(e.inverse_filter(1).inverse_filter())
Constructs:
{'cellmethod0': <CellMethod: area: mean>,
 'domainaxis0': <DomainAxis: size(5)>,
 'domainaxis1': <DomainAxis: size(8)>,
 'domainaxis2': <DomainAxis: size(1)>}

items()

Return the items as (construct key, construct) pairs.

Added in version (cfdm): 1.7.0

See also

get, keys, values

Returns:

dict_items

The construct key and constructs respectively as key-value pairs in a Python dict_items iterator.

Examples

>>> f = cfdm.example_field(0)
>>> c = f.constructs
>>> c_items = c.items()
>>> print(c_items)
dict_items([('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)>),
            ('cellmethod0', <CellMethod: area: mean>)])
>>> type(c_items)
<class 'dict_items'>
>>> dict(c_items)
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: time(1) days since 2018-12-01 >,
 'cellmethod0': <CellMethod: area: mean>,
 'domainaxis0': <DomainAxis: size(5)>,
 'domainaxis1': <DomainAxis: size(8)>,
 'domainaxis2': <DomainAxis: size(1)>}

key(default=ValueError())

Return the construct key of the sole metadata construct.

Added in version (cfdm): 1.7.0

See also

get, keys, value

Parameters:

default: optional

Return the value of the default parameter if there is not exactly one construct.

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

Returns:

str

The construct key.

Examples

>>> f = cfdm.Field()
>>> c = f.constructs
>>> d = cfdm.DimensionCoordinate(
...     properties={
...         'standard_name': 'latitude', 'units': 'degrees_north'},
...     data=cfdm.Data(range(5))
... )
>>> c._set_construct(d)
'dimensioncoordinate0'
>>> print(c)
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>}
>>> c.key()
'dimensioncoordinate0'
>>> c.value()
<DimensionCoordinate: latitude(5) degrees_north>

keys()

Return all of the construct keys, in arbitrary order.

Added in version (cfdm): 1.7.0

See also

get, items, values

Returns:

dict_keys

The construct keys as a Python dict_keys iterator.

Examples

>>> f = cfdm.example_field(0)
>>> c = f.constructs
>>> c_keys = c.keys()
>>> print(c_keys)
dict_keys(['domainaxis0',
           'domainaxis1',
           'domainaxis2',
           'dimensioncoordinate0',
           'dimensioncoordinate1',
           'dimensioncoordinate2',
           'cellmethod0'])
>>> type(c_keys)
<class 'dict_keys'>
>>> list(c_keys)
['domainaxis0',
 'domainaxis1',
 'domainaxis2',
 'dimensioncoordinate0',
 'dimensioncoordinate1',
 'dimensioncoordinate2',
 'cellmethod0']

new_identifier(construct_type)

Return a new, unused construct key.

Added in version (cfdm): 1.7.0

Parameters:

construct_type: str

The construct type for which the identifier is being created.

Parameter example:

construct_type='dimension_coordinate'

Returns:

str

The new construct identifier.

Examples

>>> f = cfdm.example_field(0)
>>> c = f.constructs
>>> c.keys()
['domainaxis0',
 'domainaxis1',
 'domainaxis2',
 'dimensioncoordinate0',
 'dimensioncoordinate1',
 'dimensioncoordinate2',
 'cellmethod0']
>>> c.new_identifier('domain_axis')
'domainaxis3'
>>> c.new_identifier('cell_method')
'cellmethod1'

replace(key, construct, axes=None, copy=True)

Replace one metadata construct with another.

Note

No checks on the axes are done.

shallow_copy(_ignore=None)

Return a shallow copy.

f.shallow_copy() is equivalent to copy.copy(f).

Any in-place changes to the actual constructs of the copy will not be seen in the original Constructs object, and vice versa, but the copy is otherwise independent of its parent.

Added in version (cfdm): 1.7.0

Returns:

Constructs

The shallow copy.

Examples

>>> g = f.shallow_copy()

todict(copy=False)

Return a dictionary of the metadata constructs.

Added in version (cfdm): 1.8.9.0

Parameters:

copy: bool, optional

If True then deep copy the metadata construct values.

Returns:

dict

The dictionary representation, keyed by construct identifiers with metadata construct values.

unfilter(depth=None, copy=True)

Return the constructs that existed prior to previous filters.

By default, the unfiltered constructs are those that existed before all previously applied filters.

If the depth parameter is set to N then the unfiltered constructs are those that existed before the N-th most recently applied filter.

A history of the filters that have been applied is returned in a tuple by the filters_applied method. The last element of the tuple describes the last filter applied. If no filters have been applied then the tuple is empty.

Added in version (cfdm): 1.7.0

See also

filter, filters_applied, clear_filters_applied, inverse_filter

Parameters:

depth: int, optional

If set to N then return the constructs selected by the N-th most recently applied filter. By default the constructs from before all previously applied filters are returned. N may be larger than the total number of filters applied, which results in the default behaviour.

Returns:

Constructs

The constructs, and their construct keys, that existed before the last filter was applied. If no filters have been applied then all of the constructs are returned.

Examples

>>> print(c)
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)>}
>>> d = c.filter_by_type('dimension_coordinate', 'cell_method')
>>> print(d)
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 >}
>>> d.unfilter().equals(c)
True
>>> e = d.filter_by_method('mean')
>>> print(e)
Constructs:
{'cellmethod0': <CellMethod: area: mean>}
>>> c.unfilter().equals(c)
True
>>> c.unfilter(0).equals(c)
True
>>> e.unfilter().equals(c)
True
>>> e.unfilter(1).equals(d)
True
>>> e.unfilter(2).equals(c)
True

If no filters have been applied then the unfiltered constructs are unchanged:

>>> c.filters_applied()
()
>>> c.unfilter().equals(c)
True

value(default=ValueError())

Return the sole metadata construct.

Added in version (cfdm): 1.7.0

See also

get, key, values

Parameters:

default: optional

Return the value of the default parameter if there is not exactly one construct.

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

Returns:

The metadata construct.

Examples

>>> f = cfdm.Field()
>>> c = f.constructs
>>> d = cfdm.DimensionCoordinate(
...     properties={
...         'standard_name': 'latitude', 'units': 'degrees_north'},
...     data=cfdm.Data(range(5))
... )
>>> c._set_construct(d)
'dimensioncoordinate0'
>>> print(c)
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>}
>>> c.key()
'dimensioncoordinate0'
>>> c.value()
<DimensionCoordinate: latitude(5) degrees_north>

values()

Return all of the metadata constructs, in arbitrary order.

Added in version (cfdm): 1.7.0

See also

get, items, keys

Returns:

dict_values

The constructs as a Python dict_values iterator.

Examples

>>> f = cfdm.example_field(0)
>>> c = f.constructs
>>> c_values = c.values()
>>> print(c_values)
dict_values([<DimensionCoordinate: latitude(5) degrees_north>,
             <DimensionCoordinate: longitude(8) degrees_east>,
             <DimensionCoordinate: time(1) days since 2018-12-01 >,
             <DomainAxis: size(5)>,
             <DomainAxis: size(8)>,
             <DomainAxis: size(1)>,
             <CellMethod: area: mean>])
>>> type(c_values)
<class 'dict_values'>
>>> list(c_values)
[<DimensionCoordinate: latitude(5) degrees_north>,
 <DimensionCoordinate: longitude(8) degrees_east>,
 <DimensionCoordinate: time(1) days since 2018-12-01 >,
 <DomainAxis: size(5)>,
 <DomainAxis: size(8)>,
 <DomainAxis: size(1)>,
 <CellMethod: area: mean>]