correlation Module

This module is for functions specific to time correlation

class skbeam.core.correlation.CrossCorrelator(shape, mask=None, normalization=None)

Compute a 1D or 2D cross-correlation on data.

This uses a mask, which may be binary (array of 0’s and 1’s), or a list of non-negative integer id’s to compute cross-correlations separately on.

The symmetric averaging scheme introduced here is inspired by a paper from Schätzel, although the implementation is novel in that it allows for the usage of arbitrary masks. [1]

References

1

Schätzel, Klaus, Martin Drewel, and Sven Stimac. “Photon correlation measurements at large lag times: improving statistical accuracy.” Journal of Modern Optics 35.4 (1988): 711-718.

Examples

>> ccorr = CrossCorrelator(mask.shape, mask=mask) >> # correlated image >> cimg = cc(img1) or, mask may may be ids >> cc = CrossCorrelator(ids) #(where ids is same shape as img1) >> cc1 = cc(img1) >> cc12 = cc(img1, img2) # if img2 shifts right of img1, point of maximum correlation is shifted # right from correlation center

skbeam.core.correlation.auto_corr_scat_factor(lags, beta, relaxation_rate, baseline=1)

This model will provide normalized intensity-intensity time correlation data to be minimized.

Parameters
lagsarray

delay time

betafloat

optical contrast (speckle contrast), a sample-independent beamline parameter

relaxation_ratefloat

relaxation time associated with the samples dynamics.

baselinefloat, optional

baseline of one time correlation equal to one for ergodic samples

Returns
g2array

normalized intensity-intensity time autocorreltion

References

1

L. Li, P. Kwasniewski, D. Orsi, L. Wiegart, L. Cristofolini, C. Caronna and A. Fluerasu, ” Photon statistics and speckle visibility spectroscopy with partially coherent X-rays,” J. Synchrotron Rad. vol 21, p 1288-1295, 2014

skbeam.core.correlation.lazy_one_time(image_iterable, num_levels, num_bufs, labels, internal_state=None)

Generator implementation of 1-time multi-tau correlation

If you do not want multi-tau correlation, set num_levels to 1 and num_bufs to the number of images you wish to correlate

Parameters
image_iterableiterable of 2D arrays
num_levelsint

how many generations of downsampling to perform, i.e., the depth of the binomial tree of averaged frames

num_bufsint, must be even

maximum lag step to compute in each generation of downsampling

labelsarray

Labeled array of the same shape as the image stack. Each ROI is represented by sequential integers starting at one. For example, if you have four ROIs, they must be labeled 1, 2, 3, 4. Background is labeled as 0

internal_statenamedtuple, optional

internal_state is a bucket for all of the internal state of the generator. It is part of the results object that is yielded from this generator

Yields
namedtuple

A results object is yielded after every image has been processed. This reults object contains, in this order:

  • g2: the normalized correlation shape is (len(lag_steps), num_rois)

  • lag_steps: the times at which the correlation was computed

  • _internal_state: all of the internal state. Can be passed back in to lazy_one_time as the internal_state parameter

Notes

The normalized intensity-intensity time-autocorrelation function is defined as

\[ \begin{align}\begin{aligned}g_2(q, t') = \frac{<I(q, t)I(q, t + t')> }{<I(q, t)>^2}\\t' > 0\end{aligned}\end{align} \]

Here, I(q, t) refers to the scattering strength at the momentum transfer vector q in reciprocal space at time t, and the brackets <...> refer to averages over time t. The quantity t' denotes the delay time

This implementation is based on published work. [1]

References

1

D. Lumma, L. B. Lurio, S. G. J. Mochrie and M. Sutton, “Area detector based photon correlation in the regime of short data batches: Data reduction for dynamic x-ray scattering,” Rev. Sci. Instrum., vol 71, p 3274-3289, 2000.

skbeam.core.correlation.lazy_two_time(labels, images, num_frames, num_bufs, num_levels=1, two_time_internal_state=None)

Generator implementation of two-time correlation

If you do not want multi-tau correlation, set num_levels to 1 and num_bufs to the number of images you wish to correlate

Multi-tau correlation uses a scheme to achieve long-time correlations inexpensively by downsampling the data, iteratively combining successive frames.

The longest lag time computed is num_levels * num_bufs.

See Also: multi_tau_auto_corr for a non-generator implementation

Parameters
labelsarray

labeled array of the same shape as the image stack; each ROI is represented by a distinct label (i.e., integer)

imagesiterable of 2D arrays

dimensions are: (rr, cc), iterable of 2D arrays

num_framesint

number of images to use default is number of images

num_bufsint, must be even

maximum lag step to compute in each generation of downsampling

num_levelsint, optional

how many generations of downsampling to perform, i.e., the depth of the binomial tree of averaged frames default is one

Yields
namedtuple

A results object is yielded after every image has been processed. This reults object contains, in this order:

  • g2: the normalized correlation shape is (num_rois, len(lag_steps), len(lag_steps))

  • lag_steps: the times at which the correlation was computed

  • _internal_state: all of the internal state. Can be passed back in to lazy_one_time as the internal_state parameter

Notes

The two-time correlation function is defined as

\[C(q,t_1,t_2) = \frac{<I(q,t_1)I(q,t_2)>}{<I(q, t_1)><I(q,t_2)>}\]

Here, the ensemble averages are performed over many pixels of detector, all having the same q value. The average time or age is equal to (t1+t2)/2, measured by the distance along the t1 = t2 diagonal. The time difference t = |t1 - t2|, with is distance from the t1 = t2 diagonal in the perpendicular direction. In the equilibrium system, the two-time correlation functions depend only on the time difference t, and hence the two-time correlation contour lines are parallel.

[1]

References

1

A. Fluerasu, A. Moussaid, A. Mandsen and A. Schofield, “Slow dynamics and aging in collodial gels studied by x-ray photon correlation spectroscopy,” Phys. Rev. E., vol 76, p 010401(1-4), 2007.

skbeam.core.correlation.multi_tau_auto_corr(num_levels, num_bufs, labels, images)

Wraps generator implementation of multi-tau

Original code(in Yorick) for multi tau auto correlation author: Mark Sutton

For parameter description, please reference the docstring for lazy_one_time. Note that there is an API difference between this function and lazy_one_time. The images argument is at the end of this function signature here for backwards compatibility, but is the first argument in the lazy_one_time() function. The semantics of the variables remain unchanged.

skbeam.core.correlation.one_time_from_two_time(two_time_corr)

This will provide the one-time correlation data from two-time correlation data.

Parameters
two_time_corrarray

matrix of two time correlation shape (number of labels(ROI’s), number of frames, number of frames)

Returns
one_time_corrarray

matrix of one time correlation shape (number of labels(ROI’s), number of frames)

skbeam.core.correlation.results

alias of skbeam.core.correlation.correlation_results

skbeam.core.correlation.two_time_corr(labels, images, num_frames, num_bufs, num_levels=1)

Wraps generator implementation of multi-tau two time correlation

This function computes two-time correlation Original code : author: Yugang Zhang

Returns
resultsnamedtuple
For parameter definition, see the docstring for the lazy_two_time()
function in this module
skbeam.core.correlation.two_time_state_to_results(state)

Convert the internal state of the two time generator into usable results

Parameters
statenamedtuple

The internal state that is yielded from lazy_two_time

Returns
resultsnamedtuple

A results object that contains the two time correlation results and the lag steps