Base SegmentationExtractors#

SegmentationExtractor#

Base segmentation extractors.

Classes#

SegmentationExtractor: Abstract class that contains all the meta-data and output data from the ROI segmentation operation when applied to the pre-processed data. It also contains methods to read from various data formats output from the processing pipelines like SIMA, CaImAn, Suite2p, CNMF-E.
SampleSlicedSegmentationExtractor: Class to get a lazy sample slice.

class SegmentationExtractor[source]#

Bases: ABC

Abstract segmentation extractor class.

An abstract class that contains all the meta-data and output data from the ROI segmentation operation when applied to the pre-processed data. It also contains methods to read from various data formats output from the output from the processing pipelines like SIMA, CaImAn, Suite2p, CNMF-E. All the methods with @abstract decorator have to be defined by the format specific classes that inherit from this.

Create a new SegmentationExtractor for a specific data format (unique to each child SegmentationExtractor).

get_accepted_list() → list[source]#

Get a list of accepted ROI ids.

Deprecated since version `get_accepted_list`: is deprecated and will be removed in May 2026. Use get_property() instead to access format-specific acceptance data.

Returns:: accepted_list – List of accepted ROI ids.
Return type:: list

get_rejected_list() → list[source]#

Get a list of rejected ROI ids.

Deprecated since version `get_rejected_list`: is deprecated and will be removed in May 2026. Use get_property() instead to access format-specific acceptance data.

Returns:: rejected_list – List of rejected ROI ids.
Return type:: list

abstract get_native_timestamps(start_sample: int | None = None, end_sample: int | None = None) → ndarray | None[source]#

Get the original timestamps from the data source.

Parameters:

start_sample (int, optional) – Start sample index (inclusive).
end_sample (int, optional) – End sample index (exclusive).

Returns:

timestamps – The original timestamps in seconds, or None if not available.

Return type:

np.ndarray or None

Get frame size of movie (height, width).

Returns:: frame_shape – 2-D array: image height x image width
Return type:: array_like

get_num_samples() → int[source]#

Get the number of samples in the recording (duration of recording).

Returns:: num_samples – Number of samples in the recording.
Return type:: int

get_roi_locations(roi_ids=None) → ndarray[source]#

Get the locations of the Regions of Interest (ROIs).

Parameters:: roi_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: roi_locs – 2-D array: 2 X no_ROIs. The pixel ids (x,y) where the centroid of the ROI is.
Return type:: numpy.ndarray

get_roi_ids() → list[source]#

Get the list of ROI ids.

Returns:: roi_ids – List of roi ids.
Return type:: list

get_roi_image_masks(roi_ids=None) → ndarray[source]#

Get the image masks extracted from segmentation algorithm.

Parameters:: roi_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: image_masks – 3-D array(val 0 or 1): image_height X image_width X length(roi_ids)
Return type:: numpy.ndarray

get_roi_pixel_masks(roi_ids=None) → array[source]#

Get the weights applied to each of the pixels of the mask.

Parameters:: roi_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: pixel_masks – List of length number of rois, each element is a 2-D array with shape (number_of_non_zero_pixels, 3). Columns 1 and 2 are the x and y coordinates of the pixel, while the third column represents the weight of the pixel.
Return type:: list

get_background_ids() → list[source]#

Get the list of background components ids.

Returns:: background_components_ids – List of background components ids.
Return type:: list

get_background_image_masks(background_ids=None) → ndarray[source]#

Get the background image masks extracted from segmentation algorithm.

Parameters:: background_ids (array_like) – A list or 1D array of ids of the background components. Length is the number of background components requested.
Returns:: background_image_masks – 3-D array(val 0 or 1): image_height X image_width X length(background_ids)
Return type:: numpy.ndarray

get_background_pixel_masks(background_ids=None) → array[source]#

Get the weights applied to each of the pixels of the mask.

Parameters:: background_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: pixel_masks – List of length number of rois, each element is a 2-D array with shape (number_of_non_zero_pixels, 3). Columns 1 and 2 are the x and y coordinates of the pixel, while the third column represents the weight of the pixel.
Return type:: list

slice_samples(start_sample: int | None = None, end_sample: int | None = None)[source]#

Return a new SegmentationExtractor ranging from the start_sample to the end_sample.

Parameters:

start_sample (int, optional) – Start sample index (inclusive).
end_sample (int, optional) – End sample index (exclusive).

Returns:

segmentation – The sliced SegmentationExtractor object.

Return type:

SampleSlicedSegmentationExtractor

select_rois(roi_ids: list[str | int])[source]#

Return a new SegmentationExtractor with only the specified ROIs.

