Table Of Contents

Search

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

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 an ‘id’ which is used for clustering or aligning ROIs across ROILists.

ROI.ROIList objects are a list-like container for storing multiple ROIs and includes methods for saving, loading, 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