DeepLabCut Installation

DeepLabCut Installation

An open source, markerless tracking system for behavior motion analysis of humans or animals.

How did Buster Keaton get those awesome moves?? Analyze the videos and find out!!!!

Also check out other relevant DLC stuff on our projects page

Introduction

“DeepLabCut is a toolbox for markerless pose estimation of animals performing various tasks. Examples include tail tracking, reaching in mice, and various Drosophila behaviors during egg-laying (see Mathis et al. for details).” See the DeepLabCut Github for the latest instructions and information. The instructions offered here are an expansion of their instructions and are intended for someone with less experience with Linux. Or for someone attempting to get DeepLabCut up and running on a fresh install of Ubuntu.

@article{Mathisetal2018,
    title={DeepLabCut: markerless pose estimation of user-defined body parts with deep learning},
    author = {Alexander Mathis and Pranav Mamidanna and Kevin M. Cury and Taiga Abe  and Venkatesh N. Murthy and Mackenzie W. Mathis and Matthias Bethge},
    journal={Nature Neuroscience},
    year={2018},
    url={https://www.nature.com/articles/s41593-018-0209-y}
}

ONE Core notes/user guide/overview of DLC can be found here.

Computer

DeepLabCut can run on a wide variety of computers. It can run it on just a CPU, but a good GPU (8 GB such as the NVIDIA GeForce 1080 Ti) will make things significantly faster. But note that DeepLabCut currently only runs on certain NVIDIA GPU’s, so it is critical to choose a GPU that can support DeepLabCut. Make sure that your GPU is CUDA 9.0+ compatible before purchasing. We built our own computer to run both DeepLabCut and the super cool Neuropixels project. You can copy this design by getting the parts listed here.

Setting up an Operating System

DeepLabCut runs best on a Linux based operating system, ideally Ubuntu 16.04 . Some colleagues have reported success with Ubuntu 18.04, but we recommend 16.04 as it is currently better supported by the DeepLabCut community. You can set up the computer to Dual Boot (example: Windows and Ubuntu) or have the computer run a dedicated Ubuntu only system. Either way, setting up a new OS has the potential for error, so back up all data before proceeding.

Dual Booting (Optional) Setting up a dual boot system when done correctly allows you to keep your current operating system (ie. Windows) and install another OS next to it (either on the same harddrive, or another harddrive that is visible to the BIOS/UEFI at boot). When done correctly, the programs and files on the original OS should remain intact. The new OS (ie. Ubuntu) will be an option you can choose each time you turn on the machine. If you only want to run a single Ubuntu OS on this computer and are okay wiping all files off of the installed harddrive, skip to the “Installing Ubuntu” section.

First step of setting up a dual boot is to back up any critical data already on the harddrive. You have been warned. It’s pretty simple to set up a dual boot with two harddrives, so we are not going to cover that here. If you’d like to split a single harddrive to hold two OS, you will need to create a new partition:

  • Partition Option 1: If your computer already has Windows 10 installed, you can use a built in tool to create a partition. This option is easier to use but slightly “riskier” (there have been reports of this tool breaking Windows). Create a new volume, instructions here
  • Partition Option 2: You can also use a free tool called GParted to set up your dual boot. This approach is less “risky”. GParted is a more accepted tool for dealing with partitions. Follow the “Method A” instructions found here.

Installing Ubuntu Alone You’ll can now install Ubuntu 16.04 on either the entire harddrive, or the partition you just created. Click here for a tutorial on creating a bootable USB stick with Ubuntu 16.04 on it. Follow the instructions to install Ubuntu. If you opted for a dual boot, be sure to select that you want Ubuntu installed alongside the existing OS. This should be the default option, but just be sure.

Using Ubuntu If you are completely unfamiliar with Linux (welcome to a super awesome community!!), click here for a bit of guidance on Linux terminal commands. You will be using the Linux terminal in almost every step below. Also, it may be super duper handy to note that ctrl c and ctrl v do not function as copy and paste in the terminal. Use ctrl shift c and ctrl shift v (or mouse middle button) for copy and paste.

Setting Up Anaconda Environments

Installing Anaconda Installing DeepLabCut could overwrite existing versions of Python packages or Tensorflow. This could potentially break previously installed applications that relied on specific versions of other software. Creating an anaconda environment for DLC can remedy this situation. Each environment acts somewhat like a separate pocket of your computer, allowing different versions of software to coexist on the same computer. If you have a dedicated DLC workstation, then this step is not strictly speaking necessary. But environments do allow you to easily specify which version of python you are using, and python 3.6 is required for DLC.

Download the most recent version of Anaconda here.

sudo apt-get upgrade
cd Downloads
bash Anaconda3-2018.12-Linux-x86_64.sh

Exit the terminal and reopen before creating a new environment

Creating Anaconda Environment Create a new anaconda environment with the following command. Note that you will want to call conda by it’s full address. Here and in the rest of this documentation the environment is named “dlc”, but you can name it whatever you like. Just ensure you are running python 3.6. (Tip: Ubuntu will automatically replace $USER with the user name you chose earlier).

/home/$USER/anaconda3/bin/conda create -n dlc python=3.6

Activate the environment with the following command. You will need to re-activate the environment every time you reopen the terminal.

conda activate dlc

For information on managing environments, click here.

Installing DeepLabCut 2.0

Call the following commands to install the necessary DeepLabCut files and wxPython.

pip install deeplabcut
pip install https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-16.04/wxPython-4.0.3-cp36-cp36m-linux_x86_64.whl

Also grab the official example files if you want them. You’ll want to install the git program on your computer first:

sudo apt-get install git

The following downloads the DeepLabCut examples and a few other things into a folder in your home directory, but you can place it wherever you would like.

cd /home/$USER
git clone https://github.com/AlexEMG/DeepLabCut

If using CPU only (training is slow)

Install tensorflow into your anaconda environment with the following

source activate dlc
pip install tensorflow==1.10

And if you are using a CPU, that’s it! Training DeepLabCut algorithms will be extremely slow with this setup (several days at a times), but still possible.

For GPU Utilization (training is much faster! Like 100x faster)

There are a few more steps involved for GPU utilization. If you have a tensorflow compatible GPU, then you’ll need to cover the following steps (ideally in order):

  • Install GPU Driver
  • Install CUDA 9.0
  • Install cuDNN
  • Install Tensowflow

Installing Driver for GPU

There are multiple NVIDIA GPU driver versions available, but not every one of them works for DeepLabCut. Tensorflow currently supports CUDA versions 9.0 through 10.0 (depending on the Tensorflow version being used). We currently recommend CUDA 9.0 which requires NVIDIA Drivers 384.x or higher to utilize your GPU’s speed. But also note that some GPU’s require newer drivers than 384.x, and we’ll cover how to detect which driver is best for your GPU below.

Detailed instructions can be found at the tensorflow website, but running the following should suffice.

sudo add-apt-repository ppa:graphics-drivers
sudo apt-get update
ubuntu-drivers devices

A list of available compatible drivers will appear. Look for the most recent nvidia driver number (ie. the highest) in the list. That will be the driver you want. In January 2019, the most recent number version for the RTX 2080 GPU was “nvidia-driver-415”. Run the following command, replacing “415” with another driver number if necessary.

sudo apt-get install nvidia-415

Now restart your computer (simply call sudo reboot ). A visible sign that your driver was successfully installed is that the Ubuntu OS should be operating in a higher resolution. If the following command generates an error, then your GPU driver was not successfully installed.

nvidia-smi

Alternative GPU Driver Installation If this method gives you issues, there is an alternative way to install the NVIDIA drivers. Download the appropriate NVIDIA GPU driver here. This should be in the format of a “.run” file.

  • If installing NVIDIA Driver for RTX 2080 on Ubuntu 64 bit, you can simply call wget "http://us.download.nvidia.com/XFree86/Linux-x86_64/410.93/NVIDIA-Linux-x86_64-410.93.run" -P /home/$USER/Downloads to download the 410 version of the driver.

We will then be using the instructions found here to install the nvidia driver: First, turn the run file into an executable. If you aren’t installing version 410.93, insert the proper version number.

chmod +x /home/$USER/Downloads/NVIDIA-Linux-x86_64-410.93.run

Now press Ctrl+Alt+F1 to enter a terminal stripped of most GUI elements. From here you can stop the Xserver that would otherwise interfere with the installation. Enter the following commands, and then you’ll be prompted be a really long page of legal stuff. Hold down the “d” key to quickly move through it.

sudo service lightdm stop
sudo init 3
sudo /home/$USER/Downloads/NVIDIA-Linux-x86_64-410.93.run

Now restart your computer (you can just call sudo reboot ). Again, a visible sign that your driver was successfully installed is that the Ubuntu OS should be operating in a higher resolution. If the following command generates an error, then your GPU driver was not successfully installed.

nvidia-smi

Installing CUDA for UBUNTU 16.04 64 bit

The following section is based off of the official CUDA installation guide. You can install via DEB files or via RUN files.

Download and install CUDA

Download CUDA 9.0 install files from here or use the code below.

Download the DEB file with

wget "https://developer.nvidia.com/compute/cuda/9.0/Prod/local_installers/cuda-repo-ubuntu1604-9-0-local_9.0.176-1_amd64-deb" -P /home/$USER/Downloads

Install with

sudo dpkg -i /home/$USER/Downloads/cuda-repo-ubuntu1604-9-0-local_9.0.176-1_amd64-deb
sudo apt-key add /var/cuda-repo-9-0-local/7fa2af80.pub
sudo apt-get update

Then call the following to install the CUDA toolkit without overriding your NVIDIA driver

sudo apt-get install cuda-toolkit-9.0

Installing CUDA Patches (Optional) We haven’t found the CUDA patches to be necessary. But the necessary files can be found here (same place as the original CUDA downloads). The RUN and DEB patches can then be installed just like we installed the base toolkit above.

Post CUDA Install Set up your path to so that your computer knows where to find CUDA:

export PATH=/usr/local/cuda-7.5/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-7.5/lib64:$LD_LIBRARY_PATH

Install cuDNN

For official cuDNN installation documents, click here. But: TL;DR.

An account is required to get cuDNN, click here to sign up. Download the necessary files (we used cuDNN 9.0). We downloaded:

  • cuDNN Runtime Library for Ubuntu16.04 (Deb)
  • cuDNN Developer Library for Ubuntu16.04 (Deb)
  • cuDNN Code Samples and User Guide for Ubuntu16.04 (Deb)

Then run the following:

cd /home/$USER/Downloads
sudo dpkg -i libcudnn7_7.5.0.56-1+cuda9.0_amd64.deb
sudo dpkg -i libcudnn7-dev_7.5.0.56-1+cuda9.0_amd64.deb
sudo dpkg -i libcudnn7-doc_7.5.0.56-1+cuda9.0_amd64.deb
cd ..

Tensorflow Install

If that was successful, proceed to install tensorflow in your deeplabcut environment

source activate dlc
pip install tensorflow-gpu==1.10

Test your tensorflow install by trying to run the following:

ipython
import tensorflow as tf
sess = tf.Session(config=tf.ConfigProto(log_device_placement=True))

If you ever need to exit ipython to go back to the regular terminal, hit up

exit

Running Jupyter Notebooks

Jupyter notebooks is a nice (though optional) way to run DeepLabCut programs. Most of our colleagues on campus currently just run things in ipython, but running DeepLabCut through Jupyter adds some nice functionality which you can learn about here or here. If you choose to run DeepLabCut through a Jupyer, make sure that your environment (where you’ve just installed tensorflow) is accessible by running the following:

python -m ipykernel install --user --name dlc --display-name "Python (dlc)
jupyter notebook

Quick guide to Jupyter notebooks found here.

Using DeepLabCut

With DeepLabCut now installed, check out the user guide and demos found on the projects GitHub page.


ONE Core acknowledgement

Please acknowledge the ONE Core facility in your publications. An appropriate wording would be:

“The Optogenetics and Neural Engineering (ONE) Core at the University of Colorado School of Medicine provided engineering support for this research. The ONE Core is part of the NeuroTechnology Center, funded in part by the School of Medicine and by the National Institute of Neurological Disorders and Stroke of the National Institutes of Health under award number P30NS048154.”