Regions of Interest

The roi_tools module provided a standardized ROI class to represent regions of interest in your imaging data. By having this standardized class, we can import ROIs from any arbitrary data structure. That is, we can load ROIs from any analysis software we want. A dictionary of ROIs can be easily formed using the default or custom ROI Handlers. Software-specific ROI Handlers are available for many major calcium imaging software packages and a metaclass is provided for customizing your own.

ROI instances

Each ROI instance contains the basic characteristics & properties of an ROI. Constructing an ROI requires only knowledge of its pixel coordinates. From these coordinates, a variety of attributes are calculated, including its centroid, radius, and approximate outline. Importantly, these attributes are only calculated at instantiation and then permanently cached for performance benefits. Therefore, changing the pixels of an existing ROI instance is not permitted. A properties attribute is provided to allow users to incorporate arbitrary information for a particular ROI (e.g., SNR). All keyword arguments will be passed to the properties attribute.

Generating an ROI instance

import numpy as np
from CalSciPy.roi_tools import ROI

x_pixels = [31, 31, 31, 32, 32, 32, 33, 33, 33]
y_pixels = [31, 32, 33, 31, 32, 33, 31, 32, 33]
reference_shape = (64, 64)
properties = {"cool_roi": True}

roi = ROI(x_pixels, y_pixels, reference_shape, properties, special_roi=True)

>>>print(f"{roi.radius=}")
roi.radius=1

>>>print(f"{roi.centroid=}")
roi.centroid=(32, 32)

>>>print(f"{roi.properties}")
roi.properties={'special_roi': True, 'cool_roi': True}

Importing ROIs from File

The ROI Handler metaclass describes a standardized approach to loading ROIs and can be adapted to handle any arbitrary data structure your ROIs may be stored in. Calling the load class method for any ROIHandler will generate a tuple containing a dictionary of ROIs and a reference image in the form of a numpy array with shape height x width. Each key of the dictionary is an integer indexing the ROI and its value-pair is the associated ROI. ROI Handlers for common analysis software are provided.

Suite2P

The Suite2P Handler is provided for loading suite2p data. It requires the path to a folder containing suite2p data as its only argument. The folder ought to contain at least the stat.npy and ops.npy files, although the iscell.npy file is also recommended.

Using the Suite2P Handler

from CalSciPy.roi_tools import Suite2PHandler

rois, reference_image = Suite2PHandler("file_location")