i,,dZddlZddlmZddZdZdS)aCorrelations utilities --- :mod:`MDAnalysis.lib.correlations` ================================================================================= :Authors: Paul Smith & Mateusz Bieniek :Year: 2020 :Copyright: Lesser GNU Public License v2.1+ .. versionadded:: 1.0.0 This module is primarily for internal use by other analysis modules. It provides functionality for calculating the time autocorrelation function of a binary variable (i.e one that is either true or false at each frame for a given atom/molecule/set of molecules). This module includes functions for calculating both the time continuous autocorrelation and the intermittent autocorrelation. The function :func:`autocorrelation` calculates the continuous autocorrelation only. The data may be pre-processed using the function :func:`intermittency` in order to acount for intermittency before passing the results to :func:`autocorrelation`. This module is inspired by seemingly disparate analyses that rely on the same underlying calculation, including the survival probability of water around proteins :footcite:p:`ArayaSecchi2014`, hydrogen bond lifetimes :footcite:p:`Gowers2015,ArayaSecchi2014`, and the rate of cholesterol flip-flop in lipid bilayers :footcite:p:`Gu2019`. .. seeAlso:: Analysis tools that make use of modules: * :class:`MDAnalysis.analysis.waterdynamics.SurvivalProbability` Calculates the continuous or intermittent survival probability of an atom group in a region of interest. * :class:`MDAnalysis.analysis.hbonds.hbond_analysis` Calculates the continuous or intermittent hydrogen bond lifetime. .. rubric:: References .. footbibliography:: N)deepcopyc Dt|tkrt|dkst|dtkrt dt||krt dtt d|dz}dt |D}t dt||D]}t||}|dkr|D]q}||zt|krnXttj||||zdz}||dz |t|z rd|D} | dd| dd|| |fS)u Implementation of a discrete autocorrelation function. The autocorrelation of a property :math:`x` from a time :math:`t=t_0` to :math:`t=t_0 + \tau` is given by: .. math:: C(\tau) = \langle \frac{ x(t_0)x(t_0 +\tau) }{ x(t_0)x(t_0) } \rangle where :math:`x` may represent any property of a particle, such as velocity or potential energy. This function is an implementation of a special case of the time autocorrelation function in which the property under consideration can be encoded with indicator variables, :math:`0` and :math:`1`, to represent the binary state of said property. This special case is often referred to as the survival probability (:math:`S(\tau)`). As an example, in calculating the survival probability of water molecules within 5 Å of a protein, each water molecule will either be within this cutoff range (:math:`1`) or not (:math:`0`). The total number of water molecules within the cutoff at time :math:`t_0` will be given by :math:`N(t_0)`. Other cases include the Hydrogen Bond Lifetime as well as the translocation rate of cholesterol across a bilayer. The survival probability of a property of a set of particles is given by: .. math:: S(\tau) = \langle \frac{ N(t_0, t_0 + \tau )} { N(t_0) }\rangle where :math:`N(t0)` is the number of particles at time :math:`t_0` for which the feature is observed, and :math:`N(t0, t_0 + \tau)` is the number of particles for which this feature is present at every frame from :math:`t_0` to :math:`N(t0, t_0 + \tau)`. The angular brackets represent an average over all time origins, :math:`t_0`. See :footcite:`ArayaSecchi2014` for a description survival probability. Parameters ---------- list_of_sets : list List of sets. Each set corresponds to data from a single frame. Each element in a set may be, for example, an atom id or a tuple of atoms ids. In the case of calculating the survival probability of water around a protein, these atom ids in a given set will be those of the atoms which are within a cutoff distance of the protein at a given frame. tau_max : int The last tau (lag time, inclusive) for which to calculate the autocorrelation. e.g if tau_max = 20, the survival probability will be calculated over 20 frames. window_step : int, optional The step size for t0 to perform autocorrelation. Ideally, window_step will be larger than tau_max to ensure independence of each window for which the calculation is performed. Default is 1. Returns -------- tau_timeseries : list of int the values of tau for which the autocorrelation was calculated timeseries : list of int the autocorelation values for each of the tau values timeseries_data : list of list of int the raw data from which the autocorrelation is computed, i.e :math:`S(\tau)` at each window. This allows the time dependant evolution of :math:`S(\tau)` to be investigated. .. versionadded:: 0.19.2 rz3list_of_sets must be a one-dimensional list of setsz9tau_max cannot be greater than the length of list_of_setsrcg|]}gSr).0_s e/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/lib/correlations.py z#autocorrelation..s222ar222c6g|]}tj|Sr)npmean)rxs r r z#autocorrelation..s 666"'!**666r ) typelistlenset TypeError ValueErrorrange intersectionappendfloatinsert) list_of_setstau_max window_steptau_timeseriestimeseries_datatNttauNtau timeseriess r autocorrelationr&IsB \d""s<'8'8A'='=$QCC C C  A    <7"" G   %7Q;//00N225>>222O1c,'' 5 5 > > a ! ! 77 ! > >C3w#l++++s'a!c'A+o)FGHHD C!G $ + +D599,< = = = =66o666J!Qa : 66r c|dkr|St|}t|D]\}}d|D}td|dzD]}|D]}||zt |kr||||zvr||xxdz cc<7||dkrD|||krQt||ddD]#}|||z|z |$d||<|S)a Preprocess data to allow intermittent behaviour prior to calling :func:`autocorrelation`. Survival probabilty may be calculated either with a strict continuous requirement or a less strict intermittency. If calculating the survival probability water around a protein for example, in the former case the water must be within a cutoff distance of the protein at every frame from :math:`t_0` to :math:`t_0 + \tau` in order for it to be considered present at :math:`t_0 + \tau`. In the intermittent case, the water molecule is allowed to leave the region of interest for up to a specified consecutive number of frames whilst still being considered present at :math:`t_0 + \tau`. This function pre-processes data, such as the atom ids of water molecules within a cutoff distance of a protein at each frame, in order to allow for intermittent behaviour, with a single pass over the data. For example, if an atom is absent for a number of frames equal or smaller than the parameter :attr:`intermittency`, then this absence will be removed and thus the atom is considered to have not left. e.g 7,A,A,7 with `intermittency=2` will be replaced by 7,7,7,7, where A=absence. The returned data can be used as input to the function :func:`autocorrelation` in order to calculate the survival probability with a given intermittency. See :footcite:p:`Gowers2015` for a description of intermittency in the calculation of hydrogen bond lifetimes. # TODO - is intermittency consitent with list of sets of sets? (hydrogen bonds) Parameters ---------- list_of_sets: list In the simple case of e.g survival probability, a list of sets of atom ids present at each frame, where a single set contains atom ids at a given frame, e.g [{0, 1}, {0}, {0}, {0, 1}] intermittency : int The maximum gap allowed. The default `intermittency=0` means that if the datapoint is missing at any frame, no changes are made to the data. With the value of `intermittency=2`, all datapoints missing for up to two consecutive frames will be instead be considered present. Returns ------- list_of_sets: list returns a new list with the IDs with added IDs which disappeared for <= :attr:`intermittency`. e.g If [{0, 1}, {0}, {0}, {0, 1}] is a list of sets of atom ids present at each frame and `intermittency=2`, both atoms will be considered present throughout and thus the returned list of sets will be [{0, 1}, {0, 1}, {0, 1}, {0, 1}]. rci|]}|dS)rr)ris r z)correct_intermittency..s222A1a222r r)r enumeraterkeysradd)r intermittencyr)elementsseen_frames_agojelementks r correct_intermittencyr6sj^L))L !..-- 822222q-!+,, - -A*//11 - -q5C ----,q1u"555#G,,,1,,,#7+q00#7+m;; w7B??99A Q+//8888+,((7 - -: r )r)__doc__numpyrcopyrr&r6rr r r:sg0++Zf7f7f7f7RWWWWWr