| Parameters : |
- items : optional
Select items whose properties satisfy the given
conditions. The items argument may be one, or a sequence,
of:
- None or an empty dictionary. All items are
selected. This is the default.
- A domain item identifier (such as 'dim1', 'aux0',
'cm2', 'trans0', etc.). Selects the corresponding
item.
A string or cf.Comparison object. Selects items whose
identities, as returned by their identity methods,
match the value. 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 select items with an identity starting with
“grid” you could set items='grid'.
This case may be specified equivalently in a dictionary
with the special key of None.
Example: items='time' is equivalent to
items={None: 'time'}.
A dictionary which identifies properties of the items with
corresponding tests on their values. By default (see the
match_all argument) selects items which satisfy all of
the conditions. 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 each item’s
property 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 each item’s identity, as
returned by its identity method.
|
'units'
|
The value must be a string and, by
default, is evaluated for equivalence
with items’ units properties. See the
exact argument.
|
'calendar'
|
The value must be a string and, by
default, is evaluated for equivalence
with items’ calendar properties. See
the exact argument.
|
Example: To select items with a standard_name
starting with “air” and with units of temperature you
could set items={'standard_name': 'air', 'units':
'K'}.
If items is a sequence of any combination of the above then
the selected items are the union of those selected by each
element of the sequence.
Example:
>>> x = f.items(['aux1', 'time', {'units': 'degreeN'}, {'units': 'K'}])
>>> y = {}
>>> for items in ['aux1', 'time', {'units': 'degreeN'}, {'units': 'K'}]:
... y.update(f.items(items))
...
>>> set(x) == set(y)
True
If the sequence is empty then no items are selected.
- role : (sequence of) str, optional
Select items of the given roles. Valid roles are:
Role
|
Selected items
|
|---|
'a'
|
Auxiliary coordinate objects
|
'c'
|
Cell measure objects
|
'd'
|
Dimension coordinate objects
|
't'
|
Transform objects
|
Multiple roles may be specified by a multi-character string or
a sequence.
Example: Selecting auxiliary coordinate and cell measure
objects may be done with any of the following values of
role: 'ac', 'ca', ('a', 'c'), ['c', 'a'],
set(['a', 'c']), etc.
- ctype : (sequence of) str, optional
Select dimension and auxiliary coordinate object items of the
given CF types. Valid types, as defined by the CF conventions,
are:
Type
|
Selected items
|
|---|
'T'
|
Time coordinate objects
|
'X'
|
Longitude coordinate objects
|
'Y'
|
Latitude coordinate objects
|
'Z'
|
Vertical coordinate objects
|
Multiple types may be specified by a multi-character string or
a sequence.
Example: Selecting time and longitude coordinate objects may
be done with any of the following values of ctype:
'XT', 'TX', ('X', 'T'), ['X', 'T'],
set(['X', 'T']), etc.
- axes : optional
Select items which span at least one of the specified axes,
taken in any order (as well as possibly spanning other,
unspecified axes). The axes are those that would be selected
by this call of the field’s axes method:
f.axes(axes). See cf.Field.axes for details. The
strict_axes argument modifies this behaviour.
Note that more complex specifications of axes are possible,
since the axes argument may take as its value any output of
the field’s axes method.
Example: To specify the axes spanned by one dimensionsal CF
time coordinate objects you could set
axes=f.axes(ctype='T', rank=1).
- rank : int or cf.Comparison, optional
Select items whose ranks satisfy the given condition, where an
item’s rank is the number of axes which it spans. If rank is
an integer then only items with this rank are selected. Items
with a range of ranks may be selected if rank is a
cf.Comparison object.
Example: rank=1 selects items which span exactly one
axis and rank=cf.ge(2) selects items which span two or
more axes.
- exact : bool, optional
The exact argument applies to the interpretion of particular
conditions given by values of the items argument. 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 are evaluated for
equivalence rather then equality (e.g. 'metre' is
equivalent to 'm' and to 'km').
Example: To select items with a standard_name starting
with “air_pressure” and units of pressure you could set
items={'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 are evaluated for exact
equality rather than equivalence (e.g. 'metre' is
equal to 'm', but not to 'km').
Example: To select items with a standard_name of exactly
“air_pressure” and units of exactly hectopascals you
could set items={'standard_name': 'air_pressure', 'units':
'hPa'}, exact=True.
Note that cf.Comparison objects provide a mechanism for
overriding exact=False for individual values.
Example: items={None: cf.eq('grid_latitude'), 'units':
'degrees'} will select items with an identity of exactly
“grid_latitude” and any units equivalent to degrees.
- inverse : bool, optional
If True then select items other than those selected by all
other criteria.
Example: f.items(role='da', inverse=True) selects the
same items as f.items(role='ct').
- match_all : bool, optional
The match_all argument applies to the interpretion of
dictionaries given by the items argument. By default
match_all is True and items are selected if they satisfy all
of the conditions specified by a dictionary of the items
argmuent.
If match_all is False then items are selected if they
satisfy at least one of the specified by a dictionary of the
items argmuent.
Example: To select items with a standard_name containing
“temp” and/or units of temperature you could set
items={'standard_name': cf.eq('temp', regex=True),
'units': 'K'}, 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 and all strings given by values of
the items argument 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 select items with a long_name which starts
with “a” and ends with “z” you could set
items={'long_name': '^a.*z$'}, regex=True.
Note that cf.Comparison objects provide a mechanism for
overriding regex for individual values.
Example: items={'long_name': cf.eq('^a.*z$',
regex=True)} will select items a long_name which starts
with “a” and ends with “z” regardless of the value of
regex.
- strict_axes : bool, optional
The strict_axes argument applies to the interpretion of
axes argument. By default strict_axes is False and items
are selected which span at least one of the specified axes,
taken in any order (as well as possibly spanning other,
unspecified axes).
If strict_axes is True then items are selected which span
exactly all of the specified axes, taken in any order.
|
|---|