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
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]
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: The headless version of opencv is installed by default. If
the regular version is already installed, you will need to uninstall it first.
3. Clone the repo to get the notebooks
git clone https://github.com/RichieHakim/ROICaT
Then, navigate to the ROICaT/notebooks/jupyter 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
Troubleshooting Installation
package installation issues
If you have issues importing packages like roicat or any of its dependencies, try reinstalling roicat with the following commands within the environment:
pip uninstall roicat
pip install --upgrade --force --no-cache-dir roicat[all]
HDBSCAN installation issues
If you are using Windows receive the error: ERROR: Could not build wheels for hdbscan, which is required to install pyproject.toml-based projects on Windows, make sure that you have installed Microsoft C++ Build Tools. If not, download from here and run the commands:
cd path/to/vs_buildtools.exe
vs_buildtools.exe --norestart --passive --downloadThenInstall --includeRecommended --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Workload.MSBuildTools
Then, try proceeding with the installation by rerunning the pip install commands above. (reference)
GPU support issues
GPU support is not required. Windows users will often need to manually install a CUDA version of pytorch (see below). Note that you can check your nvidia driver version using the shell command: nvidia-smi if you have drivers installed.
Use the following command to check your PyTorch version and if it is GPU enabled:
python -c "import torch, torchvision; print(f'Using versions: torch=={torch.__version__}, torchvision=={torchvision.__version__}'); print(f'torch.cuda.is_available() = {torch.cuda.is_available()}')"
Outcome 1: Output expected if GPU is enabled:
Using versions: torch==X.X.X+cuXXX, torchvision==X.X.X+cuXXX
torch.cuda.is_available() = True
This is the ideal outcome. You are using a CUDA version of PyTorch and your GPU is enabled.
Outcome 2: Output expected if non-CUDA version of PyTorch is installed:
Using versions: torch==X.X.X, torchvision==X.X.X
OR
Using versions: torch==X.X.X+cpu, torchvision==X.X.X+cpu
torch.cuda.is_available() = False
If a non-CUDA version of PyTorch is installed, please follow the instructions here: https://pytorch.org/get-started/locally/ to install a CUDA version. If you are using a GPU, make sure you have a CUDA compatible NVIDIA GPU and drivers that match the same version as the PyTorch CUDA version you choose. All CUDA 11.x versions are intercompatible, so if you have CUDA 11.8 drivers, you can install torch==2.0.1+cu117.
Solution: If you are sure you have a compatible GPU and correct drivers, you can force install the GPU version of pytorch, see the pytorch installation instructions. Links for the latest version or older versions. Example:
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
Outcome 3: Output expected if CUDA version of PyTorch is installed but GPU is not available:
Using versions: torch==X.X.X+cuXXX, torchvision==X.X.X+cuXXX
torch.cuda.is_available() = False
If a CUDA version of PyTorch is installed but GPU is not available, make sure you have a CUDA compatible NVIDIA GPU and drivers that match the same version as the PyTorch CUDA version you choose. All CUDA 11.x versions are intercompatible, so if you have CUDA 11.8 drivers, you can install torch==2.0.1+cu117.