cf.CellMethods

class cf.CellMethods(string=None)

Bases: cf.utils.CfList

A CF cell methods object to describe the characteristic of a field that is represented by cell values.

Each cell method is stored in a dictionary and these dictionaries are stored in a list-like object. Similarly to a CF cell_methods string, the order of cell methods in the list is important.

The dictionary representing each cell method recognizes the following keys (where all keys are optional; the referenced sections are from the NetCDF Climate and Forecast (CF) Metadata Conventions and words in double quotes (”...”) refer to CF cell_methods components in the referenced sections):

Statistics for a combination of axes

The names of the dimensions involved in a combination of axes are given as a list (although their order is immaterial), with corresponding dimension identifiers:

>>> c
<CF CellMethods: latitude: longitude: mean>
>>> list(c)
[{'method'   : 'mean',
  'name'     : ['latitude', 'longitude'],     
  'dim'      : ['dim2, 'dim3']}]

If the string ‘area’ is used to indicate variation over horizontal area, then the corresponding dimension is None:

>>> c
<CF CellMethods: area: mean>
>>> list(c)
[{'method'   : 'mean',
  'name'     : ['area'],     
  'dim'      : [None]}]

Cell methods when there are no coordinates

These have name strings which are standard names or the string ‘area’, with corresponding dimension identifiers of None:

>>> c
<CF CellMethods: time: max>
>>> list(c)
[{'method'   : 'max',
  'name'     : ['time'],     
  'dim'      : [None]}]

>>> c
<CF CellMethods: lat: longitude: mean>
>>> list(c)
[{'method'   : 'mean',
  'name'     : ['lat', 'longitude','],     
  'dim'      : ['dim1', None]}]

>>> c
<CF CellMethods: area: mean>
>>> list(c)
[{'method'   : 'minimum',
  'name'     : ['area'],     
  'dim'      : [None]}]

In the case of ‘area’, there is no distinction between this cell method and one for which there appropriate dimensions exist, but the two cases may be discerned by inspection of the field’s space.

Initialization

Parameters :

string : str, optional

Initialize new instance from a CF-netCDF-like cell methods string. See the parse method for details. By default an empty cell methods is created.

Examples

>>> c = CellMethods()
>>> c = CellMethods('time: max: height: mean')

CellMethods methods (undocumented methods behave exactly as their counterparts in a built-in list)

append
copy	Return a deep copy.
count	Return the number of occurrences of a given value.
dump	Return a string containing a full description of the instance.
equals	True if two cell methods are equal, False otherwise.
extend
has_cellmethods	Return True if and only if this cell methods is a super set of another.
index	Return the first index of a given value.
insert	Insert an object before the given index in place.
netCDF_translation	Translate netCDF variable names.
parse	Parse a CF cell_methods string into this CellMethods instance in
pop
remove
reverse
strings	Return a list of a CF-netCDF-like string of each cell method.

copy()

Return a deep copy.

Equivalent to copy.deepcopy(s).

Returns :

out :

The deep copy.

Examples

>>> s.copy()

count(value)

Return the number of occurrences of a given value.

Uses numerically tolerant equality where appropriate.

Parameters :

value :

The value to count.

Returns :

out : int

The number of occurrences of value.

Examples

>>> s
[1, 2, 3, 2, 4, 2]
>>> s.count(1)
1
>>> s.count(2)
3

dump(id=None)

Return a string containing a full description of the instance.

If a cell methods ‘name’ is followed by a ‘*’ then that cell method is relevant to the data in a way which may not be precisely defined its corresponding dimension or dimensions.

Parameters :

id : str, optional

Set the common prefix of component names. By default the instance’s class name is used.

Returns :

out : str

A string containing the description.

Examples

>>> x = c.dump()
>>> print c.dump()
>>> print c.dump(id='cellmethods1')

equals(other, rtol=None, atol=None, traceback=False)

True if two cell methods are equal, False otherwise.

The dim attribute is ignored in the comparison.

Parameters :

other :

The object to compare for equality.

atol : float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the ATOL function is used.

rtol : float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the RTOL function is used.

traceback : bool, optional

If True then print a traceback highlighting where the two instances differ.

Returns :

out : bool

Whether or not the two instances are equal.

Examples

equivalent(other, rtol=None, atol=None)

True if two cell methods are equivalent, False otherwise.

The dim attribute is ignored in the comparison.

Parameters :

other :

The object to compare for equality.

atol : float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the ATOL function is used.

rtol : float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the RTOL function is used.

Returns :

out : bool

Whether or not the two instances are equivalent.

Examples

has_cellmethods(other)

Return True if and only if this cell methods is a super set of another.

Parameters :

other : CellMethods

The other cell methods for comparison.

Returns :

out : bool

Whether or not this cell methods is a super set of the other.

Examples

>>> c = cf.CellMethods('time: mean height: mean area: mean')
>>> d = cf.CellMethods('area: mean time: mean')
>>> c.has_cellmethods(d)
True

index(value, start=0, stop=None)

Return the first index of a given value.

Uses numerically tolerant equality where appropriate.

Parameters :

value :

The value to look for in the list.

start : int, optional

Start looking from this index. By default, look from the beginning of the list.

stop : int, optional

Stop looking before this index. By default, look up to the end of the list.

Returns :

out : int

Raises :

ValueError :

If the given value is not in the list.

Examples

>>> s
[1, 2, 3, 2, 4, 2]
>>> s.index(1)
1
>>> s.index(2, 2)
3
>>> s.index(2, start=2, stop=5)
3
>>> s.index(6)
ValueError: CfList doesn't contain: 6

insert(index, item)

Insert an object before the given index in place.

Parameters :

index : int

item :

Returns :

None

Examples

>>> s
[1, 2, 3]
>>> s.insert(1, 'A')
>>> s
[1, 'A', 2, 3]
>>> s.insert(100, 'B')
[1, 'A', 2, 3, 'B']
>>> s.insert(100, 'B')
[1, 'A', 2, 3, 'B']
>>> s.insert(-2, 'C')
[1, 'A', 2, 'C', 3, 'B']
>>> s.insert(-100, 'D')
['D', 1, 'A', 2, 'C', 3, 'B']

netCDF_translation(f)

Translate netCDF variable names.

Parameters :

f : Field

The field which provides the translation.

Returns :

out : CellMethods

A new cell methods instance with translated names.

Examples

>>> c = CellMethods('time: mean lon: mean')
>>> d = c.netCDF_translation(f)

parse(string=None)

Parse a CF cell_methods string into this CellMethods instance in place.

Parameters :

string : str, optional

The CF cell_methods string to be parsed into the CellMethods object. By default the cell methods will be empty.

Returns :

None

Examples

>>> c = cf.CellMethods()
>>> c = c.parse('time: minimum within years time: mean over years (ENSO years)')    
>>> print c
Cell methods    : time: minimum within years
                  time: mean over years (ENSO years)

strings()

Return a list of a CF-netCDF-like string of each cell method.

Note that if the intention is to concatenate the output list into a string for creating a CF-netCDF cell_methods attribute, then the cell methods “name” components may need to be modified, where appropriate, to reflect netCDF variable names.

Returns :

out : list

A string for each cell method.

Examples

>>> c = cf.CellMethods('time: minimum within years time: mean over years (ENSO years)')
>>> c.strings()
['time: minimum within years',
 'time: mean over years (ENSO years)']

string