ImagingDataset objects¶

Base classes for multiframe imaging data.

class sima.ImagingDataset(iterables, savedir, channel_names=None, metadata=None, displacements=None, trim_criterion=None, invalid_frames=None)¶

A multiple cycle imaging dataset.

Imaging data sets can be iterated over to generate cycles, which can in turn be iterated over to generate imaging frames.

Examples

>>> import sima 
...
>>> from sima.misc import example_data
>>> dataset = sima.ImagingDataset.load(example_data())

Datasets can be iterated over as follows:

>>> for cycle in dataset:
...     for frame in cycle:
...         for channel in frame:
...             for row in channel:
...                 for column in row:
...                         pass

Parameters:

iterables (list of list of iterable) – Iterables yielding frames from imaging cycles and channels.
savedir (str) – The directory used to store the dataset. If the directory name does not end with .sima, then this extension will be appended.
channel_names (list of str, optional) – Names for the channels. Defaults to [‘0’, ‘1’, ‘2’, ...].
metadata (dict) – Data for the order and timing of the data acquisition. See Notes for details.
displacements (list of array, optional)
trim_criterion (float, optional) – The required fraction of frames during which a location must be within the field of view for it to be included in the motion-corrected imaging frames. By default, only locations that are always within the field of view are retained. This argument only has effect if the ImagingDataset object is initialized with displacements.

frame_shape tuple of int¶: The shape of the data acquired for each frame, in order (num_planes, num_rows, num_columns).

num_cycles int¶: The number of cycles in the ImagingDataset.

num_channels int¶: The number of simultaneously recorded channels in the ImagingDataset.

num_columns int¶: The number of columns per image frame.

num_frames int¶: The total number of image frames in the ImagingDataset.

num_planes int¶: The number of imaging planes in the ImagingDataset.

num_rows int¶: The number of rows per image frame.

ROIs dict of (str, ROIList)¶: The sets of ROIs saved with this ImagingDataset.

time_averages list of ndarray¶: The time-averaged intensity for each channel.

invalid_frames list of list of int¶: The indices of the invalid frames in each cycle.

classmethod load(path)¶: Load a saved ImagingDataset object.

add_ROIs(ROIs, label=None)¶

Add a set of ROIs to the ImagingDataset.

Parameters:	ROIs (ROIList) – The regions of interest (ROIs) to be added. label (str, optional) – The label associated with the ROIList. Defaults to using the timestamp as a label.

Examples

Import an ROIList from a zip file containing ROIs created with NIH ImageJ.

>>> from sima.ROI import ROIList
>>> from sima.misc import example_imagej_rois,example_data
>>> from sima.imaging import ImagingDataset
>>> dataset = ImagingDataset.load(example_data())
>>> rois = ROIList.load(example_imagej_rois(), fmt='ImageJ')
>>> dataset.add_ROIs(rois, 'from_ImageJ')

import_transformed_ROIs(source_dataset, source_channel=0, target_channel=0, source_label=None, target_label=None, copy_properties=True)¶

Calculate an affine transformation that maps the source ImagingDataset onto this ImagingDataset, tranform the source ROIs by this mapping, and then import them into this ImagingDataset.

Parameters:

source_dataset (ImagingDataset) – The ImagingDataset object from which ROIs are to be imported. This dataset must be roughly of the same field-of-view as self in order to calculate an affine transformation.
source_channel (string or int, optional) – The channel of the source image from which to calculate an affine transformation, either an integer index or a string in source_dataset.channel_names.
target_channel (string or int, optional) – The channel of the target image from which to calculate an affine transformation, either an integer index or a string in self.channel_names.
source_label (string, optional) – The label of the ROIList to transform
target_label (string, optional) – The label to assign the transformed ROIList
copy_properties (bool, optional) – Copy the label, id, tags, and im_shape properties from the source ROIs to the transformed ROIs

delete_ROIs(label)¶

Delete an ROI set from the rois.pkl file

Removes the file if no sets left.

Parameters:	label (string) – The label of the ROI Set to remove from the rois.pkl file

export_averages(filenames, fmt='TIFF16', scale_values=True)¶

Save TIFF files with the time average of each channel.

For datasets with multiple frames, the resulting TIFF files have multiple pages.

Parameters:	filenames (list of str) – The (tif) filenames for saving the time averages. fmt ({‘TIFF8’, ‘TIFF16’}, optional) – The format of the output files. Defaults to 16-bit TIFF. scale_values (bool, optional) – Whether to scale the values to use the full range of the output format. Defaults to False.

export_frames(filenames, fmt='TIFF16', fill_gaps=True, scale_values=False)¶

Save a multi-page TIFF files of the motion-corrected time series.

# TODO: HDF5, multiple Z planes One TIFF file is created for each cycle and channel. The TIFF files have the same name as the uncorrected files, but should be saved in a different directory.

Parameters:

