-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #199 from RichieHakim/dev
Update documentation to use MyST embedding
- Loading branch information
Showing
8 changed files
with
49 additions
and
202 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,70 +1,7 @@ | ||
| How to use ROICaT | ||
| ================= | ||
|
|
||
| Listed below, we have a suite of easy to run notebooks for running the ROICaT | ||
| pipelines. | ||
|
|
||
| * The **Google CoLab notebooks** can be run fully remotely without installing | ||
| anything on your computer. | ||
| * The **Jupyter notebooks** can be run locally on your computer and require you to | ||
| `install ROICaT | ||
| <https://roicat.readthedocs.io/en/latest/installation.html>`__. | ||
|
|
||
| .. image:: ../media/tracking_FOV_clusters_rich.gif | ||
| :align: right | ||
| :width: 300 | ||
| :alt: ROICaT logo_1 | ||
|
|
||
| **TRACKING:** | ||
| * `Interactive notebook <https://github.com/RichieHakim/ROICaT/blob/main/notebooks/jupyter/tracking/tracking_interactive_notebook.ipynb>`__ | ||
| * `Google CoLab <https://githubtocolab.com/RichieHakim/ROICaT/blob/main/notebooks/colab/tracking/tracking_interactive_notebook.ipynb>`__ | ||
| * (TODO) `demo script <https://github.com/RichieHakim/ROICaT/blob/main/notebooks/jupyter/tracking/tracking_scripted_notebook.ipynb>`__ | ||
|
|
||
| | | ||
| .. image:: ../media/umap_with_labels.png | ||
| :align: right | ||
| :width: 200 | ||
| :alt: ROICaT logo_1 | ||
|
|
||
| **CLASSIFICATION:** | ||
| * `Interactive notebook - Drawing <https://github.com/RichieHakim/ROICaT/blob/main/notebooks/jupyter/classification/classify_by_drawingSelection.ipynb>`__ | ||
| * `Google CoLab - Drawing <https://githubtocolab.com/RichieHakim/ROICaT/blob/main/notebooks/colab/classification/classify_by_drawingSelection_colab.ipynb>`__ | ||
| * `Interactive notebook - Labeling <https://github.com/RichieHakim/ROICaT/blob/main/notebooks/jupyter/classification/labeling_interactive.ipynb>`__ | ||
| * (TODO) `Interactive notebook - Train classifier <https://github.com/RichieHakim/ROICaT>`__ | ||
| * (TODO) `Interactive notebook - Inference with classifier <https://github.com/RichieHakim/ROICaT>`__ | ||
|
|
||
| | | ||
| **OTHER:** | ||
| * `Custom data importing notebook <https://github.com/RichieHakim/ROICaT/blob/main/notebooks/jupyter/other/demo_data_importing.ipynb>`__ | ||
| * Train a new ROInet model using the provided Jupyter Notebook [TODO: link]. | ||
| * Use the API to integrate ROICaT functions into your own code: `Documentation <https://roicat.readthedocs.io/en/latest/roicat.html>`__. | ||
|
|
||
| How ROICaT pipelines work: | ||
| ########################## | ||
|
|
||
| * **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. These feature vectors are used in the next steps. | ||
| * **Classification:** | ||
| * A simple **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 | ||
| **drawing** a circle around 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. | ||
|
|
||
|
|
||
| ROInet model data | ||
| ################# | ||
|
|
||
| Below are links to the current ROInet models. These models are trained on data | ||
| from many labs from around the world. They take in images of ROIs and output a | ||
| feature vector describing each ROI. See documentation on the `ROInet_embedder | ||
| <https://roicat.readthedocs.io/en/latest/roicat.html#roicat.ROInet.ROInet_embedder>`__ | ||
| for more information on how to use these models. | ||
|
|
||
| .. include:: ../helpers/ROInet_links.txt | ||
| .. include:: ../../README.md/ | ||
| :start-after: # How to use ROICaT | ||
| :end-before: # Installation | ||
| :parser: myst_parser.sphinx_ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,136 +1,16 @@ | ||
| Installation | ||
| ============ | ||
|
|
||
| ROICaT has been tested on Windows 10 & 11, MacOS, and Linux. | ||
|
|
||
| Requirements | ||
| ############ | ||
|
|
||
| - Segmented data. For example Suite2p output data (stat.npy and ops.npy files), | ||
| CaImAn output data (results.h5 files), or any other type of data using this | ||
| `custom data importing notebook | ||
| <https://github.com/RichieHakim/ROICaT/blob/main/notebooks/jupyter/other/demo_custom_data_importing.ipynb>`__. | ||
| - `Anaconda <https://www.anaconda.com/distribution/>`__ or `Miniconda | ||
| <https://docs.conda.io/en/latest/miniconda.html>`__. | ||
| - If using Windows: `Microsoft C++ Build Tools | ||
| <https://visualstudio.microsoft.com/visual-cpp-build-tools/>`__ | ||
| - If using linux/unix: GCC >= 5.4.0, ideally == 9.2.0. Google how to do this on | ||
| your operating system. Check with: ``gcc --version``. | ||
| - **Optional:** `CUDA compatible NVIDIA GPU | ||
| <https://developer.nvidia.com/cuda-gpus>`__ and `drivers | ||
| <https://developer.nvidia.com/cuda-toolkit-archive>`__. Using a GPU can | ||
| increase ROICaT speeds ~5-50x, though without it, ROICaT will still run | ||
| reasonably quick. GPU support is not available for Macs. | ||
| - The below commands should be run in the terminal (Mac/Linux) or Anaconda | ||
| Prompt (Windows). | ||
|
|
||
|
|
||
| Installation | ||
| ############ | ||
|
|
||
|
|
||
| 1. **Recommended: Create a new conda environment** | ||
|
|
||
| .. literalinclude:: ../helpers/create_env.txt | ||
|
|
||
| You will need to activate the environment with ``conda activate roicat`` each | ||
| time you want to use ROICaT. | ||
|
|
||
| 2. **Install ROICaT** | ||
|
|
||
| .. literalinclude:: ../helpers/pip_install.txt | ||
|
|
||
| Note: if you are using a zsh terminal, add quotes around the pip install | ||
| command, i.e. ``pip install "roicat[all]"`` | ||
|
|
||
| 3. **Clone the repo to get the scripts and notebooks** | ||
|
|
||
| .. literalinclude:: ../helpers/clone_repo.txt | ||
|
|
||
| .. include:: ../../README.md/ | ||
| :start-after: # Installation | ||
| :end-before: # Troubleshooting Installation | ||
| :parser: myst_parser.sphinx_ | ||
|
|
||
|
|
||
| Troubleshooting Installation | ||
| ############################ | ||
|
|
||
| Windows installation | ||
| --------------------- | ||
|
|
||
| If you 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 <https://visualstudio.microsoft.com/visual-cpp-build-tools/>`__ | ||
| 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 <https://stackoverflow.com/questions/64261546/how-to-solve-error-microsoft-visual-c-14-0-or-greater-is-required-when-inst>`__) | ||
|
|
||
|
|
||
| GPU support | ||
| ----------- | ||
|
|
||
| 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 <https://developer.nvidia.com/cuda-gpus>`__ and | ||
| `drivers <https://developer.nvidia.com/cuda-toolkit-archive>`__ 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``. | ||
|
|
||
| **Outcome 3:** Output expected if 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 <https://developer.nvidia.com/cuda-gpus>`__ and | ||
| `drivers <https://developer.nvidia.com/cuda-toolkit-archive>`__ 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``. | ||
| .. include:: ../../README.md/ | ||
| :start-after: # Troubleshooting Installation | ||
| :end-before: # TODO | ||
| :parser: myst_parser.sphinx_ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters