cf.aggregate

cf.aggregate(fields, info=0, relaxed_units=False, overlap=True, 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, atol=None, rtol=None, no_overlap=False, shared_nc_domain=False)[source]

Aggregate field constructs into as few field constructs as possible.

Aggregation is the combination of field constructs to create a new field construct that occupies a “larger” domain. Using the aggregation rules (https://ncas-cms.github.io/cf-python/aggregation_rules.html), field constructs are separated into aggregatable groups and each group is then aggregated to a single field construct.

Identifying field and metadata constructs

In order to ascertain whether or not field constructs are aggregatable, the aggregation rules rely on field constructs (and their metadata constructs where applicable) being identified by standard name properties. However, it is sometimes the case that standard names are not available. In such cases the “id” attribute (which is not a CF property) may be set on any construct, which will be treated like a standard name if one doesn’t exist. Alternatively the relaxed_identities parameter allows long name properties or netCDF variable names to be used when standard names are missing.

Units

Parameters:
fields: FieldList or sequence of Field

The field constructs to aggregated.

info: int, optional

Print information about the aggregation process. By default info is 0 and 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 also display the structural signatures of the fields and, when there is more than one field construct with the same structural signature, their canonical first and last coordinate values. If info is 3 or more then display the field construct’s complete aggregation metadata.

overlap: bool, optional

If False then require that aggregated field constructs have adjacent dimension coordinate construct cells which do not overlap (but they may share common boundary values). Ignored for a dimension coordinate construct that does not have bounds. See also the contiguous parameter.

contiguous: bool, optional

If True then require that aggregated field constructs have adjacent dimension coordinate construct cells which overlap or share common boundary values. Ignored for a dimension coordinate construct that does not have bounds. See also the overlap parameter.

relaxed_units: bool, optional

If True then assume that field and metadata constructs with the same identity but missing units actually have equivalent (but unspecified) units, so that aggregation may occur. By default such field constructs are not aggregatable.

allow_no_identity: bool, optional

If True then assume that field and metadata constructs with no identity (see the relaxed_identities parameter) actually have the same (but unspecified) identity, so that aggregation may occur. By default such field constructs are not aggregatable.

relaxed_identities: bool, optional

If True and there is no standard name property nor “id” attribute, then allow field and metadata constructs to be identifiable by long name properties or netCDF variable names.

ncvar_identities: bool, optional

If True then force field and metadata constructs to be identified by their netCDF file variable names See also the relaxed_identies parameter.

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.

no_overlap:

Use the overlap parameter instead.

shared_nc_domain: deprecated at version 3.0.0

No longer required due to updated CF data model.
Returns:
FieldList

The aggregated field constructs.

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'