filenames (list of list of string or list of string) – Path to the locations where the output files will be saved. If fmt is TIFF, filenames[i][j] is the path to the file for the jth channel of the ith cycle. If fmt is ‘HDF5’, filenames[i] is the path to the file for the ith cycle
fmt ({‘TIFF8’, ‘TIFF16’, ‘HDF5’}, optional) – The format of the output files. Defaults to 16-bit TIFF.
fill_gaps (bool, optional) – Whether to fill in unobserved rows with data from adjacent frames. Defaults to True.
scale_values (bool, optional) – Whether to scale the values to use the full range of the output format. Defaults to False.

export_signals(path, fmt='csv', channel=0, signals_label=None)¶

Export extracted signals to a file.

Parameters:

path (str) – The name of the file that will store the exported data.
fmt ({‘csv’}, optional) – The export format. Currently, only ‘csv’ export is available.
channel (string or int) – The channel from which to export signals, either an integer index or a string in self.channel_names.
signals_label (str, optional) – The label of the extracted signal set to use. By default, the most recently extracted signals are used.

extract(rois=None, signal_channel=0, label=None, remove_overlap=True, n_processes=None, demix_channel=None)¶

Extracts imaging data from the current dataset using the supplied ROIs file.

Parameters:

rois (sima.ROI.ROIList, optional) – ROIList of rois to extract
signal_channel (string or int, optional) – Channel containing the signal to be extracted, either an integer index or a name in self.channel_names
label (string or None, optional) – Text label to describe this extraction, if None defaults to a timestamp.
remove_overlap (bool, optional) – If True, remove any pixels that overlap between masks.
n_processes (int, optional) – Number of processes to farm out the extraction across. Should be at least 1 and at most one less then the number of CPUs in the computer. If None, uses half the CPUs.
demix_channel (string or int, optional) – Channel to demix from the signal channel, either an integer index or a name in self.channel_names If None, do not demix signals.

Returns:

dict of arrays – Keys: raw, demixed_raw, mean_frame, overlap, signal_channel, rois, timestamp

Iterables¶

ImagingDataset objects must be initialized with iterable objects that satisfy the following properties:

The iterable should not be its own iterator, i.e. it should be able to spawn multiple iterators that can be iterated over independently.
Each iterator spawned from the iterable must yield image frames in the form of numpy arrays with shape (num_rows, num_columns).
Iterables must survive pickling and unpickling.

Examples of valid iterables include:

numpy arrays of shape (num_frames, num_rows, num_columns)

>>> import sima
>>> from numpy import ones
>>> frames = ones((100, 128, 128))
>>> sima.ImagingDataset([[frames]], None)
<ImagingDataset: num_channels=1, num_cycles=1, frame_size=128x128,
num_frames=100>

lists of numpy arrays of shape (num_rows, num_columns)

>>> frames = [ones((128, 128)) for _ in range(100)]
>>> sima.ImagingDataset([[frames]], None)
<ImagingDataset: num_channels=1, num_cycles=1, frame_size=128x128,
num_frames=100>

For convenience, we have created iterable objects that can be used with common data formats.

class sima.iterables.HDF5(path, dim_order, group=None, key=None, channel=None, clip=None)¶

Iterable for an HDF5 file containing imaging data.

Parameters:

path (str) – The HDF5 filename, typicaly with .h5 extension.
dim_order (str) – Specification of the order of the dimensions. This string can contain the letters ‘t’, ‘x’, ‘y’, ‘z’, and ‘c’, representing time, column, row, plane, and channel, respectively. For example, ‘tzyxc’ indicates that the HDF5 data dimensions represent time (t), plane (z), row (y), column(x), and channel (c), respectively. The string ‘tyx’ indicates data that data for a single imaging plane and single channel has been stored in a HDF5 dataset with three dimensions representing time (t), column (y), and row (x) respectively. Note that SIMA 0.1.x does not support multiple z-planes, although these will be supported in future versions.
group (str, optional) – The HDF5 group containing the imaging data. Defaults to using the root group ‘/’
key (str, optional) – The key for indexing the the HDF5 dataset containing the imaging data. This can be omitted if the HDF5 group contains only a single key.
channel (int, optional) – The index of the channel to be used. This can be omitted if there is no channel dimension specified by dim_order, or if the length along the channel dimension is just one.
clip (tuple of tuple of int, optional) – The number of rows/columns to clip from each edge in order ((top, bottom), (left, right)).

Warning

Moving the HDF5 file may make this iterable unusable when the ImagingDataset is reloaded. The HDF5 file can only be moved if the ImagingDataset path is also moved such that they retain the same relative position.

class sima.iterables.MultiPageTIFF(path, clip=None)¶

Iterable for a multi-page TIFF file in which the pages correspond to sequentially acquired image frames.

Parameters:	path (str) – The TIFF filename. clip (tuple of tuple of int, optional) – The number of rows/columns to clip from each edge in order ((top, bottom), (left, right)).

Warning

Moving the TIFF files may make this iterable unusable when the ImagingDataset is reloaded. The TIFF file can only be moved if the ImagingDataset path is also moved such that they retain the same relative position.

Table Of Contents

Search

ImagingDataset objects¶

Iterables¶

Navigation

Table Of Contents

Search

ImagingDataset objects¶

Iterables¶

Navigation