cf.aggregate

cf.aggregate(fields, info=0, relaxed_units=False, no_overlap=False, contiguous=False, relaxed_identities=False, ncvar_identities=False, respect_valid=False, equal_all=False, exist_all=False, equal=None, exist=None, ignore=None, exclude=False, dimension=(), concatenate=True, copy=True, axes=None, donotchecknonaggregatingaxes=False, allow_no_identity=False, shared_nc_domain=False, atol=None, rtol=None)

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.

Identities

In order for aggregation to be possible, fields and their components need to be unambiguously identifiable. By default, these identities are taken from standard_name CF properties or else id attributes. If both of these identifiers are absent then long_name CF properties or else ncvar attributes may be used if the relaxed_identities parameter is True.

Parameters:

fields: cf.FieldList or sequence of cf.Field

The fields to aggregated.

info: int, optional

Print information about the aggregation process. If info is 0 then no information is displayed. If info is 1 or more then display information on which fields are unaggregatable, and why. If info is 2 or more then display the structural signatures of the fields and, when there is more than one field with the same structural signature, their canonical first and last coordinate values. If info is 3 or more then display the fields’ complete aggregation metadata. By default info is 0 and no information is displayed.

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.

relaxed_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.

allow_no_identity: bool, optional

If True then treat fields with data arrays but with no identities (see the above notes) as having equal but unspecified identities, so that aggregation may occur. By default such fields are not aggregatable.

relaxed_identities: bool, optional

If True then allow fields and their components to be identified by their long_name CF properties or else ncvar attributes if their standard_name CF properties or id attributes are missing.

ncvar_identities: bool, optional

If True then Force fields and their components (such as coordinates) to be identified by their netCDF file variable names.

shared_nc_domain: bool, optional

If True then match axes between a field and its contained ancillary variable and coordinate reference fields via their netCDF dimension names and not via their domains.

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.

respect_valid: bool, optional

If True then the CF properties valid_min, valid_max and valid_range are taken into account during aggregation. I.e. a requirement for aggregation is that fields have identical values for each these attributes, if set. By default these CF properties are ignored and are not set in the output fields.

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 in place, and the output fields may not be independent of the inputs. However, if it is known that the input fields are never to accessed again (such as in this case: f = cf.aggregate(f)) then setting copy to False can reduce the time taken for aggregation.

axes: (sequence of) str, optional

Select axes to aggregate over. Aggregation will only occur over as large a subset as possible of these axes. Each axis is identified by the exact identity of a one dimensional coordinate object, as returned by its identity method. Aggregations over more than one axis will occur in the order given. By default, aggregation will be over as many axes as possible.

donotchecknonaggregatingaxes: bool, optional

If True, and axes is set, then checks for consistent data array values will only be made for one dimensional coordinate objects which span the any of the given aggregating axes. This can reduce the time taken for aggregation, but if any those checks would have failed then this clearly allows the possibility of an incorrect result. Therefore, this option should only be used in cases for which it is known that the non-aggregating axes are in fact already entirely consistent.

atol: float, optional

The absolute tolerance for all numerical comparisons. The tolerance is a non-negative, typically very small number. Two numbers, x and y, are considered the same if \(|x-y| \le atol + rtol*|y|\). By default the value returned by the ATOL function is used.

rtol: float, optional

The relative tolerance for all numerical comparisons. The tolerance is a non-negative, typically very small number. Two numbers, x and y, are considered the same if \(|x-y| \le atol + rtol*|y|\). By default the value returned by the RTOL function is used.

Returns:

out: cf.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'