cellector 0.1.0

A pipeline and GUI for determining which ROIs match features in a fluorescence image.

cellector

A pipeline and GUI for determining which ROIs match features in a fluorescence image. It is a common challenge in biology to determine whether a particular ROI (i.e. a collection of weighted pixels representing an inferred structure in an image) overlaps with features of a fluorescence image co-registered to the ROI. For example, in neuroscience, we might use suite2p to extract ROIs indicating active cells using a functional fluorophore like GCaMP, but want to know if the cells associated with those ROIs contain a secondary fluorophore like tdTomato. This package helps you do just that!

The package itself is somewhat simple, but we spent lots of time thinking about how to do this in the most reliable way. The standard pipeline computes a set of standard features for each ROI in comparison to a reference image which are useful for determining whether an ROI maps onto fluorescence. We provide a GUI for viewing the ROIs, the reference images, a distribution of feature values for each ROI, and an interactive system for deciding where to draw cutoffs on each feature to choose the ROIs that contain fluorescence. There's also a system for manual annotation if the automated system doesn't quite get it all right.

Installation

This package is installable with pip from PyPI. It is a lightweight package with minimal dependencies, so is probably compatible with other python environments you might use. If you're starting from scratch, first make a python environment, activate it, and install cellector with pip. If you are using an existing environment, skip the first two steps and just do pip install from within the environment.

conda create -n cellector
conda activate cellector
pip install cellector

Usage and Tutorial

The basic workflow of this package is as follows:

1. Construct an RoiProcessor object.
2. Use the SelectionGUI.
3. Save the data.
4. Repeat (or use scripting to speed up).

If you want to see the basic workflow in a notebook, look here. Otherwise, read the instructions below or look at the documentation which is very far from complete at the moment.

Basic instructions

We've provided a few functions to make RoiProcessor objects that work differently depending on what kind of data you are starting with. For an exhaustive list, go here. If you are working directly on the output of suite2p, use:

from cellector.io import create_from_suite2p
suite2p_dir = # define your suite2p path - the one with plane0, plane1, ... in it
roi_processor = create_from_suite2p(suite2p_dir)

Then, open the SelectionGUI as follows:

from cellector.gui import SelectionGUI
gui = SelectionGUI(roi_processor)

Then, use the GUI and hit save! Instructions for the GUI are coming.

Features in Progress

Hyperparameter Choices

There are a few "hyperparameters" to the package, including filtering parameters, the eps value for phase correlation, and size parameters for centered stacks. We need to enable hyperparameter optimization for these, which a user can supervise themselves. Idea: The user could open a GUI that compares masks with reference images for some sample "true" data and in addition for any data they've loaded in. One idea: For a particular set of hyperparameters (filtering, for example), the user could get a histogram of feature values for all the features for all the masks. They could use cutoff lines to pick a range of feature values for that particular set of hyperparameters, and then scroll through mask matches that come from within that range. This way, they could determine how the hyperparameters affect the feature values at each part of the distribution and select hyperparameters that give good separation. In addition, there could be some automated tuning, for example, to pick the eps a user could just input the maximum size ROI, and then measuring the average power for higher spatial frequencies.

Visualization of algorithm and filtering steps etc

To help choose hyperparameters and see how it's working, I'm going to build some tools to visualize masks and the reference image under different conditions.

Contributing

Feel free to contribute to this project by opening issues or submitting pull requests. It's already a collaborative project, so more minds are great if you have ideas or anything to contribute!

License & Citations

This project is licensed under the GNU License. If you use this repository as part of a publication, please cite us. There's no paper associated with the code at the moment, but you can cite our GitHub repository URL or email us for any updates about this issue.