pept.processing.RelativeDeviationsLinear#

class pept.processing.RelativeDeviationsLinear(directory, p1, p2, num_divisions=50, max_distance=10, height=1000, width=2000, prefix='frame', **kwargs)[source]#

Bases: Reducer

Apply the RelativeDeviations mixing algorithm at num_divisions equidistant points between p1 and p2, saving histogram images at each step in directory.

Reducer signature:

       PointData -> LaceyColors.fit -> plotly.graph_objs.Figure
 list[PointData] -> LaceyColors.fit -> plotly.graph_objs.Figure
list[np.ndarray] -> LaceyColors.fit -> plotly.graph_objs.Figure

For details about the mixing algorithm itself, check the RelativeDeviations documentation.

This algorithm saves a rich set of data:

Individual histograms for each point along P1-P2 are saved in the given directory.
A Plotly figure of computed statistics is returned, including the deviations’ mean, standard deviation, skewness and kurtosis.
The raw data is saved as object attributes (see below).

The generated images (saved in directory with height x width pixels) can be stitched into a video using pept.plots.make_video.

The extra keyword arguments **kwargs are passed to the histogram creation routine pept.plots.histogram. You can e.g. set the YAxis limits by adding ylim = [0, 20].

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
>>>     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 RelativeDeviationsLinear reducer can be used to create images of the mixing between the pipe entrance and exit:

>>> from pept.processing import RelativeDeviationsLinear
>>> entrance = [-100, 0, 0]     # Pipe data was aligned with X and centred
>>> exit = [100, 0, 0]
>>> summary_fig = RelativeDeviationsLinear(
>>>     directory = "deviations",   # Creates directory to save images
>>>     p1 = entrance,
>>>     p2 = exit,
>>> ).fit(streamlines)
>>> summary_fig.show()              # Summary statistics: mean, std, etc.

Now the directory “deviations” was created inside your current working folder, and all relative deviation histograms were saved there as “frame0000.png”, “frame0001.png”, etc. You can stitch all images together into a video using pept.plots.make_video:

>>> import pept
>>> pept.plots.make_video(
>>>     "deviations/frame*.png",
>>>     output = "deviations/video.avi"
>>> )

The raw deviations and statistics can also be extracted directly:

>>> mixing_algorithm = RelativeDeviationsLinear(
>>>     directory = "deviations",   # Creates directory to save images
>>>     p1 = entrance,
>>>     p2 = exit,
>>> )
>>> fig = mixing_algorithm.fit(streamlines)
>>> fig.show()

>>> deviations = mixing_algorithm.deviations
>>> mean = mixing_algorithm.mean
>>> std = mixing_algorithm.std
>>> skew = mixing_algorithm.skew
>>> kurtosis = mixing_algorithm.kurtosis

Attributes

deviationslist[(N,) np.ndarray]: A list of deviations computed by RelativeDeviations at each point between P1 and P2.
mean(N,) np.ndarray: A vector of mean tracer deviations at each point between P1 and P2.
std(N,) np.ndarray: A vector of the tracer deviations’ standard deviation at each point between P1 and P2.
skew(N,) np.ndarray: A vector of the tracer deviations’ adjusted skewness at each point between P1 and P2. A normal distribution has a value of 0; positive values indicate a longer right distribution tail; negative values indicate a heavier left tail.
kurtosis(N,) np.ndarray: A vector of the tracer deviations’ Fisher kurtosis at each point between P1 and P2. A normal distribution has a value of 0; positive values indicate a “thin” distribution; negative values indicate a heavy, wide distribution.

__init__(directory, p1, p2, num_divisions=50, max_distance=10, height=1000, width=2000, prefix='frame', **kwargs)[source]#

Methods

`__init__`(directory, p1, p2[, num_divisions, ...])
`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")