cf.collapse

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

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’ dimensions, where the methods are defined exactly as for CF cell methods:

Method	Description	Options
min	Minima over the specified dimensions
max	Maxima over the specified dimensions
mid_range	Means of the minima and maxima over the specified dimensions
mean	Means over the specified dimensions	Weighted or unweighted
sum	Sums over the specified dimensions	Weighted or unweighted
standard_deviation	Standard deviations over the specified dimensions	Weighted or unweighted, biased or unbiased
variance	Variances over the specified dimensions	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 None or dict, optional

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

weights	Description
'equal'	Perform an unweighted collapse.
None	The same as 'equal'.
'infer'	Create weights based on cell measure values (if possible) or based on coordinate types and values (string-valued coordinates are weighted equally; a (rotated) latitude coordinate is weighted liniearly with the sine of its values and all other coordinates are weighted linearly).
dict	Provide weights for one or more combinations of one or more of the collapse dimensions. Unspecified dimensions are assumed to have equal weights. The weights used in the calculation are the outer product of those provided.

By default the 'infer' option is used. Note that specifying an empty dictionary is equivelent to 'equal'.

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')