lumicks.pylake.correlated_stack.CorrelatedStack¶

class CorrelatedStack(*image_names, align=True)¶

CorrelatedStack acquired with Bluelake. Bluelake can export stacks of images to various formats. These can be opened and correlated to timeline data using CorrelatedStack.

Parameters

*image_names (str) – Filenames for the image stack. Typically a TIFF file recorded from a camera in Bluelake.
align (bool) – If enabled, multi-channel images will be reconstructed from the image alignment metadata from Bluelake. The default value is True.

Examples

from lumicks import pylake

# Loading a stack.
stack = pylake.CorrelatedStack("example.tiff")

# Making a plot where force is correlated to images in the stack.
file = pylake.File("example.h5")
stack.plot_correlated(file.force1x)

# Determine the force trace averaged over frame 2...9.
file.force1x.downsampled_over(stack[2:10].frame_timestamp_ranges())

# Loading multiple TIFFs into a stack.
stack = pylake.CorrelatedStack("example.tiff", "example2.tiff", "example3.tiff")

__getitem__(item)¶

Returns specific frame(s) and/or cropped stacks.

The first item refers to the camera frames; both indexing (by integer) and slicing are allowed, but using steps or slicing by a list is not. The last two items refer to the spatial dimensions in pixel rows and columns. Only full slices (without steps) are allowed. All values should be given in pixels.

Examples

import lumicks.pylake as lk

stack = lk.CorrelatedStack("test.tiff")

stack[5]  # Gets the 6th frame of the scan (0 is the first).
stack[1:5]  # Get scan frames 1, 2, 3 and 4.
stack[:, 10:50, 20:50]  # Gets all frames cropped from row 11 to 50 and column 21 to 50.
stack[:, 10:50]  # Gets all frames and all columns, but crops from row 11 to 50.
stack[5, 10:20, 10:20]  # Obtains the 6th frame and crops it.

stack[[1, 3, 4]]  # Produces an error, lists are not allowed.
stack[1:5:2]  # Produces an error, steps are not allowed.
stack[1, 3, 5]   # Error, integer indices are not allowed for the spatial dimensions.
stack[1, 3:5:2]  # Produces an error, steps are not allowed when slicing.

stack["1s":"5s"]  # Slice the stack from 1 to 5 seconds
stack[:"-5s"]  # Slice the stack up to the last 5 seconds

crop_and_rotate(frame=0, channel='rgb', show_title=True, **kwargs)¶

Open a widget to interactively edit the image stack.

Actions

scrolling through frames using the mouse wheel
left-click to define the location of the tether

Parameters

frame (int, optional) – Index of the frame to plot.
channel ('rgb', 'red', 'green', 'blue', None; optional) – Channel to plot for RGB images (None defaults to ‘rgb’) Not used for grayscale images
show_title (bool, optional) – Controls display of auto-generated plot title
**kwargs – Forwarded to matplotlib.pyplot.imshow().

Examples

from lumicks import pylake
import matplotlib.pyplot as plt

# Loading a stack.
stack = pylake.CorrelatedStack("example.tiff")
widget = stack.crop_and_rotate()
plt.show()

# Select cropping ROI by right-click drag
# Select tether ends by left-click

# Grab the updated image stack
new_stack = widget.image

crop_by_pixels(x_min, x_max, y_min, y_max)¶

Crop the image stack by pixel values.

Parameters

x_min (int) – minimum x pixel (inclusive, optional)
x_max (int) – maximum x pixel (exclusive, optional)
y_min (int) – minimum y pixel (inclusive, optional)
y_max (int) – maximum y pixel (exclusive, optional)

define_tether(point1, point2)¶

Returns a copy of the stack rotated such that the tether defined by point_1 and point_2 is horizontal.

Parameters

point_1 ((float, float)) – (x, y) coordinates of the tether start point
point_2 ((float, float)) – (x, y) coordinates of the tether end point

export_tiff(file_name)¶

Export a video of a particular scan plot

Parameters: file_name (str) – File name to export to.

export_video(channel, file_name, *, start_frame=None, stop_frame=None, fps=15, adjustment=<lumicks.pylake.adjustments.ColorAdjustment object>, **kwargs)¶

Export a video

Parameters

