API Reference

Quick links:

List of Pycorrelate functions

Functions to compute linear correlation on discrete signals (uniformly sampled in time) or on point-processes (e.g. timestamps of events).

pycorrelate.pycorrelate.make_loglags(exp_min, exp_max, points_per_base, base=10, return_int=True)[source]

Make a log-spaced array useful as lag bins for cross-correlation.

This function creates an arrays of log-spaced time-lag bins to be used with pcorrelate(). By default it returns integer time-lag bins to avoid floating point inaccuracies in the correlation (showing up as higher noise at small time-lags).

Parameters:
  • exp_min (int) – exponent of the minimum value
  • exp_max (int) – exponent of the maximum value
  • points_per_base (int) – number of points per base (i.e. in a decade when base = 10)
  • base (int) – base of the exponent. Default 10.
  • return_int (bool) – if True (default) return integer bin edges to avoid floating point inaccuracies. If False, returned bin edges are float.
Returns:

Array of log-spaced values with specified range and spacing.

Example

Compute log10-spaced bins with 5 bins per decade, starting from 1 (10⁰) and stopping at 10⁶:

>>> make_loglags(0, 6, 5)
array([      1,       2,       3,       4,       6,      10,      16,
            25,      40,      63,     100,     158,     251,     398,
           631,    1000,    1585,    2512,    3981,    6310,   10000,
         15849,   25119,   39811,   63096,  100000,  158489,  251189,
        398107,  630957, 1000000])

Compute log10-spaced bins with 2 bins per decade, starting from 10⁻¹ and stopping at 10³:

>>> make_loglags(-1, 3, 2, return_int=False)
array([  1.00000000e-01,   3.16227766e-01,   1.00000000e+00,
         3.16227766e+00,   1.00000000e+01,   3.16227766e+01,
         1.00000000e+02,   3.16227766e+02,   1.00000000e+03])

See also

pcorrelate()

pycorrelate.pycorrelate.pcorrelate[source]

Compute correlation of two arrays of discrete events (Point-process).

The input arrays need to be values of a point process, such as photon arrival times or positions. The correlation is efficiently computed on an arbitrary array of lag-bins. As an example, bins can be uniformly spaced in log-space and span several orders of magnitudes. (you can use make_loglags() to creat log-spaced bins). This function implements the algorithm described in (Laurence 2006).

Parameters:
  • t (array) – first array of “points” to correlate. The array needs to be monothonically increasing.
  • u (array) – second array of “points” to correlate. The array needs to be monothonically increasing.
  • bins (array) – bin edges for lags where correlation is computed.
  • normalize (bool) – if True, normalize the correlation function as typically done in FCS using pnormalize(). If False, return the unnormalized correlation function.
Returns:

Array containing the correlation of t and u. The size is len(bins) - 1.

See also

make_loglags() to genetate log-spaced lag bins.

pycorrelate.pycorrelate.pnormalize[source]

Normalize point-process cross-correlation function.

This normalization is usually employed for fluorescence correlation spectroscopy (FCS) analysis. The normalization is performed according to (Laurence 2006). Basically, the input argument G is multiplied by:

\[\frac{T-\tau}{n(\{i \ni t_i \le T - \tau\})n(\{j \ni u_j \ge \tau\})}\]

where n({}) is the operator counting the elements in a set, t and u are the input arrays of the correlation, τ is the time lag and T is the measurement duration.

Parameters:
  • G (array) – raw cross-correlation to be normalized.
  • t (array) – first input array of “points” used to compute G.
  • u (array) – second input array of “points” used to compute G.
  • bins (array) – array of bins used to compute G. Needs to have the same units as input arguments t and u.
Returns:

Array of normalized values for the cross-correlation function, same size as the input argument G.

pycorrelate.pycorrelate.ucorrelate[source]

Compute correlation of two signals defined at uniformly-spaced points.

The correlation is defined only for positive lags (including zero). The input arrays represent signals defined at uniformily-spaced points. This function is equivalent to numpy.correlate(), but can efficiently compute correlations on a limited number of lags.

Note that binning point-processes with uniform bins, provides signals that can be passed as argument to this function.

Parameters:
  • tx (array) – first signal to be correlated
  • ux (array) – second signal to be correlated
  • maxlag (int) – number of lags where correlation is computed. If None, computes all the lags where signals overlap min(tx.size, tu.size) - 1.
Returns:

Array contained the correlation at different lags. The size of this array is equal to the input argument maxlag (if defined) or to min(tx.size, tu.size) - 1, and its dtype is the same as argument t’s.

Example

Correlation of two signals t and u:

>>> t = np.array([1, 2, 0, 0])
>>> u = np.array([0, 1, 1])
>>> pycorrelate.ucorrelate(t, u)
array([2, 3, 0])

The same result can be obtained with numpy swapping t and u and restricting the results only to positive lags:

>>> np.correlate(u, t, mode='full')[t.size - 1:]
array([2, 3, 0])
Also works with other types:
>>> t = np.array([1.2, 2.4, 0.5, 0.6])
>>> u = np.array([0, 1.2, 1.3])
>>> pycorrelate.ucorrelate(t, u)
array([3.53, 4.56, 1.56])