Merge pull request #20 from TravisWheelerLab/installation-instructions

Installation instructions

Author: georgeglidden

README.md

@@ -21,32 +21,7 @@ DIPLOMAT provides a multi-animal pose estimation and editing interface. It relie
 | ![Example of tracking 2 Degus](https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/docs/source/_static/imgs/example1.png) | ![Example of tracking 3 Rats](https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/docs/source/_static/imgs/example2.png) |
 ## Installation
 
-DIPLOMAT also includes four environment configuration files for setting up DIPLOMAT with 
-[mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html), which can
-be installed on Windows, Linux, or MacOS using the [Miniforge](https://github.com/conda-forge/miniforge) installer.
-To create an environment using mamba, run one of these four commands:
-```bash
-# Create the environment for using DIPLOMAT with DeepLabCut
-# GPU:
-mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-DEEPLABCUT.yaml
-# CPU only:
-mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-DEEPLABCUT-CPU.yaml
-# OR Create an environment for using DIPLOMAT with SLEAP instead...
-# GPU:
-mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml
-# CPU only:
-mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yaml
-```
-And then activate the environment with one of these two commands:
-```bash
-# Activate the DeepLabCut/DIPLOMAT environment...
-mamba activate DIPLOMAT-DEEPLABCUT
-# Activate the SLEAP/DIPLOMAT environment...
-mamba activate DIPLOMAT-SLEAP
-```
-
-For a more thorough explanation of the installation process and alternative installation methods, see the 
-[documentation](https://diplomat.readthedocs.io/en/latest/installation.html).
+For detailed installation instructions, please refer to the [documentation](https://diplomat.readthedocs.io/en/latest/installation.html)!
 
 ## Usage
 

diplomat/predictors/fpe/frame_passes/repair_clusters.py

@@ -19,6 +19,7 @@ class RepairClusters(FramePass):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
+    @classmethod
     def get_config_options(cls) -> ConfigSpec:
         import diplomat.processing.type_casters as tc
 

docs/source/installation.rst

@@ -70,6 +70,44 @@ DIPLOMAT with DeepLabCut support by simply using pip, using one of the two comma
     # Install DIPLOMAT with DeepLabCut without UI support.
     pip install diplomat-track[dlc]
 
+Troubleshooting for DIPLOMAT-DLC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the standard methods fail to install DIPLOMAT and DLC, you can install from 
+the Github source code. This method requires `git <https://git-scm.com/downloads>`_, as well 
+as Miniforge. 
+
+.. code-block:: sh
+
+    # Clone the DIPLOMAT repository and navigate into it.
+    git clone https://github.com/TravisWheelerLab/DIPLOMAT
+    cd DIPLOMAT
+    # With Miniforge, create a Python 3.10 environment and activate it.
+    conda create -n py310 python==3.10
+    conda activate py310
+    # Use the environment you just activated to create a virtual environment ("venv") containing Python 3.10.
+    python -m venv venv
+    # Fully deactivate the Miniforge environment.
+    # (run the command twice)
+    conda deactivate
+    conda deactivate 
+    # Now, activate the virtual environment.
+    ## On Windows, the first time you activate the venv, you may need to configure your execution policy. 
+    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+    ## Activate the venv on Windows.
+    venv/scripts/Activate
+    ## Activate the venv on Mac/Linux.
+    source venv/bin/activate
+    # Finally, install DIPLOMAT and DLC. The installation may take several minutes to complete.
+    python -m pip install -e .[dlc,gui] --ignore-installed
+    # Verify that the installation was successful. The following command should output the current version number.
+    diplomat --version
+
+On Windows, if DIPLOMAT crashes with "OSError: [WinError 126]", you need the libomp DLL. 
+Download the .zip from https://www.dllme.com/dll/files/libomp140_x86_64/versions, extract 
+it, and copy the .dll file to the torch libraries folder of your virtual environment, which 
+should be located at ``.\venv\lib\site-packages\torch\lib`` within the DIPLOMAT directory. 
+If you named your virtual environment something other than ``venv``, change the path accordingly.
 
 With Support for SLEAP Projects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -119,4 +157,75 @@ trying to install DIPLOMAT with SLEAP support on Windows, prefer using the mamba
     # Install DIPLOMAT with SLEAP with GUI support.
     pip install diplomat-track[sleap, gui]
     # Install DIPLOMAT with SLEAP without UI support.
-    pip install diplomat-track[sleap]
+    pip install diplomat-track[sleap]
+
+Troubleshooting for DIPLOMAT-SLEAP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the Mamba method fails to install DIPLOMAT and SLEAP, you may need to downgrade the 
+numpy version manually. Activate the mamba environment with ``mamba activate DIPLOMAT-SLEAP``,
+then downgrade numpy with ``pip install numpy<1.23.0``. 
+
+Verifying the DIPLOMAT installation
+-----------------------------------
+
+Downloading the Sample data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sample models and a video are provided `on Zenodo <https://zenodo.org/records/14232002>`_ for
+verifying the installation. Download the video clip `N5PZS.avi` and the model corresponding to
+your installation (DLC_5bp.zip for DeepLabCut, SLEAP_5bp.zip for SLEAP.) Unzip the model. Your
+working directory should now contain both the video file `N5PZS.avi` and the model folder, either 
+`test_dlc_5/` or `test_sleap_5/`. Verify that both are present by running ``ls``.
+
+Activating the environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Next, you will activate the environment for DIPLOMAT. Unless you installed with the 
+`Using PIP` method, you have to activate the environment that was created for DIPLOMAT in 
+a previous step.
+
+Activating with Mamba
+~~~~~~~~~~~~~~~~~~~~~
+If you used the mamba installation 
+process, you'll run 
+``mamba activate DIPLOMAT-DEEPLABCUT`` or
+``mamba activate DIPLOMAT-SLEAP``. 
+
+Activating with venv
+~~~~~~~~~~~~~~~~~~
+If you followed the virtual environment-based methods (DLC troubleshooting or developer 
+install) you'll run ``venv/scripts/Activate`` on Windows or ``source venv/bin/activate`` 
+on Mac/Linux (replacing `venv` with whatever you named the virtual environment.) 
+
+Activating with PIP
+~~~~~~~~~~~~~~~~~~~
+If you followed the PIP-only method and installed DIPLOMAT to your default environment, 
+no action is necessary.
+
+Verify
+^^^^^^
+In the directory containing the sample video and model, you can run track to verify that 
+all of DIPLOMAT's functionality were installed properly.
+
+Verify tracking without GUI
+~~~~~~~~~~~~~~~~~~~~
+For DeepLabCut, run 
+``diplomat track -c test_dlc_5 -v N5PZS.avi``. 
+
+For SLEAP, run 
+``diplomat track -c test_sleap_5 -v N5PZS.avi``. 
+
+If the tracking completes successfully, a new file ending with extension either `.h5` or 
+`.slp` will now be present.
+
+Verify tracking with GUI
+~~~~~~~~~~~~~~~~~
+For DeepLabCut, run 
+``diplomat track_and_interact -c test_dlc_5 -v N5PZS.avi``. 
+
+For SLEAP, run 
+``diplomat track_and_interact -c test_sleap_5 -v N5PZS.avi``. 
+
+After tracking completes, the manual annotation window will be opened and you should be 
+able to make changes to the automated results.