ROI Processor

class cellector.roi_processor.RoiProcessor(root_dir: Path | str, zpix: ndarray | List[ndarray], ypix: List[ndarray], xpix: List[ndarray], lam: List[ndarray], reference: ndarray, functional_reference: ndarray | None = None, extra_features: Dict[str, List[ndarray]] | None = None, volumetric: bool = False, autocompute: bool = True, use_saved: bool = True, save_features: bool = True, **kwargs: dict)

Bases: object

Process and analyze mask & fluorescence data across multiple image planes.

This class handles the processing of mask & fluorescence data by managing masks and reference images across multiple planes, providing functionality for feature calculation and analysis.

root_dir

Path to the root directory where the data is stored.

Type:

Path

zpix

Numpy array containing the plane index for each ROI. Or, if volumetric=True, a list of numpy arrays containing the z-pixel indices for each ROI.

Type:

Union[np.ndarray, List[np.ndarray]]

ypix

List of numpy arrays containing the y-pixel indices for each ROI.

Type:

List[np.ndarray]

xpix

List of numpy arrays containing the x-pixel indices for each ROI.

Type:

List[np.ndarray]

lam

List of numpy arrays containing the pixen intensities for each ROI.

Type:

List[np.ndarray]

reference

3D numpy array containing reference images for each plane.

Type:

np.ndarray

functional_reference

3D numpy array containing functional reference images for each plane (optional).

Type:

Union[np.ndarray, None]

lx, ly, lz

Dimensions of the imaging volume.

Type:

int

num_rois

Total number of ROIs across all planes.

Type:

int

features

Computed features for all ROIs.

Type:

dict

feature_pipeline_methods

Mapping of feature pipeline names to their corresponding methods.

Type:

dict

feature_pipeline_dependencies

Mapping of feature pipeline names to dependencies on attributes of roi_processor instances.

Type:

dict

parameters

Dictionary containing all the preprocessing parameters used.

Type:

dict

_cache

Dictionary containing cached values of attributes that are expensive to compute.

Type:

dict

compute_features(use_saved: bool = True)

Compute all registered features for each ROI.

FeaturePipelines are registered with the RoiProcessor instance, and each pipeline defines a method that computes a feature based on the attributes of the RoiProcessor instance. compute_features iterates over each pipeline and computes the feature values for each ROI. Resulting feature values are stored in the self.features dictionary.

Parameters:

use_saved (bool, optional) – If True, will attempt to load saved features from disk if they exist. Default is True.

add_feature(name: str, values: ndarray)

Add (or update) the name and values to the self.features dictionary.

Parameters:

• name (str) – Name of the feature.

• values (np.ndarray) – Feature values for each ROI. Must have the same length as the number of ROIs across all planes.

register_feature_pipeline(pipeline: FeaturePipeline)

Register a feature pipeline with the RoiProcessor instance.

pipeline is a FeaturePipeline object that defines a method to compute a feature based on the attributes of the RoiProcessor instance. The method should take the RoiProcessor instance as an argument and return a numpy array of feature values. The dependencies attribute of the pipeline object should be a list of strings indicating the attributes of the RoiProcessor instance that the method depends on. If any of these attributes are updated, the feature will be recomputed.

Parameters:

pipeline (FeaturePipeline) – FeaturePipeline object that defines a method to compute a feature based on the attributes of the RoiProcessor instance.

update_parameters(**kwargs: dict)

Update preprocessing parameters and clear affected cache entries.

Preprocessing parameters are used to compute properties of self that are cached upon first access, and also for feature computation. When parameters are updated, the cache entries that are affected by the change are cleared so they can be recomputed with the new parameters when accessed again. Features are automatically regenerated if they depend on the updated parameters and have already been computed.

Parameter dependencies are indicated in the PARAM_CACHE_MAPPING dictionary. Feature dependencies are indicated in the feature_pipeline_dependencies dictionary.

Parameters:

**kwargs (dict) – New values to update in the initial dictionary. Must be a subset of the keys in initial, otherwise a ValueError will be raised.

Returns:

Updated dictionary of parameters.

Return type:

dict

copy_with_params(params: dict)

Create a new processor instance with updated parameters.

Parameters:

params (dict) – New parameter values to update in the new instance. Must be a subset of the keys in DEFAULT_PARAMETERS, otherwise a ValueError will be raised.

Returns:

New instance of RoiProcessor with updated parameters.

Return type:

RoiProcessor

property centroids

Return the centroids of the ROIs in each plane.

Centroids are two lists of the y-centroid and x-centroid for each ROI, concatenated across planes. The centroid method is determined by the centroid_method attribute. Centroids are always returned as integers.

Returns:

Tuple of two numpy arrays, the y-centroids and x-centroids.

Return type:

Tuple[np.ndarray]

property centered_masks

Return the centered mask images for each ROI.

Returns:

The centered mask images of each ROI. If volumetric=False, has shape (numROIs, centered_width*2+1, centered_width*2+1). If volumetric=True, has shape (numROIs, num_planes, centered_width*2+1, centered_width*2+1).

Return type:

np.ndarray

property centered_reference

Return the centered reference image for each ROI.

Returns:

The centered reference image around each ROI. If volumetric=False, has shape (numROIs, centered_width*2+1, centered_width*2+1). If volumetric=True, has shape (numROIs, num_planes, centered_width*2+1, centered_width*2+1).

Return type:

np.ndarray

property filtered_reference

Return the filtered reference image for each ROI.

Uses a Butterworth bandpass filter to filter the reference image.

Returns:

The filtered reference image for each ROI, with shape (numROIs, lx, ly)

Return type:

np.ndarray

property filtered_centered_reference

Return the filtered centered reference image for each ROI.

Uses a Butterworth bandpass filter to filter the reference image, then generates a centered reference stack around each ROI using the filtered reference.

Returns:

The filtered centered reference image around each ROI, with shape (numROIs, centered_width*2+1, centered_width*2+1)

Return type:

np.ndarray

property centered_reference_functional

Return the centered reference image for each ROI based on the functional reference image.

Returns:

The centered reference image around each ROI, with shape (numROIs, centered_width*2+1, centered_width*2+1)

Return type:

np.ndarray

Raises:

ValueError – If functional reference are not available.

property filtered_reference_functional

Return the filtered reference image for each ROI based on the functional reference image.

Uses a Butterworth bandpass filter to filter the reference image.

Returns:

The filtered reference image for each ROI, with shape (numROIs, lx, ly)

Return type:

np.ndarray

Raises:

ValueError – If functional reference are not available.

property filtered_centered_reference_functional

Return the filtered centered reference image for each ROI based on the functional reference image.

Uses a Butterworth bandpass filter to filter the reference image, then generates a centered reference stack around each ROI using the filtered reference.

Returns:

The filtered centered reference image around each ROI, with shape (numROIs, centered_width*2+1, centered_width*2+1)

Return type:

np.ndarray

Raises:

ValueError – If functional reference are not available.