droplets.droplet_tracks module

Classes representing the time evolution of droplets

DropletTrack

information about a single droplet over multiple time steps

DropletTrackList

a list of instances of DropletTrack
class DropletTrack(droplets=None, times=None)[source]

Bases: object

information about a single droplet over multiple time steps

Parameters:

  • emulsions (list) – List of emulsions that describe this time course

  • times (list) – Times associated with the emulsions

append(droplet, time=None)[source]

append a new droplet with a time code

Parameters:
Return type:

None

property data: np.ndarray | None

an array containing the data of the full track

Type:

ndarray

property dim: int | None

return the space dimension of the droplets

property duration: float

total duration of the track

Type:

float

property end: float

last time point

Type:

float

property first: SphericalDroplet

first droplet instance

Type:

SphericalDroplet

classmethod from_file(path)[source]

create droplet track by reading from file

Parameters:

path (str) – The path from which the data is read. This function assumes that the data was written as an HDF5 file using to_file().

Return type:

DropletTrack

get_position(time)[source]

ndarray: returns the droplet position at a specific time

Parameters:

time (float) –

Return type:

ndarray

get_radii(smoothing=0)[source]

ndarray: returns the droplet radius for each time point

Parameters:

smoothing (float) – Determines the length scale for some gaussian smoothing of the trajectory. The default value of zero disables smoothing.

Return type:

ndarray

get_trajectory(smoothing=0, *, attribute='position')[source]

return a the time-evolution of a droplet attribute (e.g., the position)

Parameters:

  • smoothing (float) – Determines the scale for some gaussian smoothing of the trajectory. The default value of zero disables smoothing.

  • attribute (str) – The attribute to consider (default: “position”).

Returns:

An array giving the position of the droplet at each

time instance

Return type:

ndarray

get_volumes(smoothing=0)[source]

ndarray: returns the droplet volume for each time point

Parameters:

smoothing (float) – Determines the volume scale for some gaussian smoothing of the trajectory. The default value of zero disables smoothing.

Return type:

ndarray

items()[source]

iterate over all times and droplets, returning them in pairs

property last: SphericalDroplet

last droplet instance

Type:

SphericalDroplet

plot(attribute='radius', smoothing=0, t_max=None, *args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)[source]

plot the time evolution of the droplet

Parameters:

  • attribute (str) – The attribute to plot. Typical values include radius and volume, but others might be defined on the droplet class.

  • smoothing (float) – Determines the scale for some gaussian smoothing of the trajectory. The default value of zero disables smoothing.

  • title (str) – Title of the plot. If omitted, the title might be chosen automatically.

  • filename (str, optional) – If given, the plot is written to the specified file.

  • action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.

  • ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.

  • fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.

  • ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

  • **kwargs – All remaining parameters are forwarded to the ax.plot method. For example, passing color=None, will use different colors for different droplets.

  • t_max (float | None) –

Returns:

Information about the plot

Return type:

PlotReference

plot_positions(grid=None, arrow=True, *args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)[source]

plot the droplet track

Parameters:

  • grid (GridBase, optional) – The grid on which the droplets are defined. If given, periodic boundary conditions can be respected in the plotting.

  • arrow (bool, optional) – Flag determining whether an arrow head is shown to indicate the direction of the droplet drift.

  • title (str) – Title of the plot. If omitted, the title might be chosen automatically.

  • filename (str, optional) – If given, the plot is written to the specified file.

  • action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.

  • ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.

  • fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.

  • ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

  • **kwargs – Additional keyword arguments are passed to the matplotlib plot function to affect the appearance. For example, passing color=None, will use different colors for different droplets.

Returns:

Information about the plot

Return type:

PlotReference

property start: float

first time point

Type:

float

time_overlaps(other)[source]

determine whether two DropletTrack instances overlaps in time

Parameters:

other (DropletTrack) – The other droplet track

Returns:

True when both tracks contain droplets at the same time step

Return type:

bool

to_file(path, info=None)[source]

