cf.Field.match_by_construct

Field.match_by_construct(*identities, OR=False, **conditions)

Whether or not there are particular metadata constructs.

Note

The API changed at version 3.1.0

New in version 3.0.0.

See also

match, match_by_property, match_by_rank, match_by_identity, match_by_ncvar, match_by_units

Parameters

identities: optional

Identify the metadata constructs that have any of the given identities or construct keys.

A construct identity is specified by a string (e.g. 'latitude', 'long_name=time', 'ncvar%lat', etc.); or a compiled regular expression (e.g. re.compile('^atmosphere')) that selects the relevant constructs whose identities match via re.search.

Each construct has a number of identities, and is selected if any of them match any of those provided. A construct’s identities are those returned by its identities method. In the following example, the construct x has six identities:

>>> x.identities()
['time',
 'long_name=Time',
 'foo=bar',
 'standard_name=time',
 'ncvar%t',
 'T']

A construct key may optionally have the 'key%' prefix. For example 'dimensioncoordinate2' and 'key%dimensioncoordinate2' are both acceptable keys.

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

If a cell method construct identity is given (such as 'method:mean') then it will only be compared with the most recently applied cell method operation.

Alternatively, one or more cell method constucts may be identified in a single string with a CF-netCDF cell methods-like syntax for describing both the collapse dimensions, the collapse method, and any cell method construct qualifiers. If N cell methods are described in this way then they will collectively identify the N most recently applied cell method operations. For example, 'T: maximum within years T: mean over years' will be compared with the most two most recently applied cell method operations.

Parameter example:

'measure:area'

Parameter example:

'latitude'

Parameter example:

'long_name=Longitude'

Parameter example:

'domainancillary2', 'ncvar%areacello'

conditions: optional

Identify the metadata constructs that have any of the given identities or construct keys, and whose data satisfy conditions.

A construct identity or construct key (as defined by the identities parameter) is given as a keyword name and a condition on its data is given as the keyword value.

The condition is satisfied if any of its data values equals the value provided.

Parameter example:

longitude=180.0

Parameter example:

time=cf.dt('1959-12-16')

Parameter example:

latitude=cf.ge(0)

Parameter example:

latitude=cf.ge(0), air_pressure=500

Parameter example:

**{'latitude': cf.ge(0), 'long_name=soil_level': 4}

OR: bool, optional

If True then return True if at least one metadata construct matches at least one of the criteria given by the identities or conditions arguments. By default True is only returned if the field constructs matches each of the given criteria.

mode: deprecated at version 3.1.0

Use the OR parameter instead.

constructs: deprecated at version 3.1.0

Returns

bool

Whether or not the field construct contains the specfied metadata constructs.

Examples:

TODO