DeepLabCut

Documentation:

<img src= https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5cca1d519b747a750d680de5/1556749676166/dlc_overview-01.png?format=1000w width="80%">

DeepLabCut is a software package that is organized such that you create a master project folder and this holds a config.yaml (a text document) file that will always link you back to the project. Namely, you can have as many projects on your computer as you wish. You can have DeepLabCut installed in an environment and always exit and return to this environment to run the code. You just need to point to the correct config.yaml file to jump back in! The documentation below will take you through the individual steps.

<img src= https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5ccc5abe0d9297405a428522/1556896461304/howtouseDLC-01.png?format=1000w width="60%">

Here are some tips for scaling up your analysis: https://github.com/AlexEMG/DeepLabCut/wiki/Batch-Processing-your-Analysis

You can get started by using our demo Jupyter Notebooks (#1), or use the program terminal/cmd (#2).

Overview of the work-flow:

This page contains a list of the essential functions of DeepLabCut as well as demos. There are many optional parameters with each described function, which you can find here. For additional assistance, you can use the help function to better understand what each function does.

This figure highlights the steps we will describe below:

Option 1: Demo Notebooks:

We provide Jupyter notebooks for using DeepLabCut on both a pre-labeled dataset, and on the end user’s own dataset. See all the demo’s here! Please note that GUIs are not easily supported in Jupyter in MacOS, as you need a framework build of python. While it’s possible to launch them with a few tweaks, we recommend using terminal - it’s more fun and still easy, so please follow the instructions below!

Option 2: using the program terminal, Start iPython*:

*please note, we provide a quick-guide of the commands at the bottom of this page. Also, if you are using MacOS, you must use pythonw vs. typing ipython, but otherwise it’s the same.

Open an ipython session and import the package by typing in the terminal:

ipython
import deeplabcut

TIP: for every function there is a associated help document that can be viewed by adding a ? after the function name; i.e. deeplabcut.create_new_project?. To exit this help screen, type :q.

Create a New Project:

deeplabcut.create_new_project(`Name of the project',`Name of the experimenter', [`Full path of video 1',`Full path of video2',`Full path of video3'], working_directory=`Full path of the working directory',copy_videos=True/False)

(more details here)

Configure the Project:

(PLEASE see more details here)

mini-demo: create project and edit the yaml file

Select Frames to Label:

deeplabcut.extract_frames(config_path,`automatic/manual',`uniform/kmeans', crop=True/False)

(more details here) *update: as of 2.0.5 checkcropping=True is dropped; you now just the option to directly draw a rectangle over the image to crop before extraction (i.e. there no need to manually change in config.yaml then check).

Label Frames:

deeplabcut.label_frames(config_path)

(more details here)

mini-demo: using the GUI to label

Check Annotated Frames:

deeplabcut.check_labels(config_path)

(more details here)

Create Training Dataset:

deeplabcut.create_training_dataset(config_path,num_shuffles=1)

(more details here)

Train The Network:

deeplabcut.train_network(config_path,shuffle=1)

(more details here)

Evaluate the Trained Network:

deeplabcut.evaluate_network(config_path,shuffle=[1], plotting=True)

(more details here)

Video Analysis and Plotting Results:

deeplabcut.analyze_videos(config_path,[`/fullpath/project/videos/'], videotype='.mp4', save_as_csv=True)

Here are some tips for scaling up your analysis: https://github.com/AlexEMG/DeepLabCut/wiki/Batch-Processing-your-Analysis

You can also filter the predicted bodyparts by:

deeplabcut.filterpredictions(config_path,[`/fullpath/project/videos/reachingvideo1.avi'], shuffle=1)

Note, this creates a file with the ending filtered.h5 that you can use for further analysis. This filtering step has many parameters, so please see the full docstring by typing: deeplabcut.filterpredictions?

Create videos:

deeplabcut.create_labeled_video(config_path, [`/analysis/project/videos/reachingvideo1.avi',`/fullpath/project/videos/reachingvideo2.avi'],filtered=True)

Plot the outputs:

deeplabcut.plot_trajectories(config_path,[`/fullpath/project/videos/reachingvideo1.avi'],filtered=True)

(more details here)

[optional] Refinement - Extract Outlier Frames from a video:

deeplabcut.extract_outlier_frames(config_path,[`videofile_path'])

(more details here)

[optional] Refinement of the labels with our GUI:

(refinement and augmentation of the training dataset)

deeplabcut.refine_labels(config_path)

mini-demo: using the refinement GUI, a user can load the file then zoom, pan, and edit and/or remove points:

When done editing the labels, merge:

deeplabcut.merge_datasets(config_path)

Now, create a new training set and re-train (same steps as above)!

(more details here)

HELP:

In ipython/Jupyter notebook:

deeplabcut.nameofthefunction?

In python or pythonw:

help(deeplabcut.nameofthefunction)

Tips for “daily” use:

<img src= https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5ccc5abe0d9297405a428522/1556896461304/howtouseDLC-01.png?format=1000w width="80%">

You can exit an environment and easily jump back into a project by simply:

Linux/MacOS formatting example:

source activate yourdeeplabcutEnvName
ipython
import deeplabcut
config_path ='/home/yourprojectfolder/config.yaml'

Windows formatting example:

activate yourdeeplabcutEnvName
ipython
import deeplabcut
config_path = r'C:\home\yourprojectfolder\config.yaml'

Now, you can run any of the functions desribed in this documentation.

There is also helper code to further analyze your data or scale up analsis here: https://github.com/AlexEMG/DLCutils/

QUICK GUIDE:

The 12 main steps to take you from project creation to analyzed videos:

Open ipython in the terminal: import deeplabcut

Create a new project: deeplabcut.create_new_project(‘project_name’,‘experimenter’,[‘path of video 1’,‘path of video2’,..])

Set a config_path variable for ease of use: config_path = ‘yourdirectory/project_name/config.yaml’

Extract frames: deeplabcut.extract_frames(config_path)

Label frames: deeplabcut.label_frames(config_path)

Check labels [OPTIONAL]: deeplabcut.check_labels(config_path)

Create training dataset: deeplabcut.create_training_dataset(config_path)

Train the network: deeplabcut.train_network(config_path)

Evaluate the trained network: deeplabcut.evaluate_network(config_path)

Video analysis: deeplabcut.analyze_videos(config_path, [‘path of video 1’,‘path of video2’, ...])

Plot results (trajectories): deeplabcut.plot_trajectories(config_path, [‘path of video 1’,‘path of video2’,..])

Create a video: deeplabcut.create_labeled_video(config_path, [‘path of video 1’,‘path of video2’,..])

Return to readme.