# cellector
[](https://github.com/psf/black)
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](https://github.com/MouseLand/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.
```bash
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](./notebooks/tutorial.ipynb).
Otherwise, read the instructions below or look at the [documentation](./docs/examples.md)
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](./docs/examples.md). If you are working directly on the output of suite2p, use:
```python
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:
```python
from cellector.gui import SelectionGUI
gui = SelectionGUI(roi_processor)
```
Then, use the GUI and hit save! Instructions for the GUI are [here](./docs/gui.md).
#### Name convention updates
The first version of cellector used poor naming convention for saving features and
feature criteria. This has been rectified in version 0.2.0, but will create backward
incompatibility for any data files that were saved with the previous convention. To
address this, a few functions have been provided which can update the previous names to
follow the new convention called ``identify_cellector_folders`` and
``update_feature_paths``. You can use ``identify...`` to get all folders that contain a
cellector directory and ``update...`` to convert the filepaths to the new structure.
These functions are in cellector/io/operations.
```python
from pathlib import Path
from cellector.io.operations import identify_cellector_folders, update_feature_paths
top_level_dir = Path(r"C:\Users\Andrew\Documents")
cellector_folders = identify_cellector_folders(top_level_dir)
update_feature_paths(cellector_folders)
```
## 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "cellector",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.13,>=3.7",
"maintainer_email": null,
"keywords": "GUI, ROI, cell, feature, fluorescence, image, matching, pipeline",
"author": "Andrew T. Landau",
"author_email": "andrewtylerlandau@gmaildot.com",
"download_url": "https://files.pythonhosted.org/packages/8f/9f/564ef55abf9ae5340894c88fc7cd655a19e0b85540b4014ec9fa34bd990b/cellector-1.0.0.tar.gz",
"platform": null,
"description": "# cellector\n[](https://github.com/psf/black)\n\nA pipeline and GUI for determining which ROIs match features in a fluorescence image. It\nis a common challenge in biology to determine whether a particular ROI (i.e. a collection\nof weighted pixels representing an inferred structure in an image) overlaps with features\nof a fluorescence image co-registered to the ROI. For example, in neuroscience, we might\nuse [suite2p](https://github.com/MouseLand/suite2p) to extract ROIs indicating active\ncells using a functional fluorophore like GCaMP, but want to know if the cells associated\nwith those ROIs contain a secondary fluorophore like tdTomato. This package helps you do\njust that!\n\nThe package itself is somewhat simple, but we spent lots of time thinking about how to do\nthis in the most reliable way. The standard pipeline computes a set of standard features\nfor each ROI in comparison to a reference image which are useful for determining whether\nan ROI maps onto fluorescence. We provide a GUI for viewing the ROIs, the reference\nimages, a distribution of feature values for each ROI, and an interactive system for\ndeciding where to draw cutoffs on each feature to choose the ROIs that contain\nfluorescence. There's also a system for manual annotation if the automated system doesn't\nquite get it all right. \n\n## Installation\nThis package is installable with pip from PyPI. It is a lightweight package with minimal\ndependencies, so is probably compatible with other python environments you might use. \nIf you're starting from scratch, first make a python environment, activate it, and\ninstall ``cellector`` with pip. If you are using an existing environment, skip the first\ntwo steps and just do pip install from within the environment. \n```bash\nconda create -n cellector\nconda activate cellector\npip install cellector\n```\n\n## Usage and Tutorial\nThe basic workflow of this package is as follows:\n1. Construct an ``RoiProcessor`` object.\n2. Use the ``SelectionGUI``. \n3. Save the data.\n4. Repeat (or use scripting to speed up).\n\nIf you want to see the basic workflow in a notebook, look [here](./notebooks/tutorial.ipynb).\nOtherwise, read the instructions below or look at the [documentation](./docs/examples.md)\nwhich is very far from complete at the moment. \n\n#### Basic instructions\nWe've provided a few functions to make ``RoiProcessor`` objects that work differently\ndepending on what kind of data you are starting with. For an exhaustive list, go\n[here](./docs/examples.md). If you are working directly on the output of suite2p, use:\n```python\nfrom cellector.io import create_from_suite2p\nsuite2p_dir = # define your suite2p path - the one with plane0, plane1, ... in it\nroi_processor = create_from_suite2p(suite2p_dir)\n```\n\nThen, open the ``SelectionGUI`` as follows:\n```python\nfrom cellector.gui import SelectionGUI\ngui = SelectionGUI(roi_processor)\n```\n\nThen, use the GUI and hit save! Instructions for the GUI are [here](./docs/gui.md).\n\n#### Name convention updates\nThe first version of cellector used poor naming convention for saving features and\nfeature criteria. This has been rectified in version 0.2.0, but will create backward\nincompatibility for any data files that were saved with the previous convention. To\naddress this, a few functions have been provided which can update the previous names to\nfollow the new convention called ``identify_cellector_folders`` and \n``update_feature_paths``. You can use ``identify...`` to get all folders that contain a\ncellector directory and ``update...`` to convert the filepaths to the new structure.\nThese functions are in cellector/io/operations. \n```python\nfrom pathlib import Path\nfrom cellector.io.operations import identify_cellector_folders, update_feature_paths\ntop_level_dir = Path(r\"C:\\Users\\Andrew\\Documents\")\ncellector_folders = identify_cellector_folders(top_level_dir)\nupdate_feature_paths(cellector_folders)\n```\n\n## Features in Progress\n#### Hyperparameter Choices\nThere are a few \"hyperparameters\" to the package, including filtering parameters, the eps\nvalue for phase correlation, and size parameters for centered stacks. We need to enable \nhyperparameter optimization for these, which a user can supervise themselves. Idea:\nThe user could open a GUI that compares masks with reference images for some sample\n\"true\" data and in addition for any data they've loaded in. One idea:\nFor a particular set of hyperparameters (filtering, for example), the user could get a\nhistogram of feature values for all the features for all the masks. They could use cutoff\nlines to pick a range of feature values for that particular set of hyperparameters, and\nthen scroll through mask matches that come from within that range. This way, they could\ndetermine how the hyperparameters affect the feature values at each part of the\ndistribution and select hyperparameters that give good separation.\nIn addition, there could be some automated tuning, for example, to pick the eps a user\ncould just input the maximum size ROI, and then measuring the average power for higher\nspatial frequencies.\n\n#### Visualization of algorithm and filtering steps etc\nTo help choose hyperparameters and see how it's working, I'm going to build some tools to\nvisualize masks and the reference image under different conditions. \n\n## Contributing\nFeel free to contribute to this project by opening issues or submitting pull\nrequests. It's already a collaborative project, so more minds are great if you\nhave ideas or anything to contribute!\n\n## License & Citations\nThis project is licensed under the GNU License. If you use this repository as part of a\npublication, please cite us. There's no paper associated with the code at the moment, but\nyou can cite our GitHub repository URL or email us for any updates about this issue.\n",
"bugtrack_url": null,
"license": null,
"summary": "A pipeline and GUI for determining which ROIs match features in a fluorescence image.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/landoskape/cellector/issues",
"Homepage": "https://github.com/landoskape/cellector"
},
"split_keywords": [
"gui",
" roi",
" cell",
" feature",
" fluorescence",
" image",
" matching",
" pipeline"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "263b1358ccbccefd66ef3e038cbc010bbaaff13763b6873edf014bd32109f61e",
"md5": "3c28d328fd06f917f2f825db61d24b49",
"sha256": "66299044764d05fc8b1a814c41064222730d601da8c746ea8de21d2f250257a3"
},
"downloads": -1,
"filename": "cellector-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c28d328fd06f917f2f825db61d24b49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.13,>=3.7",
"size": 59307,
"upload_time": "2024-12-17T16:26:32",
"upload_time_iso_8601": "2024-12-17T16:26:32.659417Z",
"url": "https://files.pythonhosted.org/packages/26/3b/1358ccbccefd66ef3e038cbc010bbaaff13763b6873edf014bd32109f61e/cellector-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f9f564ef55abf9ae5340894c88fc7cd655a19e0b85540b4014ec9fa34bd990b",
"md5": "a96a17cabc961c633aad1d2fa60bec91",
"sha256": "3a0f57ae89e284f6a799884751b0e54328da26dcd349ccbaf6995ab3d8729d56"
},
"downloads": -1,
"filename": "cellector-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a96a17cabc961c633aad1d2fa60bec91",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.13,>=3.7",
"size": 461999,
"upload_time": "2024-12-17T16:26:34",
"upload_time_iso_8601": "2024-12-17T16:26:34.084153Z",
"url": "https://files.pythonhosted.org/packages/8f/9f/564ef55abf9ae5340894c88fc7cd655a19e0b85540b4014ec9fa34bd990b/cellector-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 16:26:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "landoskape",
"github_project": "cellector",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cellector"
}
JSON
