cfdm.Constructs.filter

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

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