channel (str) – Color channel(s) to use “red”, “green”, “blue” or “rgb”.
file_name (str) – File name to export to.
start_frame (int) – First frame in exported video.
stop_frame (int) – Last frame in exported video.
fps (int) – Frame rate.
adjustment (lk.ColorAdjustment) – Color adjustments to apply to the output image.
**kwargs – Forwarded to matplotlib.pyplot.imshow().

frame_timestamp_ranges(*, include_dead_time=False)¶

Get start and stop timestamp of each frame in the stack.

Parameters: include_dead_time (bool) – Include dead time between frames.

classmethod from_data(data, name=None, start_idx=0, stop_idx=None)¶: Deprecated since version 0.10.1: Renamed to from_dataset() for consistency with Kymo and Scan.

classmethod from_dataset(data, name=None, start_idx=0, stop_idx=None, step=1) → lumicks.pylake.correlated_stack.CorrelatedStack¶

Construct CorrelatedStack from image stack object

Parameters

data (TiffStack) – TiffStack object.
name (str) – Plot label of the correlated stack
start_idx (int) – Index at the first frame.
stop_idx (int) – Index beyond the last frame.
step (int) – Step value for slicing frames.

get_image(channel='rgb')¶

Get image data for the full stack as an np.ndarray.

Parameters: channel ({'red', 'green', 'blue', 'rgb'}) – The color channel of the requested data. For single-color data, this argument is ignored.

plot(frame=0, channel='rgb', show_title=True, axes=None, adjustment=<lumicks.pylake.adjustments.ColorAdjustment object>, *, image_handle=None, **kwargs)¶

Plot image from image stack

Parameters

frame (int, optional) – Index of the frame to plot.
channel ('rgb', 'red', 'green', 'blue', None; optional) – Channel to plot for RGB images (None defaults to ‘rgb’) Not used for grayscale images
show_title (bool, optional) – Controls display of auto-generated plot title
axes (mpl.axes.Axes or None) – If supplied, the axes instance in which to plot.
image_handle (matplotlib.image.AxesImage or None) – Optional image handle which is used to update plots with new data rather than reconstruct them (better for performance).
**kwargs – Forwarded to matplotlib.pyplot.imshow().

plot_correlated(channel_slice, frame=0, reduce=<function mean>, channel='rgb', figure_scale=0.75, adjustment=<lumicks.pylake.adjustments.ColorAdjustment object>)¶

Downsample channel on a frame by frame basis and plot the results. The downsampling function (e.g. np.mean) is evaluated for the time between a start and end time of a frame.

Parameters

channel_slice (pylake.channel.Slice) – Data slice that we with to downsample.
frame (int) – Frame to show.
reduce (callable) – The function which is going to reduce multiple samples into one. The default is numpy.mean(), but numpy.sum() could also be appropriate for some cases e.g. photon counts.
channel ('rgb', 'red', 'green', 'blue', None; optional) – Channel to plot for RGB images (None defaults to ‘rgb’) Not used for grayscale images
figure_scale (float) – Scaling of the figure width and height. Values greater than one increase the size of the figure.
adjustment (lk.ColorAdjustment) – Color adjustments to apply to the output image.

Note

In environments which support interactive figures (e.g. jupyter notebook with ipywidgets or interactive python) this plot will be interactive.

Examples

from lumicks import pylake

file = pylake.File("example.h5")
stack = pylake.CorrelatedStack("example.tiff")
stack.plot_correlated(file.force1x, frame=5)

plot_tether(axes=None, **kwargs)¶

Plot a line at the tether position.

Parameters

axes (mpl.axes.Axes or None) – If supplied, the axes instance in which to plot.
**kwargs – Forwarded to matplotlib.pyplot.plot().

property num_frames¶: Number of frames in the stack.

property raw¶: Raw frame data.

Deprecated since version 0.10.1: Access to raw frame instances will be removed in a future release. All operations on these objects should be handled through the CorrelatedStack public API. For example, to retrieve the image data as an np.ndarray please use CorrelatedStack.get_image().

property start¶: Starting time stamp of the stack.

property stop¶: Final time stamp of the stack.

property timestamps¶: Get start and stop timestamp of each frame in the stack.

Deprecated since version 0.11.1: For camera based images only the integration start/stop timestamps are defined. Use CorrelatedStack.frame_timestamp_ranges() instead.