cfdm.Constructs.filter_by_identity

Constructs.filter_by_identity(*identities, todict=False, cached=None, _config={})[source]

Select metadata constructs by identity.

Calling a Constructs instance is an alias for filter_by_identity.

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

New in version (cfdm): 1.8.9.0

cached: optional

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

New in version (cfdm): 1.8.9.0

_config: optional

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

New 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')