# 4.2.3. Analysis results and their aggregation — `MDAnalysis.analysis.results`

Module introduces two classes, `Results` and `ResultsGroup`, used for storing and aggregating data in `MDAnalysis.analysis.base.AnalysisBase.run()`, respectively.

## 4.2.3.1. Classes

The `Results` class is an extension of a built-in dictionary type, that holds all assigned attributes in `self.data` and allows for access either via dict-like syntax, or via class-like syntax:

    from MDAnalysis.analysis.results import Results
    r = Results()
    r.array = [1, 2, 3, 4]
    assert r['array'] == r.array == [1, 2, 3, 4]

The `ResultsGroup` can merge multiple `Results` objects. It is mainly used by `MDAnalysis.analysis.base.AnalysisBase` class, that uses `ResultsGroup.merge()` method to aggregate results from multiple workers, initialized during a parallel run:

    from MDAnalysis.analysis.results import Results, ResultsGroup
    import numpy as np

    r1, r2 = Results(), Results()
    r1.masses = [1, 2, 3, 4, 5]
    r2.masses = [0, 0, 0, 0]
    r1.vectors = np.arange(10).reshape(5, 2)
    r2.vectors = np.arange(8).reshape(4, 2)

    group = ResultsGroup(
        lookup = {
            'masses': ResultsGroup.flatten_sequence,
            'vectors': ResultsGroup.ndarray_vstack
            }
        )

    r = group.merge([r1, r2])
    assert r.masses == list((*r1.masses, *r2.masses))
    assert (r.vectors == np.vstack([r1.vectors, r2.vectors])).all()

class MDAnalysis.analysis.results.Results(*args, **kwargs)

  Container object for storing results.

  `Results` are dictionaries that provide two ways by which values can be accessed: by dictionary key `results["value_key"]` or by object attribute, `results.value_key`. `Results` stores all results obtained from an analysis after calling `run()`.

  The implementation is similar to the `sklearn.utils.Bunch` class in scikit-learn.

  Raises:

    - AttributeError – If an assigned attribute has the same name as a default attribute.

    - ValueError – If a key is not of type `str` and therefore is not able to be accessed by attribute.

  Examples

      >>> from MDAnalysis.analysis.base import Results
      >>> results = Results(a=1, b=2)
      >>> results['b']
      2
      >>> results.b
      2
      >>> results.a = 3
      >>> results['a']
      3
      >>> results.c = [1, 2, 3, 4]
      >>> results['c']
      [1, 2, 3, 4]

  Added in version 2.0.0.

  Changed in version 2.8.0: Moved `Results` to `MDAnalysis.analysis.results`

class MDAnalysis.analysis.results.ResultsGroup(lookup: dict[str, Callable] = None)

  Management and aggregation of results stored in `Results` instances.

  A `ResultsGroup` is an optional description for `Result` “dictionaries” that are used in analysis classes based on `AnalysisBase`. For each key in a `Result` it describes how multiple pieces of the data held under the key are to be aggregated. This approach is necessary when parts of a trajectory are analyzed independently (e.g., in parallel) and then need to me merged (with `merge()`) to obtain a complete data set.

  Parameters:

    lookup (dict[str, Callable], optional) – aggregation functions lookup dict, by default None

  Examples

      from MDAnalysis.analysis.results import ResultsGroup, Results
      group = ResultsGroup(lookup={'mass': ResultsGroup.float_mean})
      obj1 = Results(mass=1)
      obj2 = Results(mass=3)
      assert {'mass': 2.0} == group.merge([obj1, obj2])

      # you can also set `None` for those attributes that you want to skip
      lookup = {'mass': ResultsGroup.float_mean, 'trajectory': None}
      group = ResultsGroup(lookup)
      objects = [Results(mass=1, skip=None), Results(mass=3, skip=object)]
      assert group.merge(objects, require_all_aggregators=False) == {'mass': 2.0}

  Added in version 2.8.0.

  static flatten_sequence(arrs: list[list])

    Flatten a list of lists into a list

    Parameters:

      arrs (list[list]) – list of lists

    Returns:

      flattened list

    Return type:

      list

  static float_mean(floats: list[float])

    calculates mean of input float values

    Parameters:

      floats (list[float]) – list of float values

    Returns:

      mean value

    Return type:

      float

  merge(objects: Sequence[Results], require_all_aggregators: bool = True) → Results

    Merge multiple Results into a single Results instance.

    Merge multiple `Results` instances into a single one, using the lookup dictionary to determine the appropriate aggregator functions for each named results attribute. If the resulting object only contains a single element, it just returns it without using any aggregators.

    Parameters:

      - objects (Sequence[Results]) – Multiple `Results` instances with the same data attributes.

      - require_all_aggregators (bool, optional) – if True, raise an exception when no aggregation function for a particular argument is found. Allows to skip aggregation for the parameters that aren’t needed in the final object – see `ResultsGroup`.

    Returns:

      merged `Results`

    Return type:

      Results

    Raises:

      ValueError – if no aggregation function for a key is found and `require_all_aggregators=True`

  static ndarray_hstack(arrs: list[ndarray])

    Performs horizontal stack of input arrays

    Parameters:

      arrs (list[np.ndarray]) – input numpy arrays

    Returns:

      result of stacking

    Return type:

      np.ndarray

  static ndarray_mean(arrs: list[ndarray])

    calculates mean of input ndarrays along `axis=0`

    Parameters:

      arrs (list[np.ndarray]) – list of input arrays. Must have the same shape.

    Returns:

      mean of input arrays

    Return type:

      np.ndarray

  static ndarray_sum(arrs: list[ndarray])

    sums an ndarray along `axis=0`

    Parameters:

      arrs (list[np.ndarray]) – list of input arrays. Must have the same shape.

    Returns:

      sum of input arrays

    Return type:

      np.ndarray

  static ndarray_vstack(arrs: list[ndarray])

    Performs vertical stack of input arrays

    Parameters:

      arrs (list[np.ndarray]) – input numpy arrays

    Returns:

      result of stacking

    Return type:

      np.ndarray