i&ddZddlmZddlZddlmZmZGddeZGddZ dS) amAnalysis results and their aggregation --- :mod:`MDAnalysis.analysis.results` ================================================================================ Module introduces two classes, :class:`Results` and :class:`ResultsGroup`, used for storing and aggregating data in :meth:`MDAnalysis.analysis.base.AnalysisBase.run()`, respectively. Classes ------- The :class:`Results` class is an extension of a built-in dictionary type, that holds all assigned attributes in :attr:`self.data` and allows for access either via dict-like syntax, or via class-like syntax: .. code-block:: python from MDAnalysis.analysis.results import Results r = Results() r.array = [1, 2, 3, 4] assert r['array'] == r.array == [1, 2, 3, 4] The :class:`ResultsGroup` can merge multiple :class:`Results` objects. It is mainly used by :class:`MDAnalysis.analysis.base.AnalysisBase` class, that uses :meth:`ResultsGroup.merge()` method to aggregate results from multiple workers, initialized during a parallel run: .. code-block:: python 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() )UserDictN)CallableSequencecPeZdZdZdZdZfdZfdZdZdZ dZ d Z xZ S) ResultsaContainer object for storing results. :class:`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``. :class:`Results` stores all results obtained from an analysis after calling :meth:`~AnalysisBase.run()`. The implementation is similar to the :class:`sklearn.utils.Bunch` class in `scikit-learn`_. .. _`scikit-learn`: https://scikit-learn.org/ .. _`sklearn.utils.Bunch`: https://scikit-learn.org/stable/modules/generated/sklearn.utils.Bunch.html 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] .. versionadded:: 2.0.0 .. versionchanged:: 2.8.0 Moved :class:`Results` to :mod:`MDAnalysis.analysis.results` c|t|vrtd|dt|tr'|st d|ddSdS)N'z%' is a protected dictionary attributez' is not a valid attribute)dirAttributeError isinstancestr isidentifier ValueError)selfkeys e/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/analysis/results.py _validate_keyzResults._validate_keyfs #d))   >C>>> S ! ! B#*:*:*<*< B@@@@AA A B B B Bct|i|}d|vrtdi|jd<||dS)Ndataz*'data' is a protected dictionary attribute)dictkeysr __dict__update)rargskwargss r__init__zResults.__init__nsZt&v&& V[[]] " " !NOO O " f Frcv||t||dSN)rsuper __setitem__)rritem __class__s rr!zResults.__setitem__us7 3 C&&&&&rc|dkr$t||dS|||dS)Nr)r __setattr__r!)rattrvalr#s rr%zResults.__setattr__ysH 6>> GG  c * * * * *   T3 ' ' ' ' 'rc` ||S#t$r}td|d|d}~wwxYwNz#'Results' object has no attribute 'r KeyErrorr rr&errs r __getattr__zResults.__getattr__sS :     =d===  s -(-cZ ||=dS#t$r}td|d|d}~wwxYwr)r*r,s r __delattr__zResults.__delattr__sT T     =d===  s *%*c|jSrr)rs r __getstate__zResults.__getstate__s yrc||_dSrr2)rstates r __setstate__zResults.__setstate__s  r) __name__ __module__ __qualname____doc__rrr!r%r.r0r3r6 __classcell__)r#s@rrr9s**XBBB'''''((((( rrcleZdZdZddeeeffdZ ddee de de fd Z e d e e fd Ze d e ejfd Ze d e ejfd Ze de efdZe d e ejfdZe d e ejfdZdS) ResultsGroupa Management and aggregation of results stored in :class:`Results` instances. A :class:`ResultsGroup` is an optional description for :class:`Result` "dictionaries" that are used in analysis classes based on :class:`AnalysisBase`. For each *key* in a :class:`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 :meth:`merge`) to obtain a complete data set. Parameters ---------- lookup : dict[str, Callable], optional aggregation functions lookup dict, by default None Examples -------- .. code-block:: python 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]) .. code-block:: python # 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} .. versionadded:: 2.8.0 Nlookupc||_dSr)_lookup)rr>s rrzResultsGroup.__init__s  rTobjectsrequire_all_aggregatorsreturnc4t|dkr |d}|St}|dD]P|jd}|fd|D}|||<<|rt dQ|S)a*Merge multiple Results into a single Results instance. Merge multiple :class:`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 :class:`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 :class:`ResultsGroup`. Returns ------- Results merged :class:`Results` Raises ------ ValueError if no aggregation function for a key is found and ``require_all_aggregators=True`` rNc g|] }| SrG).0objrs r z&ResultsGroup.merge..s<<.s%===W==T====rrGrQs rflatten_sequencezResultsGroup.flatten_sequences>=D====rcRtj|dS)asums an ndarray along ``axis=0`` Parameters ---------- arrs : list[np.ndarray] list of input arrays. Must have the same shape. Returns ------- np.ndarray sum of input arrays raxis)nparraysumrUs r ndarray_sumzResultsGroup.ndarray_sums#x~~!!q!)))rcRtj|dS)acalculates mean of input ndarrays along ``axis=0`` Parameters ---------- arrs : list[np.ndarray] list of input arrays. Must have the same shape. Returns ------- np.ndarray mean of input arrays rrXrZr[meanrUs r ndarray_meanzResultsGroup.ndarray_mean s#x~~"""***rfloatscNtj|S)zcalculates mean of input float values Parameters ---------- floats : list[float] list of float values Returns ------- float mean value r_)rbs r float_meanzResultsGroup.float_means x$$&&&rc*tj|S)zPerforms horizontal stack of input arrays Parameters ---------- arrs : list[np.ndarray] input numpy arrays Returns ------- np.ndarray result of stacking )rZhstackrUs rndarray_hstackzResultsGroup.ndarray_hstack,yrc*tj|S)zPerforms vertical stack of input arrays Parameters ---------- arrs : list[np.ndarray] input numpy arrays Returns ------- np.ndarray result of stacking )rZvstackrUs rndarray_vstackzResultsGroup.ndarray_vstack<rhrr)T)r7r8r9r:rr rrrrboolrP staticmethodlistrVrZndarrayr]rafloatrdrgrkrGrrr=r=s$$LtCM2KO**(*CG* ****X >tDz > > >\ > *$rz* * * *\ * +4 + + + +\ + '4; ' ' '\ ' T"*-   \  T"*-   \   rr=) r: collectionsrnumpyrZtypingrrrr=rGrrrts11f! %%%%%%%%ZZZZZhZZZzttttttttttr