| Parameters: |
- items : optional
Select items whose attributes or CF properties satisfy
the given conditions. The items parameter may be one, or a
sequence, of:
- 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
item’s identity method |
By default the part of the string to be compared with an
item is treated as a regular expression understood by the
re module and an item is selected if its
corresponding 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
corresponding 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. If the sequence is empty then no
items are selected.
- ndim : optional
Select the items whose number of data array dimensions
satisfy the given condition. 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).
- axes : optional
Select items whose data array spans at least one of the
specified axes, taken in any order, and possibly others. The
axes are those that would be selected by this call of the
field’s axes method: f.axes(axes) or, if
axes is a dictionary of parameters to the axes
method, f.axes(**axes). See cf.Field.axes for details.
- Example:
To select items which span a time axis, and possibly
others, you could set: axes='T'.
- Example:
To select items which span a latitude and/or longitude
axes, and possibly others, you could set: axes=['X',
'Y'].
- Example:
To specify axes with size 19 you could set axes={'size':
19}. To specify depth axes with size 40 or more, you
could set: axes={'axes': 'depth', 'size': cf.ge(40)}
(see cf.ge).
- axes_all : optional
Select items whose data arrays span all of the
specified axes, taken in any order, and no others. The axes
are those that would be selected by this call of the field’s
axes method: f.axes(axes_all) or, if
axes_all is a dictionary of parameters,
f.axes(**axes_all). See cf.Field.axes for details.
- Example:
To select items which span a time axis, and no others,
you could set: axes_all='T'.
- Example:
To select items which span latitude and longitude axes,
and no others, you could set: axes_all=['X', 'Y'].
- Example:
To specify axes with size 19 you could set
axes_all={'size': 19}. To specify depth axes with
size 40 or more, you could set: axes_all={'axes':
'depth', 'size': cf.ge(40)} (see cf.ge).
- axes_subset : optional
Select items whose data array spans all of the
specified axes, taken in any order, and possibly others. The
axes are those that would be selected by this call of the
field’s axes method: f.axes(axes_subset) or,
if axes_subset is a dictionary of parameters ,
f.axes(**axes_subset). See cf.Field.axes for details.
Example:
To select items which span a time axes, and possibly
others, you could set: axes_subset='T'.
Example:
To select items which span latitude and longitude
axes, and possibly others, you could set:
axes_subset=['X', 'Y'].
- Example:
To specify axes with size 19 you could set
axes_subset={'size': 19}. To specify depth axes with
size 40 or more, you could set: axes_subset={'axes':
'depth', 'size': cf.ge(40)} (see cf.ge).
- axes_superset : optional
Select items whose data arrays span a subset of the
specified axes, taken in any order, and no others. The axes
are those that would be selected by this call of the field’s
axes method: f.axes(axes_superset) or, if
axes_superset is a dictionary of parameters,
f.axes(**axes_superset). See cf.Field.axes for details.
- Example:
To select items which span a time axis, and no others, you
could set: axes_superset='T'.
- Example:
To select items which span latitude and/or longitude axes,
and no others, you could set: axes_superset=['X',
'Y'].
- Example:
To specify axes with size 19 you could set
axes_superset={'size': 19}. To specify depth axes with
size 40 or more, you could set: axes_superset={'axes':
'depth', 'size': cf.ge(40)} (see cf.ge).
- match_and : bool, optional
By default match_and is True and items are selected
if they satisfy the all of the specified conditions.
If match_and is False then items are selected if they
satisfy at least one of the specified conditions.
- Example:
To select items with identity beginning with “ocean”
and two data array axes: f.ref('ocean',
ndim=2).
- Example:
To select items with identity beginning with “ocean”
or two data array axes: f.ref('ocean', ndim=2,
match_and=False).
- exact : bool, optional
The exact parameter applies to the interpretation of
string-valued conditions given by the items parameter. By
default exact is False, which means that:
- A string-valued condition is treated as a regular
expression understood by the re module and an
item is selected if its corresponding 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).
- Units and calendar strings are evaluated for equivalence
rather then equality (e.g. 'metre' is equivalent to
'm' and to 'km').
- Example:
To select items with with any units of pressure:
f.ref('units:hPa'). To select items with a
standard name which begins with “air” and with any units
of pressure: f.ref({'standard_name': 'air', 'units':
'hPa'}).
If exact is True then:
- A string-valued condition is not treated as a regular
expression and an item is selected if its corresponding
value equals the string.
- Units and calendar strings are evaluated for exact equality
rather than equivalence (e.g. 'metre' is equal to
'm', but not to 'km').
- Example:
To select items with with units of hectopascals but not,
for example, Pascals: f.ref('units:hPa',
exact=True). To select items with a standard name of
exactly “air_pressure” and with units of exactly
hectopascals: f.ref({'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.ref({'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.ref({'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).
- inverse : bool, optional
If True then select items other than those selected by all
other criteria.
- key : bool, optional
If True then return the domain’s identifier for the selected
item, rather than the item itself.
- copy : bool, optional
If True then a returned item is a copy. By default it is not
copied.
|
|---|