DeepLabCut for your standard (single animal) projects!

Open In Colab

DeepLabCut for your standard (single animal) projects!#

Some useful links:

This notebook illustrates how to use the cloud to:

  • create a training set

  • train a network

  • evaluate a network

  • create simple quality check plots

  • analyze novel videos!

This notebook assumes you already have a project folder with labeled data!#

This notebook demonstrates the necessary steps to use DeepLabCut for your own project.

This shows the most simple code to do so, but many of the functions have additional features, so please check out the overview & the protocol paper!

Nath*, Mathis* et al.: Using DeepLabCut for markerless pose estimation during behavior across species. Nature Protocols, 2019.

Paper: https://www.nature.com/articles/s41596-019-0176-0

Pre-print: https://www.biorxiv.org/content/biorxiv/early/2018/11/24/476531.full.pdf

First, go to “Runtime” ->”change runtime type”->select “Python3”, and then select “GPU”#

As the COLAB environments were updated to CUDA 12.X and Python 3.11, we need to install DeepLabCut and TensorFlow in a distinct way to get TensorFlow to connect to the GPU.

# this will take a couple of minutes to install all the dependencies!
!pip install --pre deeplabcut

(Be sure to click “RESTART RUNTIME” if it is displayed above before moving on !) You will see this button at the output of the cells above ^.

import deeplabcut

DLC loaded in light mode; you cannot use any GUI (labeling, relabeling and standalone GUI)

Create a training dataset:#

You must do this step inside of Colab#

After running this script the training dataset is created and saved in the project directory under the subdirectory ‘training-datasets’

This function also creates new subdirectories under dlc-models-pytorch and appends the project config.yaml file with the correct path to the training and testing pose configuration file. These files hold the parameters for training the network. Such an example file is provided with the toolbox and named as pytorch_config.yaml.

Now it is the time to start training the network!

# There are many more functions you can set here, including which network to use!
# Check the docstring for `create_training_dataset` for all options you can use!

deeplabcut.create_training_dataset(
  path_config_file, net_type="resnet_50", engine=deeplabcut.Engine.PYTORCH
)

Start training:#

This function trains the network for a specific shuffle of the training dataset.

# Let's also change the display and save_epochs just in case Colab takes away
# the GPU... If that happens, you can reload from a saved point using the
# `snapshot_path` argument to `deeplabcut.train_network`:
#   deeplabcut.train_network(..., snapshot_path="/content/.../snapshot-050.pt")

# Typically, you want to train to ~200 epochs. We set the batch size to 8 to
# utilize the GPU's capabilities.

# More info and there are more things you can set:
#   https://deeplabcut.github.io/DeepLabCut/docs/standardDeepLabCut_UserGuide.html#g-train-the-network

deeplabcut.train_network(
    path_config_file,
    shuffle=1,
    save_epochs=5,
    epochs=200,
    batch_size=8,
)

# This will run until you stop it (CTRL+C), or hit "STOP" icon, or when it hits the end.

Note, that when you hit “STOP” you will get a KeyboardInterrupt “error”! No worries! :)

Start evaluating:#

This function evaluates a trained model for a specific shuffle/shuffles at a particular state or all the states on the data set (images) and stores the results as .csv file in a subdirectory under evaluation-results-pytorch

deeplabcut.evaluate_network(path_config_file, plotting=True)

# Here you want to see a low pixel error! Of course, it can only be as
# good as the labeler, so be sure your labels are good!

There is an optional refinement step you can do outside of Colab:#

  • if your pixel errors are not low enough, please check out the protocol guide on how to refine your network!

  • You will need to adjust the labels outside of Colab! We recommend coming back to train and analyze videos…

  • Please see the repo and protocol instructions on how to refine your data!

Start Analyzing videos:#

This function analyzes the new video. The user can choose the best model from the evaluation results and specify the correct snapshot index for the variable snapshotindex in the config.yaml file. Otherwise, by default the most recent snapshot is used to analyse the video.

The results are stored in hd5 file in the same directory where the video resides.

deeplabcut.analyze_videos(
    path_config_file,
    videofile_path,
    videotype=video_type,
    destfolder=destfolder,
)

Plot the trajectories of the analyzed videos:#

This function plots the trajectories of all the body parts across the entire video. Each body part is identified by a unique color.

deeplabcut.plot_trajectories(
    path_config_file,
    videofile_path,
    videotype=video_type,
    destfolder=destfolder,
)

Now you can look at the plot-poses file and check the “plot-likelihood.png” might want to change the “p-cutoff” in the config.yaml file so that you have only high confidnece points plotted in the video. i.e. ~0.8 or 0.9. The current default is 0.4.

Create labeled video:#

This function is for visualiztion purpose and can be used to create a video in .mp4 format with labels predicted by the network. This video is saved in the same directory where the original video resides.

deeplabcut.create_labeled_video(
    path_config_file,
    videofile_path,
    videotype=video_type,
    destfolder=destfolder,
)
Contents