Parameters:: roi_ids (list[str | int]) – List of ROI IDs to include. Can include both cell and background ROI IDs. The order of IDs is preserved in the returned extractor.
Returns:: segmentation – The ROI-sliced SegmentationExtractor object.
Return type:: RoiSlicedSegmentationExtractor
Raises:: ValueError – If roi_ids is empty or contains IDs not present in the extractor.

Notes

This method creates a lazy view of the segmentation data with a subset of ROIs. The slicing is applied to ROI-related data while temporal and spatial properties are preserved.

Examples

>>> # Select specific ROIs
>>> subset = extractor.select_rois([0, 1, 2])
>>>
>>> # Compose with temporal slicing
>>> subset = extractor.select_rois([0, 1, 2]).slice_samples(100, 200)

Get the traces of each ROI specified by roi_ids.

Parameters:

roi_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
start_frame (int) – The starting frame of the trace.
end_frame (int) – The ending frame of the trace.
name (str) – The name of the trace to retrieve ex. ‘raw’, ‘dff’, ‘neuropil’, ‘deconvolved’

Returns:

traces – 2-D array (ROI x timepoints)

Return type:

array_like

get_traces_dict() → dict[source]#

Get traces as a dictionary with key as the name of the ROiResponseSeries.

Returns:

_roi_response_dict –

dictionary with key, values representing different types of RoiResponseSeries:: Raw Fluorescence, DeltaFOverF, Denoised, Neuropil, Deconvolved, Background, etc.

Return type:

dict

get_images_dict() → dict[source]#

Get images as a dictionary with key as the name of the ROIResponseSeries.

Returns:

_roi_image_dict –

dictionary with key, values representing different types of Images used in segmentation:: Mean, Correlation image, Maximum projection, etc.

Return type:

dict

Get specific images: mean or correlation.

Parameters:: name (str) – name of the type of image to retrieve
Returns:: images
Return type:: numpy.ndarray

get_sampling_frequency() → float[source]#

Get the sampling frequency in Hz.

Returns:: sampling_frequency – Sampling frequency of the recording in Hz.
Return type:: float

get_num_rois() → int[source]#

Get total number of Regions of Interest (ROIs) in the acquired images.

Returns:: num_rois – The number of ROIs extracted.
Return type:: int

get_num_background_components() → int[source]#

Get total number of background components in the acquired images.

Returns:: num_background_components – The number of background components extracted.
Return type:: int

get_channel_names() → list[str][source]#

Get names of channels in the pipeline.

Returns:: _channel_names – names of channels (str)
Return type:: list

get_num_channels() → int[source]#

Get number of channels in the pipeline.

Returns:: num_of_channels – number of channels
Return type:: int

get_num_planes() → int[source]#

Get the default number of planes of imaging for the segmentation extractor.

Notes

Defaults to 1 for all but the MultiSegmentationExtractor.

Returns:: self._num_planes – number of planes
Return type:: int

Set the recording times in seconds for each frame.

Parameters:: times (array-like) – The times in seconds for each frame

Notes

Operates on _times attribute of the SegmentationExtractor object.

has_time_vector() → bool[source]#

Detect if the SegmentationExtractor has a time vector set or not.

Returns:: has_time_vector – True if the SegmentationExtractor has a time vector set, otherwise False.
Return type:: bool

get_timestamps(start_sample: int | None = None, end_sample: int | None = None) → ndarray[source]#

Retrieve the timestamps for the data in this extractor.

Parameters:

start_sample (int, optional) – The starting sample index. If None, starts from the beginning.
end_sample (int, optional) – The ending sample index. If None, goes to the end.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

Set property values for ROIs.

Parameters:

key (str) – The name of the property.
values (array-like) – Array of property values. Must have same length as ids and num_rois.
ids (array-like) – Array of ROI ids corresponding to the values. Must have same length as values and num_rois.

Get property values for ROIs.

Parameters:

key (str) – The name of the property.
ids (array-like) – Array of ROI ids to get property values for.

Returns:

values – Array of property values for the specified ROIs.

Return type:

array-like

get_property_keys() → list[str][source]#

Get list of available property keys.

Returns:: keys – List of property names.
Return type:: list

class SampleSlicedSegmentationExtractor(parent_segmentation: SegmentationExtractor, start_sample: int | None = None, end_sample: int | None = None)[source]#

Bases: SegmentationExtractor

Class to get a lazy sample slice.

Do not use this class directly but use .slice_samples(…) on a SegmentationExtractor object.

Initialize a SegmentationExtractor whose samples subset the parent.

