cddm.multitau

Multiple-tau algorithm and log averaging functions.

Multitau analysis (in-memory, general data versions):

  • ccorr_multi() to calculate cross-correlation/difference functions.

  • acorr_multi() to calculate auto-correlation/difference functions.

For out-of-memory analysis and real-time calculation use:

For normalization and merging of the results of the above functions use:

  • normalize_multi() to normalize the outputs of the above functions.

  • log_merge() To merge results of the multi functions into one continuous data.

For time averaging of linear spaced data use:

Module Contents

cddm.multitau.BINNING_FIRST = 0

No binning (select every second element)

cddm.multitau.BINNING_MEAN = 1

Binning (take mean value)

cddm.multitau.BINNING_CHOOSE = 2

Binning with random selection

cddm.multitau.mean_data(data, axis=0, out_axis=None, **kw)

Binning function. Takes data and performs channel binning over a specifed axis. If specified, also moves axis to out_axis.

cddm.multitau.choose_data(data, axis=0, out_axis=None, r=None)

Instead of binning, this randomly selects data. If specified, also moves axis to out_axis.

cddm.multitau.slice_data(data, axis=0, out_axis=None, **kw)

Slices data so that it takes every second channel. If specified, also moves axis to out_axis.

cddm.multitau.ccorr_multi(f1, f2, t1=None, t2=None, level_size=2 ** 4, norm=None, method=None, align=False, axis=0, period=1, binning=None, nlevel=None, thread_divisor=None, mask=None)

Multitau version of core.ccorr()

Parameters

  • f1 (array-like) – A complex ND array of the first data.

  • f2 (array-like) – A complex ND array of the second data.

  • t1 (array-like, optional) – Array of integers defining frame times of the first data. If not provided, regular time-spaced data is assumed.

  • t2 (array-like, optional) – Array of integers defining frame times of the second data. If not provided, regular time-spaced data is assumed.

  • level_size (int, optional) – If provided, determines the length of the output.

  • norm (int, optional) – Specifies normalization procedure 0,1,2, or 3 (default).

  • method (str, optional) – Either ‘fft’, ‘corr’ or ‘diff’. If not given it is chosen automatically based on the rest of the input parameters.

  • align (bool, optional) – Whether to align data prior to calculation. Note that a complete copy of the data takes place.

  • axis (int, optional) – Axis over which to calculate.

  • period (int, optional) – Period of the irregular-spaced random triggering sequence. For regular spaced data, this should be set to 1 (deefault).

  • binning (int, optional) – Binning mode (0 - no binning, 1 : average, 2 : random select)

  • nlevel (int, optional) – If specified, defines how many levels are used in multitau algorithm. If not provided, all available levels are used.

  • thread_divisor (int, optional) – If specified, input frame is reshaped to 2D with first axis of length specified with the argument. It defines how many treads are run. This must be a divisor of the total size of the frame. Using this may speed up computation in some cases because of better memory alignment and cache sizing.

Returns

lin, multi – A tuple of linear (short delay) data and multilevel (large delay) data See core.ccorr() for definition of ccorr_type

Return type

ccorr_type, ccorr_type

cddm.multitau.acorr_multi(f, t=None, level_size=2 ** 4, norm=None, method=None, align=False, axis=0, period=1, binning=None, nlevel=None, thread_divisor=None, mask=None)

Multitau version of core.acorr()

Parameters

  • f (array-like) – A complex ND array

  • t (array-like, optional) – Array of integers defining frame times of the data. If not provided, regular time-spaced data is assumed.

  • level_size (int, optional) – If provided, determines the length of the output.

  • norm (int, optional) – Specifies normalization procedure 0,1,2, or 3 (default).

  • method (str, optional) – Either ‘fft’, ‘corr’ or ‘diff’. If not given it is chosen automatically based on the rest of the input parameters.

  • align (bool, optional) – Whether to align data prior to calculation. Note that a complete copy of the data takes place.

  • axis (int, optional) – Axis over which to calculate.

  • period (int, optional) – Period of the irregular-spaced random triggering sequence. For regular spaced data, this should be set to 1 (deefault).

  • binning (int, optional) – Binning mode (0 - no binning, 1 : average, 2 : random select)

  • nlevel (int, optional) – If specified, defines how many levels are used in multitau algorithm. If not provided, all available levels are used.

  • thread_divisor (int, optional) – If specified, input frame is reshaped to 2D with first axis of length specified with the argument. It defines how many treads are run. This must be a divisor of the total size of the frame. Using this may speed up computation in some cases because of better memory alignment and cache sizing.

Returns

lin, multi – A tuple of linear (short delay) data and multilevel (large delay) data See core.acorr() for definition of acorr_type

Return type

acorr_type, acorr_type

cddm.multitau.iccorr_multi(data, t1=None, t2=None, level_size=2 ** 4, norm=None, method='corr', count=None, period=1, binning=None, nlevel=None, chunk_size=None, thread_divisor=None, auto_background=False, viewer=None, viewer_interval=1, mode='full', mask=None, stats=True)

Iterative version of ccorr_multi()

