{"id":24764915,"url":"https://github.com/landoskape/cellector","last_synced_at":"2025-10-11T14:30:51.691Z","repository":{"id":263610975,"uuid":"889087708","full_name":"landoskape/cellector","owner":"landoskape","description":"A pipeline and GUI for determining which ROIs match features in a fluorescence image.","archived":false,"fork":false,"pushed_at":"2025-06-02T13:35:59.000Z","size":712,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-24T21:59:23.274Z","etag":null,"topics":["cell","fluorescence","gui","image","matching","matching-algorithm","roi","roi-analysis"],"latest_commit_sha":null,"homepage":"https://cellector.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/landoskape.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-15T15:31:09.000Z","updated_at":"2025-06-02T13:35:38.000Z","dependencies_parsed_at":"2024-11-19T13:52:15.197Z","dependency_job_id":"d2a7905c-bd47-4fd7-a89a-70bb0f984516","html_url":"https://github.com/landoskape/cellector","commit_stats":null,"previous_names":["landoskape/cellector"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/landoskape/cellector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landoskape%2Fcellector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landoskape%2Fcellector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landoskape%2Fcellector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landoskape%2Fcellector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/landoskape","download_url":"https://codeload.github.com/landoskape/cellector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landoskape%2Fcellector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007457,"owners_count":26084313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cell","fluorescence","gui","image","matching","matching-algorithm","roi","roi-analysis"],"created_at":"2025-01-28T22:35:44.337Z","updated_at":"2025-10-11T14:30:51.684Z","avatar_url":"https://github.com/landoskape.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cellector\n[![PyPI version](https://badge.fury.io/py/cellector.svg)](https://badge.fury.io/py/cellector)\n[![Documentation Status](https://readthedocs.org/projects/cellector/badge/?version=stable)](https://cellector.readthedocs.io/en/stable/?badge=stable)\n[![Tests](https://github.com/landoskape/cellector/actions/workflows/test.yml/badge.svg)](https://github.com/landoskape/cellector/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/landoskape/cellector/branch/main/graph/badge.svg)](https://codecov.io/gh/landoskape/cellector)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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](https://github.com/landoskape/cellector/blob/main/notebooks/tutorial.ipynb).\nOtherwise, read the instructions below or look at the [documentation](https://cellector.readthedocs.io/). \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, check out\nthe explanation in the documentation files [here](https://cellector.readthedocs.io/en/latest/examples.html).\n\nIf 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](https://cellector.readthedocs.io/en/latest/gui.html).\n\n### Scripting\nThe GUI works, but it can be a bit tedious to open it over and over again when you know\nyou want the same settings for a group of sessions. To enable quick application of \nfeature criteria settings to many sessions, we have included scripting tools. \n\n```python\nfrom cellector.io import propgate_criteria\nfrom cellector.manager import CellectorManager\n\n# Copy criteria from suite2p_dir to all the other directories\nother_directories = [Path(r\"C:\\Path\\to\\other\\suite2p\"), Path(r\"C:\\Path\\to\\another\\suite2\"), ...] # as many as you like\nsuccess, failure = propagate_criteria(suite2p_dir, *other_directories)\n\nfor directory in other_directories:\n    # Make an roi_processor for each session(directory), this will compute features and save the data\n    roi_processor = create_from_suite2p(directory) # or whichever method you used to create the roi_processor\n    \n    # Make a manager instance\n    manager = CellectorManager.make_from_roi_processor(roi_processor)\n    \n    # this will save the updated criteria and idx_selection to cellector directory\n    # it will also save empty manual label arrays if they don't exist\n    manager.save_all() \n```\n\n### Handling convention changes in new versions\nSeveral changes will prevent or complicate backwards compatibility. Here's what you need\nto know:\n- `targetcell.npy` → `idx_selection.npy`: the name convention of the main output has been changed from targetcell.npy to idx_selection.npy\n- Manual selection shape from `(num_rois, 2)` to `(2, num_rois)`: manual selection is changed from a stack across labels and active_label\n- Feature files from `{feature_name}.npy` to `{feature_name}_feature.npy`: feature files now have a suffix for automatic identification\n- Criteria files from `{feature_name}_criteria.npy` to `{feature_name}_featurecriteria.npy`: criteria files suffix changed\n\nTo address these changes, version 1.0.0 includes migration utilities to fix existing data\nstructures. You can use ``identify_celector_folders`` to get all folders that contain a\ncellector directory. The other three functions operate on this list and fix the filenames\nor data structure (transposing manual selection) on all cellector files. These functions\nare in cellector/io/operations. \n```python\nfrom pathlib import Path\nfrom cellector.io import identify_cellector_folders\nfrom cellector.io import update_feature_paths\nfrom cellector.io import update_manual_selection_shape\nfrom cellector.io import update_idx_selection_filenames\ntop_level_dir = Path(r\"C:\\some\\path\\that\\has\\all\\the\\cellector\\directories\\beneath\\it\")\nroot_dirs = identify_cellector_folders(top_level_dir)\nupdate_idx_selection_filenames(root_dirs)\nupdate_manual_selection_shape(root_dirs)\nupdate_feature_paths(root_dirs)\n```\n\nNote that a few other things have changed in version 1.0.0, see the [CHANGELOG](https://github.com/landoskape/cellector/blob/main/CHANGELOG.md)\nfor more detailed descriptions!\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 \u0026 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandoskape%2Fcellector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flandoskape%2Fcellector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandoskape%2Fcellector/lists"}