cf.Field.match

Field.match(match={}, cvalue={}, csize={}, rank=None, exact=False, match_all=True, regex=False)

Test whether or not the field satisfies the given conditions.

Different types of conditions may be set with the keyword arguments:

Keyword	What gets tested
match	The field’s properties
cvalue	The field’s coordinate object array values
csize	The field’s coordinate object cell sizes
rank	The field’s domain rank

When multiple criteria are given, the field matches if it satisfies the conditions given by each one.

Quick start examples

There is great flexibility in the types of test which can be specified, and as a result the documentation is very detailed in places. These preliminary, simple examples show that the usage need not always be complicated and may help with understanding the keyword descriptions.

1. Test if a field contains air temperature data:

   >>> f.match('air_temperature')
   

2. Test if a field has at least one longitude grid cell point on the Greenwich meridian:

   >>> f.match(cvalue={'longitude': 0})
   

3. Test if a field has latitude grid cells which all have a resolution of less than 1 degree:

   >>> f.match(csize={'latitude': cf.lt(1, 'degree')})
   

4. Test if a field has exactly 4 domain axes:

   >>> f.match(rank=4)
   

5. Examples 1 to 4 may be combined to test if a field has exactly 4 domain axes, contains air temperature data, has at least one longitude grid cell point on the Greenwich meridian and all latitude grid cells have a resolution of less than 1 degree:

   >>> f.match('air_temperature',
   ...         cvalue={'longitude': 0},
   ...         csize={'latitude': cf.lt(1, 'degree')},
   ...         rank=4)
   

6. Test if a field contains monthly mean data array values:

   >>> f.match({'cell_methods': cf.CellMethods('time: mean')},
   ...         csize={'time': cf.wi(28, 31, 'days')})
   

Further examples are given within and after the description of the arguments.

Parameters :

match : optional

Set conditions on the field’s property values. By default (see the match_all argument) the field matches if, for each specified property, the field’s property value passes the given test. The match argument may be one of:

• None or an empty dictionary. Always matches the field. This is the default.

• A string or cf.Comparison object to be compared with field’s identity, as returned by its identity method. If it is a string then the usual rules for string comparisons apply (see the exact and regex arguments for details, e.g. by default a string value is tested for being an abbreviation).

  Example: to match a field with an identity starting with “ocean” you could set match='ocean'.

  This case may be specified equivalently in a dictionary with the special key of None.

  Example: match='cloud_area_fraction' is equivalent to match={None: 'cloud_area_fraction'}.

• A dictionary which identifies properties of the field with corresponding tests on their values. Each key/value pair is specified as follows:

  key:	An unabbreviated property name (such as 'long_name', 'units', 'foo', etc).
  value:	A condition to be tested against the field’s property value for, in general, equality. The exceptions are for string valued conditions (see the exact and regex arguments for details, e.g. by default a string value is tested for being an abbreviation) and for values of some special keys (see the following table).

  The dictionary keys whose values have special interpretations are:

  Special key	Value
  None	The value is compared (with the usual rules) against the field’s identity, as returned by its identity method.
  'units'	The value must be a string and, by default, is evaluated for equivalence with the field’s units property. See the exact argument.
  'calendar'	The value must be a string and, by default, is evaluated for equivalence with the field’s calendar property. See the exact argument.
  'cell_methods'	The value must be a cf.CellMethods object and, by default, is evaluated for being equivalent to a single cell method contained within the field’s cell_methods property. See the exact argument.

  Example: To match a field with a standard_name starting with the string “air” and with units of temperature you could set match={'standard_name': 'air', 'units': 'K'}.

cvalue : dict, optional

A dictionary which identifies coordinate objects of the field with corresponding tests on their data array values. By default (see the match_all argument) the field matches if, for each specified coordinate object, the field has such an item and at least one element of its data array passes the given test. Each key/value pair is specified as follows:

key:

A string or cf.Comparison object selecting a unique coordinate object by comparison with its identity, as returned by its identity method; or the coordinate object may be selected by its domain identifier (such as 'dim1', 'aux0', etc.). If it is a string representing a coordinate object identity then the usual rules for string comparisons apply (see the exact and regex arguments for details, e.g. by default a string value is tested for being an abbreviation). If it is a cf.Comparison object then it is tested for equality.

value:

In general, any object specifying a condition for the coordinate object’s data array to be tested against. The test is passed if at least one data array element equals the value. If the value is None then the test is always passed (i.e. this case tests for coordinate object existence).

Example: To match a field with a depth coordinate object which has at least one data array element between one and two kilometres you could set cvalue={'depth': cf.wi(1000, 2000, 'm')}.

csize : dict, optional

A dictionary which identifies coordinate objects of the field with corresponding tests on their cell sizes. By default (see the match_all argument) the field matches if, for each specified coordinate object, the field has such an item and all of its cell sizes pass the given test. However, if a coordinate object has also been specified with the cvalue argument then a match occurs if all of the cells meeting the cvalue conditions pass the cell size test. Each key/value pair is specified as follows:

key:

A string or cf.Comparison object selecting a unique coordinate object by comparison with its identity, as returned by its identity method; or the coordinate object may be selected by its domain identifier (such as 'dim1', 'aux0', etc.). If it is a string representing a coordinate object identity then the usual rules for string comparisons apply (see the exact and regex arguments for details, e.g. by default a string value is tested for being an abbreviation). If it is a cf.Comparison object then it is tested for equality.

value:

In general, any object specifying a condition for the coordinate object’s cell sizes to be tested against. The test is passed if at all of the cell sizes (or all those for data array elements which passed a test given by the cvalue argument) equal the value. If the value is None then the test is always passed (i.e. this case tests for coordinate object existence).

