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 (array, optional) – A boolean mask in which all non-zero values define the region of interest.
• polygons (array_like, optional) – Either an Nx2 np.array (single polygon), a list of array_like objects (multiple polygons), or a list of shapely Polygon class instances
• 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 (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.

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

>>> 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.,  1.],
       [ 1.,  1.],
       [ 1.,  0.],
       [ 0.,  0.]])]
>>> roi.mask.todense()
matrix([[ 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 Nx2 arrays

im_shape tuple

The shape of the image associated with the ROI. Determines the shape of the mask.

todict()

Returns the data in the ROI as a dictionary.

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

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')

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

Parameters:

• path (string) – Path to either a pickled ROIList or an ImageJ ROI zip file.
• fmt ({‘pkl’, ‘ImageJ’}) – The file format being imported.
• 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.

Returns:

sima.ROI.ROIList – Returns an ROIList loaded from the passed in path.

save(path, label=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.

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:

sima.ROI.ROIList – New ROIList with all filtered ROIs.

transform(transform, copy_properties=True)

Apply a 2x3 affine transformation to the ROIs

Parameters:

• transform (2x3 Numpy array) – The affine transformation to be applied to the ROIs.
• copy_properties (bool, optional) – Copy the label, id, tags, and im_shape properties from the source ROIs to the transformed ROIs

Returns:

sima.ROI.ROIList – Returns an ROIList consisting of the transformed ROI objects.