Installation 

DIPLOMAT currently supports being installed as a normal python package on Windows, Linux, and MacOS. DIPLOMAT and can be installed by following the installation guide below.

Installing Python 

If you have not already, you’ll need to install python to utilize DIPLOMAT. It is recommend that you use Miniforge which provides a python environment and install process that is consistent across platforms. To install Miniforge:

Visit https://github.com/conda-forge/miniforge.

Select the installer for your OS from the list of installers.

Run the installer and follow the installation instructions.

Hint

In these instructions, we use the commands python3 and python3 -m pip to invoke Python and PIP, respectively.

Your machine may vary! If the commands are not recognized, try python for Python, and python -m pip or just pip for PIP.

Hint

DIPLOMAT requires a Python version between 3.8 and 3.10. Check your python version by running python3 --version. If your version of Python falls outside of this range, you can use Miniforge or conda to create an appropriately-versioned environment. For example, to create a Python 3.10 environment, run conda create -n py310 python==3.10, and activate it with conda activate py310. Now check again that your Python has the correct version with python3 --version.

Installing DIPLOMAT 

Overview 

The DIPLOMAT installation process can be broken down into two steps: first, installing one of the front-end networks, SLEAP or DeepLabCut (DLC), and second, installing DIPLOMAT itself.

Note that in order to keep both DIPLOMAT and the front-end contained in one place, you will create an environment either with PIP or conda, and this environment must be activated every time you wish to use DIPLOMAT.

In the first step, you will install whichever front-end you want to use. We currently support SLEAP and DeepLabCut. Be aware that these are third-party tools with potentially complex installation procedures. The installation tutorials recommend methods that we found to be most reliable across most systems, but we cannot guarantee that any third-party tool will work on your computer. If you have difficulty installing a particular front-end, you are encouraged to refer to its internal documentation.

After the front-end is installed, you will install DIPLOMAT in the same environment. The diplomat-track package is available on PIP and offers a streamlined installation. If you are installing with GUI, i.e., diplomat-track[gui], the UI requirements may take several minutes to install on some systems. In general, if you create an environment containing the front-end network, you will be able to install DIPLOMAT to that environment.

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 CTRL + ALT + 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.

Install on Linux (with PIP)

Install DIPLOMAT-SLEAP on Linux

First, create the environment and activate. You will need to activate this environment every time you use DIPLOMAT.

# create a Python 3.10 virtual environment
python3 -m venv venv-sleap

# activate the environment
source venv-sleap/bin/activate

# upgrade pip
python3 -m pip upgrade pip

Next, you’ll install SLEAP. For more information about the SLEAP installation process, refer to the SLEAP installation guide.

# install SLEAP and verify
python3 -m pip install "sleap[pypi]"
python3 -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"
python3 -c "import sleap; sleap.versions()"
python3 -c "import sleap; sleap.system_summary()"

Install DIPLOMAT. Omit the [gui] option if you are installing on HPC or other headless systems.

# install DIPLOMAT and verify
python3 -m pip install "diplomat-track[gui]"
diplomat --version

Install DIPLOMAT-DLC on Linux

First, create the environment and activate. You will need to activate this environment every time you use DIPLOMAT.

# create a Python 3.10 virtual environment
python3 -m venv venv-dlc

# activate the environment
source venv-dlc/bin/activate

# upgrade pip
python3 -m pip upgrade pip

Next, you’ll install DeepLabCut. For more information about the DeepLabCut installation process, refer to the DeepLabCut installation guide.

# install DeepLabCut and verify
python3 -m pip install "numpy<1.24.0"
python3 -m pip install "deeplabcut[tf]"
python3 -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

Install DIPLOMAT. Omit the [gui] option if you are installing on HPC or other headless systems.

# install DIPLOMAT and verify
python3 -m pip install "diplomat-track[gui]"
diplomat --version

These procedures were tested primarily on Ubuntu and CentOS. If you’re running a different distro, we trust that you can make the appropriate changes. The MacOS (with conda) tutorials below may also work on some Linux systems.

Install on MacOS (with conda)

Install DIPLOMAT-SLEAP on MacOS

First, create the environment and activate. You will need to activate this environment every time you use DIPLOMAT.

# create the environment
conda create -n diplomat-sleap -c conda-forge "python==3.9"

# activate the environment
conda activate diplomat-sleap

Next, you’ll install SLEAP. For more information about the SLEAP installation process, refer to the SLEAP installation guide.

# install SLEAP and verify
conda install -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.3.3
python3 -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"
python3 -c "import sleap; sleap.versions()"
python3 -c "import sleap; sleap.system_summary()"

Install DIPLOMAT. Omit the [gui] option if you are installing on HPC or other headless systems.

# install DIPLOMAT and verify
python3 -m pip install "diplomat-track[gui]"
diplomat --version

Install DIPLOMAT-DLC on MacOS

First, create the environment and activate. You will need to activate this environment every time you use DIPLOMAT.

# create the environment
conda create -n diplomat-dlc -c conda-forge "python==3.10"

# activate the environment
conda activate diplomat-dlc

Next, you’ll install DeepLabCut. For more information about the DeepLabCut installation process, refer to the DeepLabCut installation guide.

# install DeepLabCut and verify
conda install "numpy<1.24.0"
conda install "deeplabcut[tf]"
python3 -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

Install DIPLOMAT. Omit the [gui] option if you are installing on HPC or other headless systems.

# install DIPLOMAT and verify
python3 -m pip install "diplomat-track[gui]"
diplomat --version

Install on Windows 

Install DIPLOMAT-SLEAP on Windows

First, create the environment and activate. You will need to activate this environment every time you use DIPLOMAT.

