cf.aggregate

cf.aggregate(fields, messages=False, no_strict_units=False, no_overlap=False, contiguous=False, _delete_meta=True, no_strict_identity=False, equal_all=False, equal_ignore=(), equal=(), exist_all=False, exist_ignore=(), exist=(), dimension=(), concatenate=True, copy=True, debug=0)

Aggregate fields into as few fields as possible.

The aggregation of fields may be thought of as the combination fields into each other to create a new field that occupies a larger domain.

Using the CF aggregation rules, input fields are separated into aggregatable groups and each group (which may contain just one field) is then aggregated to a single field. These aggregated fields are returned in a field list.

Parameters :

fields : (sequence of) Field or FieldList

The field or fields to aggregated.

messages : bool, optional

If True then print messages giving reasons why particular fields have not been aggregated.

no_overlap : bool, optional

If True then require that aggregated fields have adjacent dimension coordinate object cells which do not overlap (but they may share common boundary values). Ignored if the dimension coordinates objects do not have bounds. See the contiguous parameter.

contiguous : bool, optional

If True then require that aggregated fields have adjacent dimension coordinate object cells which partially overlap or share common boundary values. Ignored if the dimension coordinate objects do not have bounds. See the no_overlap parameter.

no_strict_units : bool, optional

If True then assume that fields or domain items (such as coordinate objects) with the same identity (as returned by their identity methods) but missing units all have equivalent but unspecified units, so that aggregation may occur. By default such fields are not aggregatable.

no_strict_identity : bool, optional

If True then treat fields with data arrays but with no identities (as returned by their identity methods) as having equal but unspecified identities, so that aggregation may occur. By default such fields are not aggregatable.

equal_all : bool, optional

If True then require that aggregated fields have the same set of non-standard CF properties (including long_name), with the same values. See the concatenate parameter.

equal_ignore : (sequence of) str, optional

Specify CF properties to omit from any properties specified by or implied by the equal_all and equal parameters.

equal : (sequence of) str, optional

Specify CF properties for which it is required that aggregated fields all contain the properties, with the same values. See the concatenate parameter.

exist_all : bool, optional

If True then require that aggregated fields have the same set of non-standard CF properties (including, in this case, long_name), but not requiring the values to be the same. See the concatenate parameter.

exist_ignore : (sequence of) str, optional

Specify CF properties to omit from the properties specified by or implied by the exist_all and exist parameters.

exist : (sequence of) str, optional

Specify CF properties for which it is required that aggregated fields all contain the properties, but not requiring the values to be the same. See the concatenate parameter.

dimension : (sequence of) str, optional

Create new axes for each input field which has one or more of the given properties. For each CF property name specified, if an input field has the property then, prior to aggregation, a new axis is created with an auxiliary coordinate whose datum is the property’s value and the property itself is deleted from that field.

concatenate : bool, optional

If False then a CF property is omitted from an aggregated field if the property has unequal values across constituent fields or is missing from at least one constituent field. By default a CF property in an aggregated field is the concatenated collection of the distinct values from the constituent fields, delimited with the string ' :AGGREGATED: '.

copy : bool, optional

If False then do not copy fields prior to aggregation. Setting this option to False may change input fields or field lists in place, and the returned fields may not equal the altered inputs. However, if the input variable is overwritten by the output field list (f = cf.aggregate(f)) then setting this option to False can improve performance.

debug : int, optional

Print debugging information for each input field. If 1 then print each field’s structural signature. If 2 the print the entire metadata summary for each field, which includes the structural signature. By default no debugging information is printed.

Returns :

out : FieldList

The aggregated fields.

Examples

The following six fields comprise eastward wind at two different times and for three different atmospheric heights for each time:

>>> f
[<CF Field: eastward_wind(latitude(73), longitude(96)>,
 <CF Field: eastward_wind(latitude(73), longitude(96)>,
 <CF Field: eastward_wind(latitude(73), longitude(96)>,
 <CF Field: eastward_wind(latitude(73), longitude(96)>,
 <CF Field: eastward_wind(latitude(73), longitude(96)>,
 <CF Field: eastward_wind(latitude(73), longitude(96)>]
>>> g = cf.aggregate(f)
>>> g
[<CF Field: eastward_wind(height(3), time(2), latitude(73), longitude(96)>]
>>> g[0].source
'Model A'
>>> g = cf.aggregate(f, dimension=('source',))
[<CF Field: eastward_wind(source(1), height(3), time(2), latitude(73), longitude(96)>]
>>> g[0].source
AttributeError: 'Field' object has no attribute 'source'