# 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'