# create the environment
## with GPU
mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml
## with CPU
mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yaml

# activate the environment
mamba activate DIPLOMAT-SLEAP

You may need to fix the Numpy version in order for SLEAP to run properly.

# fix the Numpy version
python3 -m pip install "numpy<1.23.0"
# verify
python3 -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"
python3 -c "import sleap; sleap.versions()"
python3 -c "import sleap; sleap.system_summary()"

Finally, install DIPLOMAT. Omit the [gui] option if you are installing on HPC or other headless systems.

# install DIPLOMAT and verify
python3 -m pip install "diplomat-track[gui]"
diplomat --version

Install DIPLOMAT-DLC on Windows

First, create the environment and activate. You will need to activate this environment every time you use DIPLOMAT.

# create the environment
conda create -n diplomat_dlc python==3.10

# activate the environment
conda activate diplomat_dlc

Next, you’ll install DeepLabCut. For more information about the DeepLabCut installation process, refer to the DeepLabCut installation guide.

# install DLC and verify
python3 -m pip install "numpy<1.24.0"
python3 -m pip install "deeplabcut[tf]"
python3 -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

Install DIPLOMAT. Omit the [gui] option if you are installing on HPC or other headless systems.

# install DIPLOMAT and verify
python3 -m pip install "diplomat-track[gui]"
diplomat --version

Troubleshooting 

MacOS Tips

If the DLC installation crashes with an error about tables or hdf5, make sure your system has the prerequisite packages installed: brew install hdf5 c-blosc lzo bzip2.

In some cases, it may be necessary to pre-configure conda before a Python environment can be created:
% conda config --add channels conda-forge % conda config --set channel_priority strict

Some users have reported success using SLEAP’s default mamba installation method to create an environment:
mamba create -y -n diplomat-sleap -c conda-forge -c anaconda -c sleap sleap=1.3.3 conda activate diplomat-sleap pip install "diplomat-track[gui]"
- However, on many systems this will result in a Python 3.7 environment, which is incompatible with DIPLOMAT.

Linux Tips

On some systems it may be easier to use a conda environment rather than a PIP venv. If you can’t get DIPLOMAT working with the PIP methods in the Linux section, try using the conda methods in the MacOS section.

When installing DLC, you may need to run pip install "numpy<1.24.0" after installing DLC in addition to running it before.

GPU Troubles

Your system may not have the necessary NVIDIA, CUDA, and cuDNN libraries pre-installed. In this case, refer to TensorFlow’s Software requirements for links to the relevant libraries. For an installation tutorial, refer to the NVIDIA installation docs. Alternatively, if the conda (MacOS) method works on your machine, you can run conda install -c conda-forge cudatoolkit cudnn before proceeding to the DLC or SLEAP installation step.

Installing SLEAP and DLC to the same environment

If you want to install both SLEAP and DLC to the same environment, the SLEAP installation must be performed before the DLC installation! Generally, we recommend creating a distinct environment for each front-end.

Alternate Installation Methods

If the standard methods do not work, consider installing DIPLOMAT from source with the developer installation method.

Verifying your DIPLOMAT installation 

We have created a Zenodo record with pretrained SLEAP and DeepLabCut projects and a short video clip with which you can check your DIPLOMAT installation.

Verify DIPLOMAT-SLEAP

In order to verify the installation, download the testing resources N5PZS.avi and SLEAP_5bp.zip from our Zenodo record. Unzip SLEAP_5bp.zip and put the test_sleap_5 folder in the same directory as N5PZS.avi. Alternatively, use these curl commands to download and unzip the resources.

# download and unzip files from https://zenodo.org/records/14232002,
# or do it in the terminal with curl:
curl https://zenodo.org/records/14232002/files/SLEAP_5bp.zip --output SLEAP_5bp.zip && unzip SLEAP_5bp.zip
curl https://zenodo.org/records/14232002/files/N5PZS.avi --output N5PZS.avi

Finally, verify the tracking functionality for DIPLOMAT-SLEAP. Make sure both the video file `N5PZS.avi` and the SLEAP project folder `test_sleap_5` are in your current directory.

Verify that DIPLOMAT’s primary tracking functionality works.

# verify that tracking works
diplomat track -c test_sleap_5/ -v N5PZS.avi -no 3

If you installed diplomat-track[gui], verify that the Interact GUI appears after this command completes.

# verify that interact works
diplomat track_and_interact -c test_sleap_5/ -v N5PZS.avi -no 3

Verify DIPLOMAT-DLC

In order to verify the installation, download the testing resources N5PZS.avi and DLC_5bp.zip from our Zenodo record: Zenodo record. Unzip DLC_5bp.zip and put the test_dlc_5 folder in the same directory as N5PZS.avi. Alternatively, use these curl commands to download and unzip the resources.

# download and unzip files from https://zenodo.org/records/14232002,
# or do it in the terminal with curl:
curl https://zenodo.org/records/14232002/files/DLC_5bp.zip --output DLC_5bp.zip && unzip DLC_5bp.zip
curl https://zenodo.org/records/14232002/files/N5PZS.avi --output N5PZS.avi

# your working directory should now contain "test_dlc_5" and "N5PZS.avi".

Finally, verify the tracking functionality for DIPLOMAT-DLC. Make sure both the video file `N5PZS.avi` and the DLC project folder `test_dlc_5` are in your current directory.

Verify that DIPLOMAT’s primary tracking functionality works.

# verify that tracking works
diplomat track -c test_dlc_5/config.yaml -v N5PZS.avi -no 3

If you installed diplomat-track[gui], verify that the Interact GUI appears after this command completes.

# verify that tracking works
diplomat track_and_interact -c test_dlc_5/config.yaml -v N5PZS.avi -no 3