Parameters

  • data (iterable) – An iterable object, iterating over dual-frame ndarray data.

  • t1 (array-like, optional) – Array of integers defining frame times of the first data. If not defined, regular-spaced data is assumed.

  • t2 (array-like, optional) – Array of integers defining frame times of the second data. If t1 is defined, you must define t2 as well.

  • level_size (int, optional) – If provided, determines the length of the multi_level data.

  • norm (int, optional) – Specifies normalization procedure 0,1,2, or 3 (default).

  • method (str, optional) – Either ‘fft’, ‘corr’ or ‘diff’. If not given it is chosen automatically based on the rest of the input parameters.

  • count (int, optional) – If given, it defines how many elements of the data to process. If not given, count is set to len(t1) if that is not specified, it is set to len(data).

  • period (int, optional) – Period of the irregular-spaced random triggering sequence. For regular spaced data, this should be set to 1 (deefault).

  • binning (int, optional) – Binning mode (0 - no binning, 1 : average, 2 : random select)

  • nlevel (int, optional) – If specified, defines how many levels are used in multitau algorithm. If not provided, all available levels are used.

  • chunk_size (int) – Length of data chunk.

  • thread_divisor (int, optional) – If specified, input frame is reshaped to 2D with first axis of length specified with the argument. It defines how many treads are run. This must be a divisor of the total size of the frame. Using this may speed up computation in some cases because of better memory alignment and cache sizing.

  • auto_background (bool) – Whether to use data from first chunk to calculate and subtract background.

  • viewer (any, optional) – You can use viewer.MultitauViewer to display data.

  • viewer_interval (int, optional) – A positive integer, defines how frequently are plots updated 1 for most frequent, higher numbers for less frequent updates.

  • mode (str) – Either “full” or “partial”. With mode = “full”, output of this function is identical to the output of ccorr_multi(). With mode = “partial”, cross correlation between neighbouring chunks is not computed.

  • mask (ndarray, optional) – If specifed, computation is done only over elements specified by the mask. The rest of elements are not computed, np.nan values are written to output arrays.

  • stats (bool) – Whether to return stats as well.

Returns

  • (lin, multi), bg, var ((ccorr_type, ccorr_type), ndarray, ndarray) – A tuple of linear (short delay) data and multilevel (large delay) data, background and variance data. See core.ccorr() for definition of ccorr_type

  • lin, multi (ccorr_type, ccorr_type) – If stats == False

cddm.multitau.iacorr_multi(data, t=None, level_size=2 ** 4, norm=None, method='corr', count=None, period=1, binning=None, nlevel=None, chunk_size=None, thread_divisor=None, auto_background=False, viewer=None, viewer_interval=1, mode='full', mask=None, stats=True)

Iterative version of acorr_multi()

Parameters

  • data (iterable) – An iterable object, iterating over dual-frame ndarray data.

  • t (array-like, optional) – Array of integers defining frame times of the first data. If not defined, regular-spaced data is assumed.

  • level_size (int, optional) – If provided, determines the length of the multi_level data.

  • norm (int, optional) – Specifies normalization procedure 0,1,2, or 3 (default).

  • method (str, optional) – Either ‘fft’, ‘corr’ or ‘diff’. If not given it is chosen automatically based on the rest of the input parameters.

  • count (int, optional) – If given, it defines how many elements of the data to process. If not given, count is set to len(t1) if that is not specified, it is set to len(data).

  • period (int, optional) – Period of the irregular-spaced random triggering sequence. For regular spaced data, this should be set to 1 (deefault).

  • binning (int, optional) – Binning mode (0 - no binning, 1 : average, 2 : random select)

  • nlevel (int, optional) – If specified, defines how many levels are used in multitau algorithm. If not provided, all available levels are used.

  • chunk_size (int) – Length of data chunk.

  • thread_divisor (int, optional) – If specified, input frame is reshaped to 2D with first axis of length specified with the argument. It defines how many treads are run. This must be a divisor of the total size of the frame. Using this may speed up computation in some cases because of better memory alignment and cache sizing.

  • auto_background (bool) – Whether to use data from first chunk to calculate and subtract background.

  • viewer (any, optional) – You can use viewer.MultitauViewer to display data.

  • viewer_interval (int, optional) – A positive integer, defines how frequently are plots updated 1 for most frequent, higher numbers for less frequent updates.

  • mode (str) – Either “full” or “chunk”. With mode = “full”, output of this function is identical to the output of ccorr_multi(). With mode = “chunk”, cross correlation between neighbouring chunks is not computed.

  • mask (ndarray, optional) – If specifed, computation is done only over elements specified by the mask. The rest of elements are not computed, np.nan values are written to output arrays.

  • stats (bool) – Whether to return stats as well.

Returns

  • (lin, multi), bg, var ((acorr_type, acorr_type), ndarray, ndarray) – A tuple of linear (short delay) data and multilevel (large delay) data, background and variance data. See core.acorr() for definition of acorr_type

  • lin, multi (acorr_type, acorr_type) – If stats == False

cddm.multitau.triangular_kernel(n)

