pept.processing.RelativeDeviations#

class pept.processing.RelativeDeviations(p1, p2, ax1=None, ax2=None, max_distance=10, histogram=True, **kwargs)[source]#

Bases: Reducer

Compute a Lagrangian mixing measure - the changes in tracer distances to a point P1 as they pass through an “inlet” plane and another point P2 when reaching an “outlet” plane.

A deviation is computed for each tracer trajectory, yielding a range of deviations that can e.g be histogrammed (default). Intuitively, mixing is stronger if this distribution of deviations is wider.

Reducer signature:

If ``histogram = True`` (default)
       PointData -> LaceyColors.fit -> plotly.graph_objs.Figure
 list[PointData] -> LaceyColors.fit -> plotly.graph_objs.Figure
list[np.ndarray] -> LaceyColors.fit -> plotly.graph_objs.Figure

If ``histogram = False`` (return deviations)
       PointData -> LaceyColors.fit -> (N,) np.ndarray
 list[PointData] -> LaceyColors.fit -> (N,) np.ndarray
list[np.ndarray] -> LaceyColors.fit -> (N,) np.ndarray

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

The first plane where the distances from tracers to a point p1 is defined by the point p1 and direction axis ax1. The point `p1` should be the middle of the pipe.

The second plane where relative distances are evaluated is similarly defined by p2 and ax2. The point `p2` should be the middle of the volume / pipe.

If the direction vectors ax1 and ax2 are undefined (None), the tracers are assumed to follow a straight line between p1 and p2.

The max_distance parameter defines the maximum distance allowed between a point and a plane to be considered part of it. The resolution defines the number of pixels in the height and width of the resulting image.

The following attributes are always set. A Plotly figure is only generated and returned if histogram = True (default).

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 RelativeDeviations reducer can be used to create a histogram of tracer deviations due to mixing:

>>> from pept.processing import RelativeDeviations
>>> entrance = [-100, 0, 0]     # Pipe data was aligned with X and centred
>>> exit = [100, 0, 0]
>>> fig = RelativeDeviations(entrance, exit).fit(streamlines)
>>> fig.show()

The deviations themselves can be extracted directly for further processing:

>>> mixing_algorithm = RelativeDeviations(entrance, exit, histogram=False)
>>> mixing_algorithm.fit(streamlines)
>>> deviations = mixing_algorithm.deviations
>>> inlet_points = mixing_algorithm.points1
>>> outlet_points = mixing_algorithm.points2
Attributes
points1pept.PointData

The tracer points selected at the inlet around p1.

points2pept.PointData

The tracer points selected at the outlet around p2.

deviations(N,) np.ndarray

The vector of tracer deviations for each tracer pass in points1 and points2.

__init__(p1, p2, ax1=None, ax2=None, max_distance=10, histogram=True, **kwargs)[source]#

Methods

__init__(p1, p2[, ax1, ax2, max_distance, ...])

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")