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:

Hint

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

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

Hint

DIPLOMAT requires a Python version of at least 3.8 or higher. Check your python version by running python3 --version. If your version of Python is not at least 3.8, you’ll need to install using the conda/Miniforge approach, or install a supported version of python before using the pip based install approach.

Installing DIPLOMAT

Overview

DIPLOMAT works independently of the animal tracking packages it can run inference on top of (SLEAP and DeepLabCut). Although it is technically possible to install diplomat alongside these packages, it is strongly discouraged as it leads to package conflicts in most scenarios. Instead, it is strongly recommended to install diplomat in it’s own separate python environment. This can be done by following the directions below.

It you want to create new SLEAP or DeepLabCut projects or train new models, you’ll need to install their software packages. This can be done by following their installation guides at the links below:

Note that neither is required to run diplomat, if you just want to run diplomat you can skip this section and follow one of the installation procedures below based on your platform.

Installation

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.

Open the terminal and run one of the two commands below:

# On systems with an NVIDIA GPU:
conda env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-NVIDIA.yaml
# On any other system:
conda env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT.yaml

Once the installation finishes, you can test the installation by running the commands below.

# Activate the diplomat environment.
conda activate diplomat
# Test diplomat can access the frontends it needs...
diplomat frontends list loaded

Development Installation Method

DIPLOMAT Installation for Development

  • If you plan on developing frontends or predictors for DIPLOMAT, 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 with 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 with "all", or ui support, 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 with DeepLabCut

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 If you installed diplomat with "all", or ui support, 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