multipletau reference¶
General¶
This package provides a multiple-τ algorithm for Python 2.7 and
Python 3.x and requires the package numpy
.
Multipe-τ correlation is computed on a logarithmic scale (less
data points are computed) and is thus much faster than conventional
correlation on a linear scale such as numpy.correlate()
.
Recommended literature¶
- Klaus Schaetzel and Rainer Peters; Noise on multiple-tau photon correlation data. Proc. SPIE 1430, Photon Correlation Spectroscopy: Multicomponent Systems, 109 (June 1, 1991); http://doi.org/10.1117/12.44160
- Thorsten Wohland, Rudolf Rigler, and Horst Vogel; The Standard Deviation in Fluorescence Correlation Spectroscopy. Biophysical Journal, 80 (June 1, 2001); http://dx.doi.org/10.1016/S0006-3495(01)76264-9
Obtaining multipletau¶
If you have Python and numpy
installed, simply run
pip install multipletau
The source code of multipletau is available at https://github.com/FCS-analysis/multipletau.
Citing multipletau¶
The multipletau package should be cited like this (replace “x.x.x” with the actual version of multipletau that you used and “DD Month YYYY” with a matching date).
cite
Paul Müller (2012) Python multiple-tau algorithm (Version x.x.x) [Computer program]. Available at https://pypi.python.org/pypi/multipletau/ (Accessed DD Month YYYY)
You can find out what version you are using by typing (in a Python console):
>>> import multipletau
>>> multipletau.__version__
'0.1.4'
Usage¶
The package is straightforward to use. Here is a quick example:
>>> import numpy as np
>>> import multipletau
>>> a = np.linspace(2,5,42)
>>> v = np.linspace(1,6,42)
>>> multipletau.correlate(a, v, m=2)
array([[ 0. , 569.56097561],
[ 1. , 549.87804878],
[ 2. , 530.37477692],
[ 4. , 491.85812017],
[ 8. , 386.39500297]])
Methods¶
Summary:
autocorrelate (a[, m, deltat, normalize, ...]) |
Autocorrelation of a 1-dimensional sequence on a log2-scale. |
correlate (a, v[, m, deltat, normalize, ...]) |
Cross-correlation of two 1-dimensional sequences on a log2-scale. |
correlate_numpy (a, v[, deltat, normalize, ...]) |
Convenience function that wraps around numpy.correlate() and returns the correlation in the same format as correlate() does. |
For a quick overview, see Index.
Autocorrelation¶
-
multipletau.
autocorrelate
(a, m=16, deltat=1, normalize=False, copy=True, dtype=None)[source]¶ Autocorrelation of a 1-dimensional sequence on a log2-scale.
This computes the correlation similar to
numpy.correlate()
for positive \(k\) on a base 2 logarithmic scale.numpy.correlate(a, a, mode="full")[len(a)-1:]()
\(z_k = \Sigma_n a_n a_{n+k}\)
Parameters: a : array-like
input sequence
m : even integer
defines the number of points on one level, must be an even integer
deltat : float
distance between bins
normalize : bool
normalize the result to the square of the average input signal and the factor \(M-k\).
copy : bool
copy input array, set to
False
to save memorydtype : object to be converted to a data type object
The data type of the returned array and of the accumulator for the multiple-tau computation.
Returns: autocorrelation : ndarray of shape (N,2)
the lag time (1st column) and the autocorrelation (2nd column).
Notes
Changed in version 0.1.6: Compute the correlation for zero lag time.
The algorithm computes the correlation with the convention of the curve decaying to zero.
For experiments like e.g. fluorescence correlation spectroscopy, the signal can be normalized to \(M-k\) by invoking
normalize = True
.For normalizing according to the behavior of
numpy.correlate()
, usenormalize = False
.For complex arrays, this method falls back to the method
correlate()
.Examples
>>> from multipletau import autocorrelate >>> autocorrelate(range(42), m=2, dtype=np.float) array([[ 0.00000000e+00, 2.38210000e+04], [ 1.00000000e+00, 2.29600000e+04], [ 2.00000000e+00, 2.21000000e+04], [ 4.00000000e+00, 2.03775000e+04], [ 8.00000000e+00, 1.50612000e+04]])
Cross-correlation¶
-
multipletau.
correlate
(a, v, m=16, deltat=1, normalize=False, copy=True, dtype=None)[source]¶ Cross-correlation of two 1-dimensional sequences on a log2-scale.
This computes the cross-correlation similar to
numpy.correlate()
for positive \(k\) on a base 2 logarithmic scale.numpy.correlate(a, v, mode="full")[len(a)-1:]()
\(z_k = \Sigma_n a_n v_{n+k}\)
Note that only the correlation in the positive direction is computed. To obtain the correlation for negative lag times swap the input variables
a
andv
.Parameters: a, v : array-like
input sequences with equal length
m : even integer
defines the number of points on one level, must be an even integer
deltat : float
distance between bins
normalize : bool
normalize the result to the square of the average input signal and the factor \(M-k\).
copy : bool
copy input array, set to
False
to save memorydtype : object to be converted to a data type object
The data type of the returned array and of the accumulator for the multiple-tau computation.
Returns: cross_correlation : ndarray of shape (N,2)
the lag time (1st column) and the cross-correlation (2nd column).
Notes
Changed in version 0.1.6: Compute the correlation for zero lag time and correctly normalize the correlation for a complex input sequence v.
The algorithm computes the correlation with the convention of the curve decaying to zero.
For experiments like e.g. fluorescence correlation spectroscopy, the signal can be normalized to \(M-k\) by invoking
normalize = True
.For normalizing according to the behavior of
numpy.correlate()
, usenormalize = False
.Examples
>>> from multipletau import correlate >>> correlate(range(42), range(1,43), m=2, dtype=np.float) array([[ 0.00000000e+00, 2.46820000e+04], [ 1.00000000e+00, 2.38210000e+04], [ 2.00000000e+00, 2.29600000e+04], [ 4.00000000e+00, 2.12325000e+04], [ 8.00000000e+00, 1.58508000e+04]])
Cross-correlation (NumPy)¶
-
multipletau.
correlate_numpy
(a, v, deltat=1, normalize=False, dtype=None, copy=True)[source]¶ Convenience function that wraps around
numpy.correlate()
and returns the correlation in the same format ascorrelate()
does.Parameters: a, v : array-like
input sequences
deltat : float
distance between bins
normalize : bool
normalize the result to the square of the average input signal and the factor \(M-k\). The resulting curve follows the convention of decaying to zero for large lag times.
copy : bool
copy input array, set to
False
to save memorydtype : object to be converted to a data type object
The data type of the returned array.
Returns: cross_correlation : ndarray of shape (N,2)
the lag time (1st column) and the cross-correlation (2nd column).
Notes
Changed in version 0.1.6: Removed false normalization when normalize==False.
Examples¶
Comparison of correlation methods¶
Comparison between the multipletau
correlation methods
(multipletau.autocorrelate()
, multipletau.correlate()
) and numpy.correlate()
.

Download the
full example
.