Regions of Interest (ROIs)

ROI and ROIList classes for storing and manipulating regions of interests (ROIs).

ROI.ROI objects allow for storing of ROIs as either as a boolean mask of included pixels, or as multiple polygons. Masks need not be continuous and an ROI can be defined by multiple non-adjacent polygons. In addition, each ROI can be assigned any number or ‘tags’ used to define features of the ROIs, as well as a ‘group’ which is used for clustering or aligning ROIs across ROILists.

ROI.ROIList object are a list-like container for storing multiple ROIs and includes methods for saving, sorting, and sub-grouping.

ROI class

class sima.ROI.ROI(mask=None, polygons=None, label=None, tags=None, id=None, im_shape=None)

Structure used to store ROIs

Parameters:

• mask (2D or 3D array or list of 2D arrays or of sparse matrices, optional) – A boolean mask in which all non-zero values define the region of interest. Masks are assumed to follow a (z, y, x) convention, corresponding to (plane, row, column) in the image.
• polygons (array_like, optional) – Either an Nx2 or Nx3 np.array (single polygon), a list of array_like objects (multiple polygons), a single shapely Polygon class instance, or a list of shapely Polygon class instances. Because polygons are stored internally as a shapely MultiPolygon, coordinates in this argument should follow an (x, y) or (x, y, z) convention.
• label (str, optional) – A label associated with the ROI for reference
• tags (list of str, optional) – A list of tags associated with the ROI.
• id (str, optional) – A unique identifier for the ROI. By default, the ROI will not have a unique identifier.
• im_shape (2- or 3-tuple, optional) – The shape of the image on which the ROI is drawn. If initialized with a mask, should be None, since im_shape will default to shape of the mask. Elements should correspond to (z, y, x), equivalent to (nPlanes, nRows, nCols)

Raises:

NonBooleanMask – Raised when you try to get a polygon representation of a non-boolean mask.

See also

sima.ROI.ROIList

Notes

ROI class instance must be initialized with either a mask or polygons (not both). If initialized with a polygon, im_shape must be defined before the ROI can be converted to a mask.

By convention polygon points are assumed to designate the top-left corner of a pixel (see example).

Examples

>>> import numpy as np
>>> from sima.ROI import ROI
>>> roi = ROI(polygons=[[0, 0], [0, 1], [1, 1], [1, 0]], im_shape=(2, 2))
>>> roi.coords
[array([[ 0.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 1.,  1.,  0.],
       [ 1.,  0.,  0.],
       [ 0.,  0.,  0.]])]
>>> np.array(roi)
array([[[ True, False],
        [False, False]]], dtype=bool)

id

string

The unique identifier for the ROI.

tags

set of str

The set of tags associated with the ROI.

label

string

A label associated with the ROI.

mask

array

A mask defining the region of interest.

polygons

MultiPolygon

A MultiPolygon representation of the ROI.

coords

list of arrays

Coordinates of the polygons as a list of Nx3 arrays (x, y, z)

im_shape

3-tuple

The shape of the image associated with the ROI (z, y, x). Determines the shape of the mask.

size

int

The number of non-zero pixel-weights in the ROI mask.

todict(type=None)

Returns the data in the ROI as a dictionary.

ROI(**roi.todict()) will return a new ROI equivalent to the original roi

Parameters:type ({‘mask’,’polygons’}, optional) – If specified, convert the type of each ROI in the list prior to saving

__array__()

Obtain a numpy.ndarray representation of the ROI mask.

Returns:mask – An array representation of the ROI mask. Return type:numpy.ndarray

ROIList class

class sima.ROI.ROIList(rois, timestamp=None)

A list-like container for storing multiple ROIs.

This class retains all the functionality inherited from Python’s built-in list class.

Parameters:

• rois (list of sima.ROI.ROI) – The ROIs in the set.
• timestamp (, optional) – The time at which the ROIList was created. Defaults to the current time.

See also

sima.ROI.ROI

timestamp

string

The timestamp for when the ROIList was created.

classmethod load(path, label=None, fmt='pkl', reassign_label=False)

Initialize an ROIList from either a saved pickle file or an Imagej ROI zip file.

Parameters:

• path (string) – Path to either a pickled ROIList, an ImageJ ROI zip file, or the path to the direcotry containing the ‘IC filter’ .mat files for inscopix/mosaic data.
• label (str, optional) – The label for selecting the ROIList if multiple ROILists have been saved in the same file. By default, the most recently saved ROIList will be selected.
• fmt ({‘pkl’, ‘ImageJ’, ‘inscopix’}) – The file format being imported.
• reassign_label (boolean) – If true, assign ascending integer strings as labels

Returns:

Returns an ROIList loaded from the passed in path.

Return type:

sima.ROI.ROIList

save(path, label=None, save_type=None)

Save an ROI set to a file. The file can contain multiple ROIList objects with different associated labels. If the file already exists, the ROIList will be added without deleting the others.

Parameters:

• path (str) – The name of the pkl file to which the ROIList will be saved.
• label (str, optional) – The label associated with the ROIList. Defaults to using the timestamp as a label.
• save_type ({‘mask’,’polygons’}, optional) – If specified, convert the type of each ROI in the list prior to saving

subset(tags=None, neg_tags=None)

Filter the ROIs in the set based on the ROI tags.

Parameters:

• tags (list of strings, optional) – Only ROIs that contain all of the tags will be included.
• neg_tags (list of strings, optional) – Only ROIs that contain none of the neg_tags will be included.

Returns:

New ROIList with all filtered ROIs.

Return type:

sima.ROI.ROIList

transform(transforms, im_shape=None, copy_properties=True)

Apply 2x3 affine transformations to the ROIs

Parameters:

• transforms (list of GeometryTransforms or 2x3 Numpy arrays) – The affine transformations to be applied to the ROIs. Length of list should equal the number of planes (im_shape[0]).
• im_shape (3-element tuple, optional) – The (zyx) shape of the target image. If None, must be set before any ROI can be converted to a mask.
• copy_properties (bool, optional) – Copy the label, id, and tags properties from the source ROIs to the transformed ROIs.

Returns:

Returns an ROIList consisting of the transformed ROI objects.

Return type:

sima.ROI.ROIList