store data in hdf5 file

The data can be read using the classmethod DropletTrack.from_file().

Parameters:

  • path (str) – The path to which the data is written as an HDF5 file.

  • info (dict) – Additional data stored alongside the droplet track list

Return type:

None

class DropletTrackList(iterable=(), /)[source]

Bases: list

a list of instances of DropletTrack

classmethod from_emulsion_time_course(time_course, *, method='overlap', grid=None, progress=False, **kwargs)[source]

obtain droplet tracks from an emulsion time course

Parameters:

  • time_course (droplets.emulsions.EmulsionTimeCourse) – A collection of temporally arranged emulsions

  • method (str) – The method used for tracking droplet identities. Possible methods are “overlap” (adding droplets that overlap with those in previous frames) and “distance” (matching droplets to minimize center-to-center distances).

  • grid (GridBase) – The grid on which the droplets are defined, which is necessary if periodic boundary conditions should be respected for measuring distances

  • progress (bool) – Whether to show the progress of the process.

  • **kwargs – Additional parameters for the tracking algorithm. Currently, one can only specify a maximal distance (using max_dist) for the “distance” method.

Returns:

the resulting droplet tracks

Return type:

DropletTrackList

classmethod from_file(path)[source]

create droplet track list by reading file

Parameters:

path (str) – The path from which the data is read. This function assumes that the data was written as an HDF5 file using to_file().

Returns:

an instance describing the droplet track list

Return type:

DropletTrackList

classmethod from_storage(storage, *, method='overlap', refine=False, num_processes=1, progress=None)[source]

obtain droplet tracks from stored scalar field data

This method first determines an emulsion time course and than collects tracks by tracking droplets.

Parameters:

  • storage (StorageBase) – The phase fields for many time instances

  • method (str) – The method used for tracking droplet identities. Possible methods are “overlap” (adding droplets that overlap with those in previous frames) and “distance” (matching droplets to minimize center-to-center distances).

  • refine (bool) – Flag determining whether the droplet properties should be refined using fitting. This is a potentially slow procedure.

  • num_processes (int or "auto") – Number of processes used for the refinement. If set to “auto”, the number of processes is choosen automatically.

  • progress (bool) – Whether to show the progress of the process. If None, the progress is not shown, except for the first step if refine is True.

Returns:

the resulting droplet tracks

Return type:

DropletTrackList

plot(attribute='radius', *args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)[source]

plot the time evolution of all droplets

Parameters:

  • attribute (str) – The attribute to plot. Typical values include radius and volume, but others might be defined on the droplet class.

  • title (str) – Title of the plot. If omitted, the title might be chosen automatically.

  • filename (str, optional) – If given, the plot is written to the specified file.

  • action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.

  • ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.

  • fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.

  • ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

  • **kwargs – Additional keyword arguments are passed to the matplotlib plot function to affect the appearance. The special value color=”cycle” implies that the default color cycle is used for the tracks, using different colors for different tracks.

Returns:

Information about the plot

Return type:

PlotReference

plot_positions(*args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)[source]

plot all droplet tracks

Parameters:

  • title (str) – Title of the plot. If omitted, the title might be chosen automatically.

  • filename (str, optional) – If given, the plot is written to the specified file.

  • action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.

  • ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.

  • fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.

  • ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

  • **kwargs – Additional keyword arguments are passed to the matplotlib plot function to affect the appearance.

Returns:

Information about the plot

Return type:

PlotReference

remove_short_tracks(min_duration=0)[source]

remove tracks that a shorter than a minimal duration

Parameters:

min_duration (float) – The minimal duration a droplet track must have in order to be retained. This is measured in actual time and not in the number of time steps stored in the track.

Return type:

None

to_file(path, info=None)[source]

store data in hdf5 file

The data can be read using the classmethod DropletTrackList.from_file().

Parameters:

  • path (str) – The path to which the data is written as an HDF5 file.

  • info (dict) – Additional data stored alongside the droplet track list

Return type:

None