diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 44b2c21..8ce1ebc 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,4 +1,4 @@ Changes for this version of DIPLOMAT: -- added installation troubleshooting procedure to docs -- added installation verification procedure to docs -- created a zenodo record for sample data and models. +- updated installation procedure to include updating pip +- added quotes around the editable installation path + options for zsh compatibility +- change order of installation instructions to prioritize DIPLOMAT-SLEAP \ No newline at end of file diff --git a/diplomat/__init__.py b/diplomat/__init__.py index f6d10ee..53ac642 100644 --- a/diplomat/__init__.py +++ b/diplomat/__init__.py @@ -2,7 +2,7 @@ A tool providing multi-animal tracking capabilities on top of other Deep learning based tracking software. """ -__version__ = "0.1.12" +__version__ = "0.1.12.1" # Can be used by functions to determine if diplomat was invoked through it's CLI interface. CLI_RUN = False diff --git a/docs/source/installation.rst b/docs/source/installation.rst index c060b46..bf3a6ee 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -22,6 +22,63 @@ and install process that is consistent across platforms. To install Miniforge: Installing DIPLOMAT ------------------- +With Support for SLEAP Projects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Using Mamba or Conda +~~~~~~~~~~~~~~~~~~~~ + +Once you have a mamba installed, you'll want to open a terminal and type one of these two commands: + +.. code-block:: sh + + # Install diplomat with GPU support... + mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml + # Install diplomat with CPU support only... + mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yaml + +.. hint:: + + Both running and installing diplomat requires access to a terminal. To access one: + + **Windows:** Open the start menu and search for *Miniforge Prompt*. + + **Linux:** Press :kbd:`CTRL` + :kbd:`ALT` + :kbd:`T`. This will open a terminal window. + + **Mac:** Select the search icon in the top right corner of the screen to open Spotlight, and + then search for *Terminal*. + +Once done, simply activate the brand new environment. + +.. code-block:: sh + + mamba activate DIPLOMAT-SLEAP + +From here, the ``diplomat`` command will be available from the command line. + +Using PIP +~~~~~~~~~ + +If you are using an alternative package for managing python environments, you can install +DIPLOMAT with SLEAP support by simply using pip, using one of the two commands below: + +NOTE: SLEAP is known to have installation issues on Windows when attempting to use pip. If you're +trying to install DIPLOMAT with SLEAP support on Windows, prefer using the mamba/miniforge method above. + +.. code-block:: sh + + # 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] + +Troubleshooting for DIPLOMAT-SLEAP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the Mamba method fails to install DIPLOMAT and SLEAP, or if DIPLOMAT does not run after installation, +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``. + With Support for DeepLabCut Projects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -98,8 +155,10 @@ as Miniforge. venv/scripts/Activate ## Activate the venv on Mac/Linux. source venv/bin/activate + # Update PIP + python -m pip install --upgrade pip # Finally, install DIPLOMAT and DLC. The installation may take several minutes to complete. - python -m pip install -e .[dlc,gui] --ignore-installed + 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 @@ -109,63 +168,6 @@ it, and copy the .dll file to the torch libraries folder of your virtual environ 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Using Mamba or Conda -~~~~~~~~~~~~~~~~~~~~ - -Once you have a mamba installed, you'll want to open a terminal and type one of these two commands: - -.. code-block:: sh - - # Install diplomat with GPU support... - mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml - # Install diplomat with CPU support only... - mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yaml - -.. hint:: - - Both running and installing diplomat requires access to a terminal. To access one: - - **Windows:** Open the start menu and search for *Miniforge Prompt*. - - **Linux:** Press :kbd:`CTRL` + :kbd:`ALT` + :kbd:`T`. This will open a terminal window. - - **Mac:** Select the search icon in the top right corner of the screen to open Spotlight, and - then search for *Terminal*. - -Once done, simply activate the brand new environment. - -.. code-block:: sh - - mamba activate DIPLOMAT-SLEAP - -From here, the ``diplomat`` command will be available from the command line. - -Using PIP -~~~~~~~~~ - -If you are using an alternative package for managing python environments, you can install -DIPLOMAT with SLEAP support by simply using pip, using one of the two commands below: - -NOTE: SLEAP is known to have installation issues on Windows when attempting to use pip. If you're -trying to install DIPLOMAT with SLEAP support on Windows, prefer using the mamba/miniforge method above. - -.. code-block:: sh - - # 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] - -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 -----------------------------------