Table Of Contents

Search

Enter search terms or a module, class or function name.

ImagingDataset objects

class sima.ImagingDataset(sequences, savedir, channel_names=None, read_only=False)

A multiple sequence imaging dataset.

Imaging data sets can be iterated over to generate sequences, 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 sequence in dataset:
...     for frame in sequence:
...         for plane in frame:
...             for row in plane:
...                 for column in row:
...                     for channel in column:
...                         pass

Datasets can also be indexed and sliced.

>>> dataset[0].num_sequences
1
>>> dataset[:, 0].num_frames
1
>>> dataset[:, 0].frame_shape == dataset.frame_shape
True

The resulting sliced datasets are not saved by default.

Parameters:
  • sequences (list of sima.Sequence) – Imaging sequences that can each be iterated over to yield the imaging data from each acquisition time.
  • 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’, ...].
num_sequences

int

The number of sequences in the ImagingDataset.

frame_shape

tuple of int

The shape of each frame, in order (num_planes, num_rows, num_columns, num_channels).

num_frames

int

The total number of image frames in the ImagingDataset.

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.

time_std

ndarray

The standard deviation of the intensity for each channel. Useful for knowing how dynamic each pixel is.

time_kurtosis

ndarray

The kurtosis of the intensity for each channel. Better than std deviation for knowing how dynamic each pixel is.

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, method=u'affine', source_channel=0, target_channel=0, source_label=None, target_label=None, anchor_label=None, copy_properties=True, pre_processing_method=None, pre_processing_kwargs=None, **method_kwargs)

Calculate a transformation that maps the source ImagingDataset onto this ImagingDataset, transforms the source ROIs by this mapping, and then imports 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.
  • method (string, optional) – Method to use for transform calculation.
  • 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
  • anchor_label (string, optional) – If None, use automatic dataset registration. Otherwise, the label of the ROIList that contains a single ROI with vertices defining anchor points common to both datasets.
  • copy_properties (bool, optional) – Copy the label, id, tags, and im_shape properties from the source ROIs to the transformed ROIs
  • pre_processing_method (string, optional) – pre-processing step applied before image registration
  • pre_processing_kwargs (dictionary, optional) – arguments for pre-processing of image
  • **method_kwargs –

    Additional arguments can be passed in specific to the particular method. For example, ‘order’ for a polynomial transform estimation.
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=u'TIFF16', scale_values=True, projection_type=u'average')

Save TIFF files with the time average of each channel.

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

Parameters:
  • filenames (str or list of str) – A single (.h5) output filename, or a list of (.tif) output filenames with one per channel.
  • fmt ({‘TIFF8’, ‘TIFF16’, ‘HDF5’}, 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.
  • projection_type ({‘average’, ‘std’, ‘kurtosis’}, optional) – Whether to take average z projection, the std z projection, or the kurtosis projection. std and kurtosis are useful for finding the dynamic pixels
export_frames(filenames, fmt=u'TIFF16', fill_gaps=True, scale_values=False, compression=None)

Export imaging data from the dataset.

Parameters:
  • filenames (list of 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][k] is the path to the file for sequence i, plane j, channel k. If fmt is ‘HDF5’, filenames[i] is the path to the file for the ith sequence.
  • 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. Channels are scaled separately.
  • compression ({None, ‘gzip’, ‘lzf’, ‘szip’}, optional) – If not None and ‘fmt’ is ‘HDF5’, compress the data with the specified lossless compression filter. See h5py docs for details on each compression filter.
export_signals(path, fmt=u'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, optional) – 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=1, demix_channel=None, save_summary=True)

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. Defaults to 1.
  • 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.
  • save_summary (bool, optional) – If True, additionally save a summary of the extracted ROIs.
Returns:

signals – The extracted signals along with parameters and values calculated during extraction. Contains the following keys:

raw, demixed_raw : list of arrays

The raw/demixed extracted signal. List of length num_sequences, each element is an array of shape (num_ROIs, num_frames).

mean_frame : array

Time-averaged mean frame of entire dataset.

overlap : tuple of arrays

Tuple of (rows, cols) such that zip(overlap) returns row, col pairs of pixel coordinates that are in more than one mask. Note: coordinates are for the **flattened* image, so ‘rows’ is always 0s.

signal_channel : int

The index of the channel that was extracted.

rois : list of dict

All the ROIs used for the extraction with the order matched to the order of the rows in ‘raw’. See sima.ROI.todict for details of dictionary format.

timestamp : string

Date and time of extraction in ‘%Y-%m-%d-%Hh%Mm%Ss’ format
Return type:

dict

See also

sima.ROI.ROI(), sima.ROI.ROIList()

save(savedir=None)

Save the ImagingDataset to a file.

segment(strategy, label=None, planes=None)

Segment an ImagingDataset to generate ROIs.

Parameters:
  • strategy (sima.segment.SegmentationStrategy) – The strategy for segmentation.
  • label (str, optional) – Label to be associated with the segmented set of ROIs.
  • planes (list of int) – List of the planes that are to be segmented.
Returns:

ROIs – The segmented regions of interest.
Return type:

sima.ROI.ROIList
signals(channel=0)

Return a dictionary of extracted signals

Parameters:channel (string or int) – The channel to load signals for, either an integer index or a string in self.channel_names
infer_spikes(channel=0, label=None, gamma=None, share_gamma=True, mode=u'correct', verbose=False)

Infer the most likely discretized spike train underlying a fluorescence trace.

Parameters:
  • channel (string or int, optional) – The channel to be used for spike inference.
  • label (string or None, optional) – Text string indicating the signals from which spikes should be inferred. Defaults to the most recently extracted signals.
  • gamma (float, optional) – Gamma is 1 - timestep/tau, where tau is the time constant of the AR(1) process. If no value is given, then gamma is estimated from the data.
  • share_gamma (bool, optional) – Whether to apply the same gamma estimate to all ROIs. Defaults to True.
  • mode ({‘correct’, ‘robust’, ‘psd’}, optional) – The method for estimating sigma. The ‘robust’ method overestimates the noise by assuming that gamma = 1. The ‘psd’ method estimates sigma from the PSD of the fluorescence data. Default: ‘correct’.
  • verbose (bool, optional) – Whether to print status updates. Default: False.
Returns:

  • spikes (ndarray of float) – The inferred normalized spike count at each time-bin. Values are normalized to the maximum value over all time-bins. Shape: (num_rois, num_timebins).
  • fits (ndarray of float) – The inferred denoised fluorescence signal at each time-bin. Shape: (num_rois, num_timebins).
  • parameters (dict of (str, ndarray of float)) – Dictionary with values for ‘sigma’, ‘gamma’, and ‘baseline’.

Notes

We strongly recommend installing MOSEK (www.mosek.com; free for academic use) which greatly speeds up the inference.

References

  • Pnevmatikakis et al. 2015. Submitted (arXiv:1409.2903).
  • Machado et al. 2015. Submitted.
  • Vogelstein et al. 2010. Journal of Neurophysiology. 104(6): 3691-3704.