Example: To match a field whose latitude coordinate object cell sizes are all strictly less than 2 degrees you could set csize={'latitude': cf.lt(2, 'degrees')}. If this test were to be used in conjunction with cvalue={'latitude': cf.ge(0)} then it is less stringent, as the field would match if all of its northern hemisphere latitude coordinate object cell sizes were less than 2 degrees.

rank : int or cf.Comparison, optional

Specifiy a condition on the field’s domain rank, where the domain rank is the number of domain axes. The field matches if its number of domain axes equals rank.

Example: rank=2 matches a field with exactly two domain axes and rank=cf.wi(3, 4) matches a field with three or four domain axes.

exact : bool, optional

The exact argument applies to the interpretion of particular conditions given by values of the match argument and by keys of the cvalue and csize arguments. By default exact is False, which means that:

• If the regex argument is False (which is the default) then string values are considered to be arbitrary abbreviations.
• If the regex argument is True then string values are considered to be regular expressions, which are evaluated using the re.search function.
• units and calendar values in the match dictionary are evaluated for equivalence rather then equality (e.g. 'metre' is equivalent to 'm' and to 'km').
• A cell_methods value in the match dictionary is evaluated for equivalence as follows:
  • If it contains a single cell method then it is evaluated for being equivalent to a single cell method contained within the field’s cell methods.
  • If it contains two or more cell methods then it is evaluated for being equivalent to the field’s cell methods.

Example: To match a field with a standard_name starting with “air_pressure” and units of pressure you could set match={'standard_name': 'air_pressure', 'units': 'hPa'}, exact=False.

If exact is True then:

• All string values are considered to be unabbreviated and not to be regular expressions (even if the regex argument is True).
• units and calendar values in the match dictionary are evaluated for exact equality rather than equivalence (e.g. 'metre' is equal to 'm', but not to 'km').
• A cell_methods value in the match dictionary is evaluated for equivalence to the field’s cell methods.

Example: To match a field with a standard_name of exactly “air_pressure” and units of exactly hectopascals you could set match={'standard_name': 'air_pressure', 'units': 'hPa'}, exact=True.

Note that cf.Comparison objects provide a mechanism for overriding exact=False for individual values.

Example: match={'standard_name': cf.eq('air_pressure'), 'units': 'hPa'} will match a field with a standard_name of exactly “air_pressure” and any units of pressure.

match_all : bool, optional

By default match_all is True and the field matches if it satisfies all of the conditions specified by all of the test types (properties, coordinate object values, coordinate object cell sizes, domain rank and data array rank).

If match_all is False then the field will match if, for each test type, it satisfies at least one of the given conditions.

Example: To match a field with a standard_name containing “ocean” and/or units of density you could set match={'standard_name': cf.eq('ocean', regex=True), 'units': 'kg m-3'}, match_all=False. If match_all were True in this case then the field would match only if it satisfied both conditions.

regex : bool, optional

By default regex is False, which means that all strings given by values of the match argument and by keys of the cvalue and csize arguments are considered to be arbitrary abbreviations or else exact (see the exact argument).

If regex is True then such strings are considered to be regular expressions supported by the re module and are compared via the re.search function (see the exact argument).

Example: To match a field with a long_name which starts with “a” and ends with “z” you could set match={'long_name': '^a.*z$'}, regex=True.

Note that cf.Comparison objects provide a mechanism for overriding regex for individual values.

Example: match={'long_name': cf.eq('^a.*z$', regex=True)} will match a field with a long_name which starts with “a” and ends with “z” regardless of the value of regex.

Returns :

out : bool

True if the field satisfies the given criteria, False otherwise.

See also

items, select

Examples

Field identity starts with “air”:

>>> f.match('air')

Field identity ends with with “temperature”:

>>> f.match('temperature$', regex=True)

Field identity is exactly “air_temperature”:

>>> f.match('air_temperature', exact=True)

Field has units of temperature:

>>> f.match({'units': 'K'}):

Field has units of exactly Kelvin:

>>> f.match({'units': 'K'}, exact=True)

Field standard name starts with “air” and has units of temperature:

>>> f.match({'standard_name': 'air',
...          'units': 'K'})

Field standard name starts with “air” and/or has units of temperature:

>>> f.match({'standard_name': 'air',
...          'units': 'K'},
...         match_all=False)

Field standard name starts with “air” and/or has units of exactly Kelvin:

>>> f.match({'standard_name': cf.eq('^air', regex=True),
...          'units': 'K'},
...         exact=True,
...         match_all=False)

Field has a height coordinate object with some values greater than 63km:

>>> f.match(cvalue={'height': cf.gt(63, 'km')})

Field has a height coordinate object with some values greater than 63km and a north polar point on its horizontal grid:

>>> f.match(cvalue={'height': cf.gt(63, 'km'),
...                 'latitude': cf.eq(90, 'degrees')})

Field has a height coordinate object with some values greater then 63km and/or a north polar point on its horizontal grid

>>> f.match(cvalue={'height': cf.gt(63, 'km'),
...                 'latitude': cf.eq(90, 'degrees')},
...         match_all=False)

Field longitude cell sizes are all 3.75:

>>> f.match(csize={'longitude': 3.75})

Field latitude cell sizes within a tropical region are all no greater than 1 degree:

>>> f.match(cvalue={'latitude': cf.wi(-30, 30, 'degrees'),
...         csize={'latitude': cf.le(1, 'degrees')})

Field contains monthly mean air pressure data and all vertical levels within the bottom 100 metres of the atmosphere have a thickness of 20 metres or less:

>>> f.match({None: cf.eq('air_pressure'),
...          'cell_methods': cf.CellMethods('time: mean')},
...         cvalue={'height': cf.le(100, 'm')},
...         csize={'height': cf.le(20, 'm'),
...                'time': cf.wi(28, 31, 'days')})