pept.processing.AutoCorrelation#

class pept.processing.AutoCorrelation(lag='t', signals=['vx', 'vy', 'vz'], span=None, num_divisions=500, max_distance=10, normalize=False, preprocess=True, **kwargs)[source]#

Bases: Reducer

Compute autocorrelation of multiple measures (eg YZ velocities) as a function of a lagging variable (eg time).

Reducer signature:

       PointData -> AutoCorrelation.fit -> PlotlyGrapher2D
 list[PointData] -> AutoCorrelation.fit -> PlotlyGrapher2D
list[np.ndarray] -> AutoCorrelation.fit -> PlotlyGrapher2D

Each sample in the input `PointData` is treated as a separate streamline / tracer pass. You can group passes using `Segregate + GroupBy(“label”)`.

Autocorrelation and autocovariance each refer to about 3 different things in each field. The formula used here, inspired by the VACF in molecular dynamics and generalised for arbitrary measures, is:

\[C(L_i) = \frac{ \sum_{N} V(L_0) \cdot V(L_i) }{N}\]

i.e. the autocorrelation C at a lag of Li is the average of the dot products of quantities V for all N tracers. For example, the velocity autocorrelation function with respect to time would be the average of vx(0) vx(t) + vy(0) vy(t) + vz(0) vz(t) at a given time t.

The input lag defines the column used as a lagging variable; it can be given as a named column string (e.g. “t”) or index (e.g. 0).

The input signals define the quantities for which the autocorrelation is computed, given as a list of column names (e.g. [“vy”, “vz”]) or indices (e.g. [5, 6]).

The input span, if defined, is the minimum and maximum values for the lag (e.g. start and end times) for which the autocorrelation will be computed. By default it is automatically computed as the range of values.

The input num_divisions is the number of lag points between span[0] and span[1] for which the autocorrelation will be computed.

The max_distance parameter defines the maximum distance allowed between a lag value and the closest trajectory value for it to be considered.

If normalize is True, then the formula used becomes:

\[C(L_i) = \frac{ \sum_{N} V(L_0) \cdot V(L_i) / V(L_0) \cdot V(L_0)}{N}\]

If preprocess is True, then the times of each tracer pass is taken relative to its start; only relevant if using time as the lagging variable.

The extra keyword arguments **kwargs are passed to PlotlyGrapher2D.add_points. You can e.g. set the YAxis limits by adding ylim = [0, 20].

The extra keyword arguments **kwargs are passed to plotly.graph_objs.Scatter. You can e.g. set a different colorscheme with “marker_colorscheme = ‘Viridis’”.

New in pept-0.5.1

Examples

Consider a pipe-flow experiment, with tracers moving from side to side in multiple passes / streamlines. First locate the tracers, then split their trajectories into each individual pass:

>>> import pept
>>> from pept.tracking import *
>>>
>>> split_pipe = pept.Pipeline([
>>>     Segregate(window = 10, max_distance = 20),  # Appends label column
>>>     GroupBy("label"),                           # Splits into samples
>>>     Reorient(),                                 # Align with X axis
>>>     Center(),                                   # Center points at 0
>>>     Velocity(7),                                # Compute vx, vy, vz
>>>     Stack(),
>>> ])
>>> streamlines = split_pipe.fit(trajectories)

Now each sample in streamlines corresponds to a single tracer pass, e.g. streamlines[0] is the first pass, streamlines[1] is the second. The passes were reoriented and centred such that the pipe is aligned with the X axis.

Now the AutoCorrelation algorithm can be used to compute the VACF:

>>> from pept.processing import AutoCorrelation
>>> fig = AutoCorrelation("t", ["vx", "vy", "vz"]).fit(streamlines)
>>> fig.show()

The radial velocity autocorrelation can be computed as a function of the pipe length (X axis as it was reoriented):

>>> entrance = -100
>>> exit = 100
>>> ac = AutoCorrelation("x", ["vy", "vz"], span = [entrance, exit])
>>> ac.fit(streamlines).show()

The raw lags and autocorrelations plotted can be accessed directly:

>>> ac.lags
>>> ac.correlation

The radial location can be autocorrelated with time, then normalised to show periodic movements (e.g. due to a mixer):

>>> ac = AutoCorrelation("t", ["y", "z"], normalize = True)
>>> ac.fit(streamlines).show()

__init__(lag='t', signals=['vx', 'vy', 'vz'], span=None, num_divisions=500, max_distance=10, normalize=False, preprocess=True, **kwargs)[source]#

Methods

`__init__`([lag, signals, span, ...])
`copy`([deep])	Create a deep copy of an instance of this class, including all inner attributes.
`fit`(trajectories[, executor, max_workers, ...])
`load`(filepath)	Load a saved / pickled PEPTObject object from filepath.
`save`(filepath)	Save a PEPTObject instance as a binary pickle object.

fit(trajectories, executor='joblib', max_workers=None, verbose=True)[source]#

copy(deep=True)#: Create a deep copy of an instance of this class, including all inner attributes.

static load(filepath)#

Load a saved / pickled PEPTObject object from filepath.

Most often the full object state was saved using the .save method.

Parameters

filepathfilename or file handle: If filepath is a path (rather than file handle), it is relative to where python is called.

Returns

pept.PEPTObject subclass instance: The loaded object.

Examples

Save a LineData instance, then load it back:

>>> lines = pept.LineData([[1, 2, 3, 4, 5, 6, 7]])
>>> lines.save("lines.pickle")

>>> lines_reloaded = pept.LineData.load("lines.pickle")

save(filepath)#

Save a PEPTObject instance as a binary pickle object.

Saves the full object state, including inner attributes, in a portable binary format. Load back the object using the load method.

Parameters

filepathfilename or file handle: If filepath is a path (rather than file handle), it is relative to where python is called.

Examples

Save a LineData instance, then load it back:

>>> lines = pept.LineData([[1, 2, 3, 4, 5, 6, 7]])
>>> lines.save("lines.pickle")

>>> lines_reloaded = pept.LineData.load("lines.pickle")