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, 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 cells which do not overlap (but they may share common boundary values). Ignored if the dimension coordinates do not have bounds. See the contiguous parameter.

contiguous : bool, optional

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

no_strict_units : bool, optional

If True then assume that fields or their components (such as coordinates) with the same identity 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 no identities 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 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 dimensions 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 dimension 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: '.

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)>]
>>> cf.aggregate(f)
[<CF Field: eastward_wind(height(3), time(2), latitude(73), longitude(96)>]