| Parameters: |
- items : optional
Select items whose properties or attributes satisfy the given
conditions.
items may be None, a string, a dictionary or a cf.Query
object; or a sequence of any of these:
- None or an empty dictionary. All items are
selected. This is the default.
A string which identifies items based on their
string-valued metadata. The value may take one of the
following forms:
| Value |
Interpretation |
|---|
| Contains ':' |
Selects on the CF property specified
before the first ':' |
| Contains '%' |
Selects on the attribute specified
before the first '%' |
| Anything else |
Selects on identity as returned by the
identity method |
By default the part of the string to be compared with the
item is treated as a regular expression understood by the
re module and an item is selected if its
appropriate value matches the regular expression using the
re.match method (i.e. if zero or more characters
at the beginning of item’s value match the regular
expression pattern). See the exact parameter for
details.
- Example:
To select items with standard names which begin “lat”:
items='lat'.
- Example:
To select items with long names which begin “air”:
items='long_name:air'.
- Example:
To select items with netCDF variable names which begin
“lon”: items='ncvar%lon'.
- Example:
To select items with identities which end with the
letter “z”: items='.*z$'.
- Example:
To select items with long names which start with the
string ”.*a”: items='long_name%\.\*a'.
A dictionary which identifies properties of the items with
corresponding tests on their values. An item is selected
if all of the tests in the dictionary are passed.
In general, each dictionary key is a CF property name with
a corresponding value to be compared against the item’s CF
property value.
If the dictionary value is a string then by default it is
treated as a regular expression understood by the
re module and an item is selected if its
appropriate value matches the regular expression using the
re.match method (i.e. if zero or more characters
at the beginning of item’s value match the regular
expression pattern). See the exact parameter for
details.
- Example:
To select items with standard name of exactly
“air_temperature” and long name beginning with the
letter “a”: items={'standard_name':
cf.eq('air_temperature'), 'long_name': 'a'} (see
cf.eq).
Some key/value pairs have a special interpretation:
| Special key |
Value |
|---|
| 'units' |
The value must be a string and by
default is evaluated for
equivalence, rather than equality,
with an item’s units property,
for example a value of 'Pa'
will match units of Pascals or
hectopascals, etc. See the exact
parameter. |
| 'calendar' |
The value must be a string and by
default is evaluated for
equivalence, rather than equality,
with an item’s calendar
property, for example a value of
'noleap' will match a calendar
of noleap or 365_day. See the
exact parameter. |
| None |
The value is interpreted as for a
string value of the items
parameter. For example,
items={None: 'air'} is
equivalent to items='air',
items={None: 'ncvar%pressure'}
is equivalent to
items='ncvar%pressure' and
items={None: 'Y'} is equivalent
to items='Y'. |
- Example:
To select items with standard name starting with
“air”, units of temperature and a netCDF variable name
of “tas” you could set
items={'standard_name': 'air', 'units': 'K', None:
'ncvar%tas$'}.
A domain item identifier (such as 'dim1', 'aux0',
'msr2', 'ref0', etc.). Selects the corresponding
item.
- Example:
To select the item with domain identifier “dim1”:
items='dim1'.
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', 'long_name': 'foo'}])
>>> y = {}
>>> for items in ['aux1', 'time', {'units': 'degreeN', 'long_name': 'foo'}]:
... 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 |
Items selected |
|---|
| 'd' |
Dimension coordinate objects |
| 'a' |
Auxiliary coordinate objects |
| 'm' |
Cell measure objects |
| 'r' |
Coordinate reference 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:
'am', 'ma', ('a', 'm'), ['m', 'a'],
set(['a', 'm']), 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,
exact=exact). See cf.Field.axes for details. The
strict_axes parameter modifies this behaviour.
- Example:
To select items which the time axes you could set:
axes='T'.
Note that more complex specifications of axes are possible,
since the axes parameter may take as its value any output
of the field’s axes method.
- Example:
To select items which span one dimensional time axes you
could set: axes=f.axes('T', ndim=1).
- ndim : optional
Select items whose number of data array axes satisfy the given
condition. Items are selected if they have ndim data aray
axes. A range of data numbers of array axes may be selected if
ndim is a cf.Query object.
- Example:
ndim=1 selects items which span exactly one axis and
ndim=cf.ge(2) selects items which span two or more
axes (see cf.ge).
- exact : bool, optional
The exact parameter applies to the interpretation of
string-valued conditions given by values of the items
parameter. By default exact is False, which means that:
- A string value is treated as a regular expression
understood by the re module.
- Units and calendar values in an items dictionary 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 which begins with
“air” and any units of pressure:
f.items({'standard_name': 'air', 'units': 'hPa'}).
If exact is True then:
- A string value is not treated as a regular expression.
- Units and calendar values in an items dictionary 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:
f.items({'standard_name': 'air_pressure', 'units':
'hPa'}, exact=True).
Note that cf.Query objects provide a mechanism for
overriding the exact parameter for individual values.
- Example:
f.items({'standard_name': cf.eq('air', exact=False),
'units': 'hPa'}, exact=True) will select items with a
standard name which begins “air” but with units of exactly
hectopascals (see cf.eq).
- Example:
f.items({'standard_name': cf.eq('air_pressure'),
'units': 'hPa'}) will select items with a standard name
of exactly “air_pressure” but with any units of pressure
(see cf.eq).
- match_and : bool, optional
By default match_and is True and then an item is selected if
it satisfies the conditions specified by each test parameter
(items, role, axes and ndim).
If match_and is False then an item is selected if it
satisfies at least one of the conditions specified by the test
parameters (items, role, axes and ndim).
- Example:
To select items with identity beginning with “ocean”
and at least 2 data array axes: f.items('ocean',
ndim=cf.ge(2)) (see cf.gt).
Example:
To select items with identity beginning with “ocean”
or at least 2 data array axes: f.items('ocean',
ndim=cf.ge(2), match_and=False)
- strict_axes : bool, optional
The strict_axes parameter applies to the interpretation of
axes parameter. 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.
- 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='mr').
|
|---|