Returns normalized triangular kernel for a given level integer

Examples

>>> triangular_kernel(0) #zero-th level
array([1.])
>>> triangular_kernel(1) #first level
array([0.25, 0.5 , 0.25])
cddm.multitau.multilevel_count(count, level_size, binning=BINNING_MEAN)

Returns effective number of measurements in multilevel data calculated from linear time-space count data using multilevel()

This function can be used to estimate the effective number of realizations of each data point in multilevel data for error estimation.

Parameters

  • count (ndarray) – Count data,

  • level_size (int) – Level size used in multilevel averaging.

  • binning (int) – Binning mode that was used in multilevel()

Returns

x – Multilevel effective count array. Shape of this data depends on the length of the original data and the provided level_size parameter.

Return type

ndarray

cddm.multitau.ccorr_multi_count(count, period=1, level_size=16, binning=True)

Returns an effective count data for the equivalent multilevel cross-correlation calculation.

Parameters

  • count (int) – Number of frames processed

  • period (int) – The period argument used in correlation calculation

  • level_size (int) – Level size used in correlation calculation

  • binning – Binning mode used in correlation calculation

  • int – Binning mode used in correlation calculation

Returns

cf,cs – Count arrays for the linear part and the multilevel part of the multilevel correlation calculation.

Return type

ndarray, ndarray

cddm.multitau.acorr_multi_count(count, period=1, level_size=16, binning=True)

Returns an effective count data for the equivalent multilevel auto-correlation calculation.

Parameters

  • count (int) – Number of frames processed

  • period (int) – The period argument used in correlation calculation

  • level_size (int) – Level size used in correlation calculation

  • binning – Binning mode used in correlation calculation

  • int – Binning mode used in correlation calculation

Returns

cf,cs – Count arrays for the linear part and the multilevel part of the multilevel correlation calculation,

Return type

ndarray, ndarray

cddm.multitau.multilevel(data, level_size=16, binning=BINNING_MEAN)

Computes a multi-level version of the linear time-spaced data.

Parameters

  • data (ndarray) – Normalized correlation data

  • level_size (int) – Level size

  • binning (int) – Binning mode, either BINNING_FIRST or BINNING_MEAN (default).

Returns

x – Multilevel data array. Shape of this data depends on the length of the original data and the provided level_size parameter

Return type

ndarray

cddm.multitau.merge_multilevel(data, mode='full')

Merges multilevel data (data as returned by the multilevel() function)

Parameters

  • data (ndarray) – data as returned by multilevel()

  • mode (str, optional) – Either ‘full’ or ‘half’. Defines how data from the zero-th level of the multi-level data is treated. Take all data (full) or only second half

Returns

x, y – Time, log-spaced data arrays

Return type

ndarray, ndarray

cddm.multitau.log_average(data, size=8)

Performs log average of normalized linear-spaced data.

You must first normalize with core.normalize() before averaging!

Parameters

  • data (array) – Input array of linear-spaced data

  • size (int) – Sampling size. Number of data points per each doubling of time. Any positive number is valid.

Returns

x, y – Time and log-spaced data arrays.

Return type

ndarray, ndarray

cddm.multitau.log_average_count(count, size=8)

Returns effective number of measurements in data calculated from linear time-space count data using log_average()

This function can be used to estimate the effective number of realizations of each data point in multilevel data for error estimation.

Parameters

  • count (ndarray) – Count data, as returned by the ccorr or acorr functions

  • size (int) – Sampling size that was used in log_average()

Returns

x, y – Time and log-spaced effetive count arrays.

Return type

ndarray, ndarray

cddm.multitau.log_merge(lin, multi, binning=BINNING_MEAN)

Merges normalized multi-tau data.

You must first normalize with normalize_multi() before merging! This function performs a multilevel split on the fast (linear) data and merges that with the multilevel slow data into a continuous log-spaced data.

Parameters

  • lin (ndarray) – Linear data

  • multi (ndarray) – Multilevel data

  • binning (int) – Binning mode used for multilevel calculation of the linear part of the data. either BINNING_FIRST or BINNING_MEAN (default).

Returns

x, y – Time and log-spaced data arrays.

Return type

ndarray, ndarray

cddm.multitau.log_merge_count(lin_count, multi_count, binning=BINNING_MEAN)

Merges multi-tau count data. This function cab be used to obtain effective count data of results merged by log_merge(). You must first call equivalent count function, like ccorr_multi_count().

Parameters

  • lin_count (ndarray) – Linear data count

  • multi_count (ndarray) – Multilevel data count

  • binning (int) – Binning mode used in log_merge()

Returns

x, y – Time and log-spaced count arrays.

Return type

ndarray, ndarray

cddm.multitau.t_multilevel(shape, period=1)

Returns broadcasteable time array of multilevel data with a given shape

cddm.multitau.normalize_multi(data, background=None, variance=None, norm=None, mode='corr', scale=False, mask=None)

A multitau version of core.normalize().

Performs normalization of data returned by ccorr_multi(),

acorr_multi(),:func:iccorr_multi, or iacorr_multi() function.

See documentation of core.normalize().