cfdm.Constructs.filter_by_property

Constructs.filter_by_property(*property_mode, **properties)[source]

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

New in version (cfdm): 1.7.0

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