Subset is exclusive on the right bound, that is, the indexes of this SegmentationExtractor range over [0, …, end_sample-start_sample-1], which is used to resolve the index mapping in get_traces(…).

Parameters:

parent_segmentation (SegmentationExtractor) – The SegmentationExtractor object to subset the samples of.
start_sample (int, optional) – The left bound of the samples to subset. The default is the start sample of the parent.
end_sample (int, optional) – The right bound of the samples, exclusively, to subset. The default is end sample of the parent.

get_native_timestamps(start_sample: int | None = None, end_sample: int | None = None) → ndarray | None[source]#

Get the original timestamps from the data source.

Parameters:

start_sample (int, optional) – Start sample index (inclusive).
end_sample (int, optional) – End sample index (exclusive).

Returns:

timestamps – The original timestamps in seconds, or None if not available.

Return type:

np.ndarray or None

get_frame_shape() → tuple[int, int][source]#

Get frame size of movie (height, width).

Returns:: frame_shape – 2-D array: image height x image width
Return type:: array_like

get_num_samples() → int[source]#

Get the number of samples in the recording (duration of recording).

Returns:: num_samples – Number of samples in the recording.
Return type:: int

get_roi_locations(roi_ids=None) → ndarray[source]#

Get the locations of the Regions of Interest (ROIs).

Parameters:: roi_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: roi_locs – 2-D array: 2 X no_ROIs. The pixel ids (x,y) where the centroid of the ROI is.
Return type:: numpy.ndarray

get_roi_ids() → list[source]#

Get the list of ROI ids.

Returns:: roi_ids – List of roi ids.
Return type:: list

get_roi_image_masks(roi_ids=None) → ndarray[source]#

Get the image masks extracted from segmentation algorithm.

Parameters:: roi_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: image_masks – 3-D array(val 0 or 1): image_height X image_width X length(roi_ids)
Return type:: numpy.ndarray

Get the weights applied to each of the pixels of the mask.

Parameters:: roi_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: pixel_masks – List of length number of rois, each element is a 2-D array with shape (number_of_non_zero_pixels, 3). Columns 1 and 2 are the x and y coordinates of the pixel, while the third column represents the weight of the pixel.
Return type:: list

get_background_ids() → list[source]#

Get the list of background components ids.

Returns:: background_components_ids – List of background components ids.
Return type:: list

get_background_image_masks(background_ids=None) → ndarray[source]#

Get the background image masks extracted from segmentation algorithm.

Parameters:: background_ids (array_like) – A list or 1D array of ids of the background components. Length is the number of background components requested.
Returns:: background_image_masks – 3-D array(val 0 or 1): image_height X image_width X length(background_ids)
Return type:: numpy.ndarray

Get the weights applied to each of the pixels of the mask.

Parameters:: background_ids (array_like) – A list or 1D array of ids of the ROIs. Length is the number of ROIs requested.
Returns:: pixel_masks – List of length number of rois, each element is a 2-D array with shape (number_of_non_zero_pixels, 3). Columns 1 and 2 are the x and y coordinates of the pixel, while the third column represents the weight of the pixel.
Return type:: list

get_num_rois() → int[source]#

Get total number of Regions of Interest (ROIs) in the acquired images.

Returns:: num_rois – The number of ROIs extracted.
Return type:: int

get_num_background_components() → int[source]#

Get total number of background components in the acquired images.

Returns:: num_background_components – The number of background components extracted.
Return type:: int

get_images_dict() → dict[source]#

Get images as a dictionary with key as the name of the ROIResponseSeries.

Returns:

_roi_image_dict –

dictionary with key, values representing different types of Images used in segmentation:: Mean, Correlation image, Maximum projection, etc.

Return type:

dict

Get specific images: mean or correlation.

Parameters:: name (str) – name of the type of image to retrieve
Returns:: images
Return type:: numpy.ndarray

get_sampling_frequency() → float[source]#

Get the sampling frequency in Hz.

Returns:: sampling_frequency – Sampling frequency of the recording in Hz.
Return type:: float

get_channel_names() → list[str][source]#

Get names of channels in the pipeline.

Returns:: _channel_names – names of channels (str)
Return type:: list

get_num_channels() → int[source]#

Get number of channels in the pipeline.

Returns:: num_of_channels – number of channels
Return type:: int

get_num_planes() → int[source]#

Get the default number of planes of imaging for the segmentation extractor.

Notes

Defaults to 1 for all but the MultiSegmentationExtractor.

Returns:: self._num_planes – number of planes
Return type:: int

has_time_vector() → bool[source]#

Detect if the SegmentationExtractor has a time vector set or not.

