# 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([[   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 data as multipletau.correlate does.

For a quick overview, see Index.

### Autocorrelation

`multipletau.``autocorrelate`(a, m=16, deltat=1, normalize=False, copy=True, dtype=None)

  Autocorrelation of a 1-dimensional sequence on a log2-scale.

  This computes the correlation according 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}\)

  Note that only the correlation in the positive direction is computed.

  Parameters:

  a : array_like

  > input sequence of real numbers

  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 memory

  dtype : dtype, optional

  > The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of a is used.

  Returns:

  autocorrelation : ndarray

  > Nx2 array containing lag time and autocorrelation

  Notes

  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 emulating the numpy.correlate behavior on a logarithmic scale (default behavior) use:

  > normalize = False

  Examples

      >>> from numpy import dtype
      >>> from multipletau import autocorrelate
      >>> autocorrelate(range(42), m=2, dtype=dtype(float))
      array([[  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)

  Cross-correlation of two 1-dimensional sequences on a log2-scale.

  This computes the cross-correlation according 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.

  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 memory

  dtype : dtype, optional

  > The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of a is used.

  Returns:

  crosscorrelation : ndarray

  > Nx2 array containing lag time and cross-correlation

  Notes

  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 emulating the numpy.correlate behavior on a logarithmic scale (default behavior) use:

  > normalize = False

  Examples

      >>> from numpy import dtype
      >>> from multipletau import correlate
      >>> correlate(range(42), range(1,43), m=2, dtype=dtype(float))
      array([[  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)

  Convenience function that wraps around numpy.correlate and returns the data as multipletau.correlate 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 memory

  dtype : dtype, optional

  > The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of a is used.

  Returns:

  crosscorrelation : ndarray

  > Nx2 array containing lag time and cross-correlation

# Examples

## Comparison of correlation methods

Illustration of the difference between `multipletau.correlate()` and `numpy.correlate()`.

Download the `full example`.