13.2.11. Correlations utilities — MDAnalysis.lib.correlations¶
| Authors: | Paul Smith & Mateusz Bieniek |
|---|---|
| Year: | 2020 |
| Copyright: | GNU Public License v2 |
New in version 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 autocorrelation()
calculates the continuous autocorrelation only. The data may be
pre-processed using the function intermittency() in order to
acount for intermittency before passing the results to
autocorrelation().
This module is inspired by seemingly disparate analyses that rely on the same underlying calculation, including the survival probability of water around proteins [Araya-Secchi2014], hydrogen bond lifetimes [Gowers2015], [Araya-Secchi2014], and the rate of cholesterol flip-flop in lipid bilayers [Gu2019].
See also
Analysis tools that make use of modules:
MDAnalysis.analysis.waterdynamics.SurvivalProbability- Calculates the continuous or intermittent survival probability of an atom group in a region of interest.
MDAnalysis.analysis.hbonds.hbond_analysis- Calculates the continuous or intermittent hydrogen bond lifetime.
References
| [Gu2019] | Gu, R.-X.; Baoukina, S.; Tieleman, D. P. (2019) Cholesterol Flip-Flop in Heterogeneous Membranes. J. Chem. Theory Comput. 15 (3), 2064–2070. https://doi.org/10.1021/acs.jctc.8b00933. |
13.2.11.1. Autocorrelation Function¶
-
MDAnalysis.lib.correlations.autocorrelation(list_of_sets, tau_max, window_step=1)[source]¶ Implementation of a discrete autocorrelation function.
The autocorrelation of a property \(x\) from a time \(t=t_0\) to \(t=t_0 + \tau\) is given by:
\[C(\tau) = \langle \frac{ x(t_0)x(t_0 +\tau) }{ x(t_0)x(t_0) } \rangle\]where \(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, \(0\) and \(1\), to represent the binary state of said property. This special case is often referred to as the survival probability (\(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 (\(1\)) or not (\(0\)). The total number of water molecules within the cutoff at time \(t_0\) will be given by \(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:
\[S(\tau) = \langle \frac{ N(t_0, t_0 + \tau )} { N(t_0) }\rangle\]where \(N(t0)\) is the number of particles at time \(t_0\) for which the feature is observed, and \(N(t0, t_0 + \tau)\) is the number of particles for which this feature is present at every frame from \(t_0\) to \(N(t0, t_0 + \tau)\). The angular brackets represent an average over all time origins, \(t_0\).
See [Araya-Secchi2014] 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 \(S(\tau)\) at each window. This allows the time dependant evolution of \(S(\tau)\) to be investigated.
- .. versionadded:: 0.19.2
13.2.11.2. Intermittency Function¶
-
MDAnalysis.lib.correlations.correct_intermittency(list_of_sets, intermittency)[source]¶ Preprocess data to allow intermittent behaviour prior to calling
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 \(t_0\) to \(t_0 + \tau\) in order for it to be considered present at \(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 \(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
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
autocorrelation()in order to calculate the survival probability with a given intermittency.See [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 – returns a new list with the IDs with added IDs which disappeared for <=
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}].Return type: