cf.Constructs.filter_by_axis

Constructs.filter_by_axis(*axes, axis_mode='and', todict=False, cached=None)

Select metadata constructs by axes spanned by their data.

New in version (cfdm): 1.7.0

See also

filter, filters_applied, inverse_filter, clear_filters_applied, unfilter

Parameters

mode: str

Deprecated at version 1.8.9.0. Use the axis_mode parameter instead.

axes: optional

Select constructs that whose data spans the domain axis constructs specified by the given values. A value may be:

• A domain axis construct identifier, with or without the 'key%' prefix.

• The unique domain axis construct spanned by all of the 1-d coordinate constructs returned by, for a given value, c.filter(filter_by_type=["dimension_coordinate", "auxiliary_coordinate"], filter_by_naxes=(1,), filter_by_identity=(value,)). See filter for details.

• If there is an associated Field data array and a value matches the integer position of an array dimension, then the corresponding domain axis construct is specified.

• A unique domain axis construct identity, defined by its identities methods. In this case a value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

If no axes are provided then all constructs that do, or could have data, spanning any domain axes constructs, are selected.

axis_mode: str

Define the relationship between the given domain axes and the constructs’ data.

axis_mode	Description
'and'	A construct is selected if it spans all of the given domain axes, and possibly others.
'or'	A construct is selected if it spans any of the domain axes, and possibly others.
exact	A construct is selected if it spans all of the given domain axes, and no others.
subset	A construct is selected if it spans a subset of the given domain axes, and no others.

By default axis_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.

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

Returns

Constructs or dict or cached

The selected constructs, or a cached valued.

Examples

Select constructs whose data spans the “domainaxis1” domain axis construct:

>>> d = c.filter_by_axis('domainaxis1')

Select constructs whose data does not span the “domainaxis2” domain axis construct:

>>> d = c.filter_by_axis('domainaxis2').inverse_filter()

Select constructs whose data spans the “domainaxis1”, but not the “domainaxis2” domain axis constructs:

>>> d = c.filter_by_axis('domainaxis1')
>>> d = d.filter_by_axis('domainaxis2')
>>> d  = d.inverse_filter(1)

Select constructs whose data spans the “domainaxis1” or the “domainaxis2” domain axis constructs:

>>> d = c.filter_by_axis('domainaxis1', 'domainaxis2', axis_mode="or")