Returns:: has_time_vector – True if the SegmentationExtractor has a time vector set, otherwise False.
Return type:: bool

MultiSegmentationExtractor#

Defines the MultiSegmentationExtractor class.

Classes#

MultiSegmentationExtractor: This class is used to combine multiple SegmentationExtractor objects by frames.

concatenate_output(func)[source]#

Concatenate output of single SegmentationExtractor methods.

Parameters:: func (function) – function to be decorated
Returns:: _get_from_roi_map – decorated function
Return type:: function

class MultiSegmentationExtractor(segmentatation_extractors_list, plane_names=None)[source]#

Bases: SegmentationExtractor

Class is used to concatenate multi-plane recordings from the same device and session of experiment.

Initialize a MultiSegmentationExtractor object from a list of SegmentationExtractors.

Parameters:

segmentatation_extractors_list (list of SegmentationExtractor) – list of segmentation extractor objects (one for each plane)
plane_names (list) – list of strings of names for the plane. Defaults to ‘Plane0’, ‘Plane1’ …

property no_planes: int#

Number of planes in the recording.

Returns:: no_planes – number of planes in the recording
Return type:: int

property segmentations: list[SegmentationExtractor]#

List of segmentation extractors (one for each plane).

Returns:: segmentations – list of segmentation extractors (one for each plane)
Return type:: list

get_num_channels()[source]#

Get number of channels in the pipeline.

Returns:: num_of_channels – number of channels
Return type:: int

get_num_rois() → int[source]#

Get total number of Regions of Interest (ROIs) in the acquired images.

Returns:: num_rois – The number of ROIs extracted.
Return type:: int

get_images(name='correlation_plane0')[source]#

Get images from the imaging extractors.

Parameters:: name (str) – name of the image to get
Returns:: images – Array of images.
Return type:: numpy.ndarray

get_images_dict() → dict[source]#

Get images as a dictionary with key as the name of the ROIResponseSeries.

Returns:

_roi_image_dict –

dictionary with key, values representing different types of Images used in segmentation:: Mean, Correlation image, Maximum projection, etc.

Return type:

dict

get_traces_dict() → dict[source]#

Get traces as a dictionary with key as the name of the ROiResponseSeries.

Returns:

_roi_response_dict –

dictionary with key, values representing different types of RoiResponseSeries:: Raw Fluorescence, DeltaFOverF, Denoised, Neuropil, Deconvolved, Background, etc.

Return type:

dict

get_frame_shape() → tuple[int, int][source]#

Get frame size of movie (height, width).

Returns:: frame_shape – 2-D array: image height x image width
Return type:: array_like

get_traces(roi_ids=None, **kwargs)[source]#

Call member function of each SegmentationExtractor specified by func and concatenate the output.

Parameters:

roi_ids (list) – list of roi ids to be used
kwargs (dict) – keyword arguments to be passed to func

Returns:

out – list of outputs from each SegmentationExtractor

Return type:

list

get_roi_pixel_masks(roi_ids=None, **kwargs)[source]#

Call member function of each SegmentationExtractor specified by func and concatenate the output.

Parameters:

roi_ids (list) – list of roi ids to be used
kwargs (dict) – keyword arguments to be passed to func

Returns:

out – list of outputs from each SegmentationExtractor

Return type:

list

get_roi_image_masks(roi_ids=None, **kwargs)[source]#

Call member function of each SegmentationExtractor specified by func and concatenate the output.

Parameters:

roi_ids (list) – list of roi ids to be used
kwargs (dict) – keyword arguments to be passed to func

Returns:

out – list of outputs from each SegmentationExtractor

Return type:

list

get_roi_locations(roi_ids=None, **kwargs)[source]#

Call member function of each SegmentationExtractor specified by func and concatenate the output.

Parameters:

roi_ids (list) – list of roi ids to be used
kwargs (dict) – keyword arguments to be passed to func

Returns:

out – list of outputs from each SegmentationExtractor

Return type:

list

get_accepted_list() → list[int][source]#

Get a list of accepted ROI ids.

Deprecated since version `get_accepted_list`: is deprecated and will be removed in May 2026. Use get_property() instead to access format-specific acceptance data.

Returns:: accepted_list – List of accepted ROI ids.
Return type:: list

get_rejected_list() → list[int][source]#

Get a list of rejected ROI ids.

Deprecated since version `get_rejected_list`: is deprecated and will be removed in May 2026. Use get_property() instead to access format-specific acceptance data.

Returns:: rejected_list – List of rejected ROI ids.
Return type:: list

Base SegmentationExtractors#

SegmentationExtractor#

Classes#

MultiSegmentationExtractor#

Classes#

This Page