# cfdm.Constructs.filter¶

Constructs.filter(axis_mode='and', property_mode='and', todict=False, cached=None, _identity_config={}, **filters)[source]

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)


New in version (cfdm): 1.8.9.0

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_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_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

filter_by_property

A dictionary as expected by the properties parameter of filter_by_property

filter_by_data

Any value is allowed which will be ignored, as filter_by_data does not have any positional arguments.

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.