cf.aggregate

cf.aggregate(fields, verbose=None, 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, field_identity=None, info=False)

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, 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; the field_identity parameter forces the field construct identities to be taken from a particular property; and the ncvar_identities parameter forces field and metadata constructs to be identified by their netCDF file variable names.

Parameters

fields: FieldList or sequence of Field

The field constructs to aggregate.

verbose: int or str or None, optional

If an integer from -1 to 3, or an equivalent string equal ignoring case to one of:

• 'DISABLE' (0)

• 'WARNING' (1)

• 'INFO' (2)

• 'DETAIL' (3)

• 'DEBUG' (-1)

set for the duration of the method call only as the minimum cut-off for the verboseness level of displayed output (log) messages, regardless of the globally-configured cf.log_level. Note that increasing numerical value corresponds to increasing verbosity, with the exception of -1 as a special case of maximal and extreme verbosity.

Otherwise, if None (the default value), output messages will be shown according to the value of the cf.log_level setting.

Overall, the higher a non-negative integer or equivalent string that is set (up to a maximum of 3/'DETAIL') for increasing verbosity, the more description that is printed to convey information about the aggregation process. Explicitly:

Value set	Result
0	No information is displayed.
1	Display information on which fields are unaggregatable, and why.
2	As well as the above, 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.
3/-1	As well as the above, 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.

field_identity: str, optional

Specify a property with which to identify field constructs instead of any other technique. How metadata constructs are identified is not affected by this parameter. See the relaxed_identities and ncvar_identities parameters.

Parameter example:

Force field constructs to be identified by the values of their long_name properties: field_identity='long_name'

New in version 3.1.0.

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: (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: (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.

ignore: (sequence of) str, optional

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

exclude: bool, optional

If True then do not return unaggregatable field constructs. By default, all input field constructs are represent in the outputs.

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.

info: deprecated at version 3.5.0

Use the verbose parameter instead.

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'