Welcome to ROICaT

🎉 CONTRIBUTIONS WELCOME! 🎉
See the TODO section

• Documentation: https://roicat.readthedocs.io/en/latest/.
• Overview:
• Discussion forum: https://groups.google.com/g/roicat_support
• Technical support: Github Issues

Region Of Interest Classification and Tracking ᗢ

A simple-to-use Python package for automatically classifying images of cells and tracking them across imaging sessions/planes.

Why use ROICaT?

• It's easy to use. You don't need to know how to code. You can use the interactive notebooks or online app to run the pipelines with just a few clicks.
• It's accurate. ROICaT was designed to be better than existing tools. It is capable of classifying and tracking neuron ROIs at accuracies approaching human performance out of the box.
• It's fast and computational requirements are low. You can run it on a laptop. It was designed to be used with >1M ROIs, and can utilize GPUs to speed things up.

With ROICaT, you can:

• Classify ROIs into different categories (e.g. neurons, dendrites, glia, etc.).
• Track ROIs across imaging sessions/planes (e.g. ROI #1 in session 1 is the same as ROI #7 in session 2).

What data types can ROICaT process?

• ROICaT can accept any imaging data format including: Suite2p, CaImAn, CNMF, NWB, raw/custom ROI data and more. See below for details on how to use any data type with ROICaT.

How to use ROICaT

TRACKING:

• Online App: Good for first time users. Try it out without installing anything.
• Interactive notebook (also available in colab)
• Command line interface script:

roicat --pipeline tracking --path_params /path/to/params.yaml --dir_data /folder/with/data/ --dir_save /folder/save/ --prefix_name_save expName --verbose

CLASSIFICATION:

• Interactive notebook - Drawing. (also available in colab) : Use mouse to draw circles around regions of a UMAP to classify ROIs.
• Interactive notebook - Simple interactive Labeling: Images of ROIs are displayed and you use the keyboard to manually label them.
• Interactive notebook - Interactive labeling with drawing: Draw circles around regions of a UMAP to subselect ROIs for manual labeling.
• Interactive notebook - Train classifier
• Interactive notebook - Inference with classifier
• Deploying a trained classifier

OTHER:

• Custom data importing notebook
• Use the API to integrate ROICaT functions into your own code: Documentation.
• Run the full tracking pipeline using the CLI or roicat.pipelines.pipeline_tracking with default parameters generated from roicat.util.get_default_parameters() saved as a yaml file.

Installation

ROICaT works on Windows, MacOS, and Linux. If you have any issues during the installation process, please make a github issue with the error.

0. Requirements

• Python 3.11, 3.12, or 3.13.
• Anaconda or Miniconda.
• The below commands should be run in the terminal (Mac/Linux) or Anaconda Prompt (Windows).

1. (Recommended) Create a new conda environment

conda create -n roicat python=3.12
conda activate roicat

You will need to activate the environment with conda activate roicat each time you want to use ROICaT.

2. Install ROICaT

pip install roicat[all]

That is the whole install. Everything ROICaT needs is included: both pipelines, the interactive plots, and Jupyter for running the notebooks. [core], [classification], [tracking] and [pinned] are all names for the same complete set, at the exact versions ROICaT is tested against.

Note on zsh: if you are using a zsh terminal, change command to: pip3 install --user 'roicat[all]'
Note on installing GPU support on Windows: see GPU Troubleshooting documentation.
Note on opencv: ROICaT installs the headless build of opencv, which has no GUI support and does not need one. If the regular build is already in your environment, uninstall it first -- the two provide the same cv2 module and pip cannot tell them apart.
Note for packages that depend on ROICaT: use pip install roicat[latest] instead. It installs the same packages with no version constraints, so ROICaT's pins do not propagate into your own dependency resolution.

3. Clone the repo to get the notebooks

git clone https://github.com/RichieHakim/ROICaT

Then, navigate to the ROICaT/notebooks directory to run the notebooks.

Quick Start

After installation, you can run the tracking pipeline with just a few lines of Python:

import roicat

# Run the tracking pipeline with default parameters
params = roicat.util.get_default_parameters(pipeline='tracking')
params['data_loading']['dir_outer'] = '/path/to/your/data/'
params['data_loading']['data_kind'] = 'suite2p'

results, run_data, params = roicat.pipelines.pipeline_tracking(params)

For more detailed usage, see the interactive notebooks or the documentation.

Upgrading versions

There are 2 parts to upgrading ROICaT: the Python package and the repository files which contain the notebooks and scripts.
Activate your environment first, then...
To upgrade the Python package, run:

pip install --upgrade roicat[all]

To upgrade the repository files, navigate your terminal to the ROICaT folder and run:

git pull

General workflow:

• Pass ROIs through ROInet: Images of the ROIs are passed through a neural network which outputs a feature vector for each image describing what the ROI looks like.
• Classification: The feature vectors can then be used to classify ROIs:
  • A simple regression-like classifier can be trained using user-supplied labeled data (e.g. an array of images of ROIs and a corresponding array of labels for each ROI).
  • Alternatively, classification can be done by projecting the feature vectors into a lower-dimensional space using UMAP and then simply circling the region of space to classify the ROIs.
• Tracking: The feature vectors can be combined with information about the position of the ROIs to track the ROIs across imaging sessions/planes.

Run the app locally

Although, we recommend transitioning to using the notebooks or CLI instead of the app, you can download and run the app locally with the following command:

sudo docker run -it -p 7860:7860 --platform=linux/amd64 --shm-size=10g registry.hf.space/richiehakim-roicat-tracking:latest streamlit run app.py

TODO:

algorithmic improvements:

• Add in method to use more similarity metrics for tracking
• [ ] Coordinate descent on each similarity metric
• Add F and Fneu to data_roicat, dFoF and trace quality metric functions
• Add in notebook for demonstrating using temporal similarity metrics (SWT on dFoF)
• Make a standard classifier
• Try other clustering methods
• Make image aligner based on image similarity + RANSAC of centroids or s_SF
• Better post-hoc curation metrics and visualizations
• Discount the non-rigid warp masks towards the edges to be more like the rigid warp map in order improve border performance
• Make non-rigid image registration optional

code improvements:

• Finish ROIextractors integration
• Update automatic regression module (make new repo for it)
• Switch to ONNX for ROInet
• Some more integration tests
• Figure out RNG / OS differences issues for tests
• Add more documentation / tutorials
• Make a GUI
• Add settings to the webapp GUI
• Make a Docker container
• Make colab demo notebook have demo data
• Make a better CLI
• Switch to pyproject.toml
• Improve params.json / default params system
• Spruce up training code
• Switch off pickling optuna save file
• Try training on cellpose datasets
• Python 3.13

other:

• Write the paper
• Make tweet about it
• Make a video or two on how to use it
• [ ] Maybe use lightthetorch for torch installation
• Better Readme
• More documentation
• Make a regression model for in-plane-ness
• Formalize bounty program