cf.collapse

cf.collapse(fields, method, axes=None, weights=None, unbiased=False, ignore_size1=True, squeeze=False, **kwargs)

Return new fields with dimensions collapsed by statistical operations.

In all cases, the presence of missing data in an input field’s data array is accounted for during the collapse.

The following collapse methods are available over any subset of the fields’ axes, where the methods are defined exactly as for CF cell methods:

Method	Description	Options
min	Minima over the specified axes
max	Maxima over the specified axes
mid_range	Means of the minima and maxima over the specified axes
sum	Sums over the specified axes
mean	Means over the specified axes	Weighted or unweighted
standard_deviation	Standard deviations over the specified axes	Weighted or unweighted, biased or unbiased
variance	Variances over the specified axes	Weighted or unweighted, biased or unbiased

Parameters :

fields : (sequence of) Field or FieldList

The field or fields to be collapsed.

method : str or CellMethods

Define the collapse method (or methods). There are two ways of setting the collapse method:

• A string containing a single method (such as 'min').
  • The method is one of the available CF cell methods.
  • All of the dimensions specified by the axes parameter are collapsed simultaneously with this method.

• A CF cell methods-like string (such as 'time: max' or 'time: max dim0: mean 2: min') or a cf.CellMethods object equivalent to such a string.
  • Specifies both collapse methods and the axes to apply them to.
  • Each method is one of the available CF cell methods. The axes are interpreted as for the axes parameter.
  • When multiple cell methods are specified, each collapse is carried out independently and in the order that they are given. The axes parameter must not be set.

axes : (sequence of) int or str, optional

The axis or axes which are to be simultaneously collapsed with the method specified by the method parameter. May be any one, or any combination of:

• A dimension identity, as a defined by an appropriate coordinate’s identity method (such as 'time').
• The integer position of a dimension in the field’s data array (such as 2).
• The internal name of a dimension in the field’s domain (such as 'dim0').

By default all dimensions with size greater than 1 are collapsed, unless the method is a CF cell methods-like string or a cf.CellMethods object, in which case the collapse axes are already specified and the axes parameter must not be set.

weights : str or tuple, optional

Specify the weights to be used in the collapse. One of:

weights	Description
None	Perform an unweighted collapse (this is the default).
'equal'	Perform an unweighted collapse.
tuple	The axes for which non-equal weights are to be computed. Each axis is specified by one of: The identity of one of its one dimensional coordinate objects (such as 'time') A coordinate object type (one of 'T', 'X', 'Y' or 'Z') An axis or coordinate object domain identifier (such as 'dim1'). If cell measures are available for any specified axes then they will consitute the weights, otherwise weights are based on each axis’s dimension coordinate object. In general, dimension coordinate object weights will be linear, with the exception of a latitude axis, for which linear weights of the sine of the coordinate values are calculated. Example: To specify latitude/longitude area weights you could set weights=('X', 'Y'). If only coordinate object types are specified, then they may be given as a concatenated string instead of a tuple. Example: weights=('X', 'T') is equivalent to weights='XT'.

Note

The interface for the specification of weights is currently limited (version 0.9.8). A fully general API for specifiying weights is under development.

unbiased : bool, optional

If True then calculate unbiased statisics where applicable. By default biased statistics are calculated.

ignore_size1 : bool, optional

If False then raise a ValueError if a dimension to be collapsed has size 1, regardless of whether or not it spans the data array. By default size 1 collapse dimensions are ignored, regardless of whether or not they span the data array.

squeeze : bool, optional

If True then remove collapsed dimensions from the output data array. By default the output data array retains collapsed dimensions with size 1 if they were spanned by the original data array. It is not possible to remove collapsed dimensions when mutliple methods have been specified.

Returns :

out : Field or FieldList

The collapsed fields.

Examples

>>> g = cf.collapse(f, 'max')
>>> g = cf.collapse(f, 'min', axes=[2, 1])
>>> g = cf.collapse(f, 'sum', axes='dim2')
>>> g = cf.collapse(f, 'mid_range', axes=('latitude', 0, dim2'))
>>. g = cf.collapse(f, 'mean', axes='latitude', weights=None)
>>> g = cf.collapse(f, 'mean', axes='longitude', weights=None)
>>> g = cf.collapse(f, 'mean', axes=['longitude', 'latitude'], weights=None)
>>> g = cf.collapse(f, 'standard_deviation', weights=None)
>>> g = cf.collapse(f, 'variance', weights=None, unbiased=True)
>>> g = cf.collapse(f, 'mean', axes='latitude')
>>> g = cf.collapse(f, 'mean', axes='longitude')
>>> g = cf.collapse(f, 'mean', axes=['longitude', 'latitude'])
>>> g = cf.collapse(f, 'variance')
>>> g = cf.collapse(f, 'standard_deviation', unbiased=True)
>>> g = cf.collapse(f, 'longitude: mean latitude: max')

>>> weights = {'time': None,
...            (2, 'dim1'): numpy.arange(45).reshape(5, 9))
>>> g = cf.collapse(f, 'mean', weights=weights)