Skip to content
This repository has been archived by the owner on Jun 1, 2023. It is now read-only.

Latest commit

 

History

History
149 lines (88 loc) · 11.3 KB

UseOverviewGuide.md

File metadata and controls

149 lines (88 loc) · 11.3 KB
Raw

(overview)=

Documentation Overview

Below we will first outline what you need to get started, the different ways you can use DeepLabCut, and then the full workflow. Note, we highly recommend you also read and follow our Nature Protocols paper, which is (still) fully relevant to standard DeepLabCut.

Additional Learning Resources:

  • TUTORIALS: video tutorials that demonstrate various aspects of using the code base.
  • HOW-TO-GUIDES: step-by-step user guidelines for using DeepLabCut on your own datasets (see below)
  • EXPLANATIONS: resources on understanding how DeepLabCut works
  • REFERENCES: read the science behind DeepLabCut

Getting Started: a video tutorial on navigating the documentation!

What you need to get started:

  • a set of videos that span the types of behaviors you want to track. Having 10 videos that include different backgrounds, different individuals, and different postures is MUCH better than 1 or 2 videos of 1 or 2 different individuals (i.e. 10-20 frames from each of 10 videos is much better than 50-100 frames from 2 videos).

  • minimally, a computer w/a CPU. If you want to use DeepLabCut on your own computer for many experiments, then you should get an NVIDIA GPU. See technical specs here. You can also use cloud computing resources, including COLAB (see how).

What you DON'T need to get started:

  • no specific cameras/videos are required; color, monochrome, etc., is all fine. If you can see what you want to measure, then this will work for you (given enough labeled data).

  • no specific computer is required (but see recommendations above), our software works on Linux, Windows, and MacOS, although we recommend Ubuntu.

Overview:

DeepLabCut is a software package for markerless pose estimation of animals performing various tasks. The software can manage multiple projects for various tasks. Each project is identified by the name of the project (e.g. TheBehavior), name of the experimenter (e.g. YourName), as well as the date at creation. This project folder holds a config.yaml (a text document) file containing various (project) parameters as well as links the data of the project.

Overview of the workflow:

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.

NOTE: There is a highly similar workflow for 2.2+ (and your 2.X projects are still fully compatible with this format!).

** DLC 2.2:** as of 2.2 we support "multi-animal projects," but these new features can also be used on single animals too (details below). The workflow is highly similar, but with a few key additional steps. Please carefully review the functions below for more details. You can search/look for maDeepLabCut for specific steps that are changed, or see this more comprehensive guide here

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.

(important-info-regd-usage)=

Specific Advice for Using DeepLabCut:

Important information on using DeepLabCut:

We recommend first using DeepLabCut for a single animal scenario to understand the workflow - even if it's just our demo data. Multi-animal tracking is more complex - i.e. it has several decisions the user needs to make. Then, when you are ready you can jump into 2.2...

Additional information for getting started with maDeepLabCut (aka DeepLabCut 2.2):

We highly recommend using 2.2 first in the Project Manager GUI (Option 3). This will allow you to get used to the additional steps by being walked through the process. Then, you can always use all the functions in your favorite IDE, notebooks, etc.

What scenario do you have?

  • I have single animal videos:

    • quick start: when you create_new_project (and leave the default flag to False in multianimal=False). This is the typical work path for many of you.

  • I have single animal videos, but I want to use the updated network capabilities introduced for multi-animal projects:

    • quick start: when you create_new_project just set the flag multianimal=True. This enables you to use maDLC features even though you have only one animal. To note, this is rarely required for single animal projects, and not the recommended path. Some tips for when you might want to use this: this is good for say, a hand or a mouse if you feel the "skeleton" during training would increase performance. DON'T do this for things that could be identified an individual objects. i.e., don't do whisker 1, whisker 2, whisker 3 as 3 individuals. Each whisker always has a specific spatial location, and by calling them individuals you will do WORSE than in single animal mode.

VIDEO TUTORIAL AVAILABLE!

  • I have multiple identical-looking animals in my videos:
    • quick start: when you create_new_project set the flag multianimal=True. If you can't tell them apart, you can assign the "individual" ID to any animal in each frame. See this labeling w/2.2 demo video

VIDEO TUTORIAL AVAILABLE!

  • I have multiple animals, but I can tell them apart, in my videos and want to use DLC2.2:
    • quick start: when you create_new_project set the flag multianimal=True. And always label the "individual" ID name the same; i.e. if you have mouse1 and mouse2 but mouse2 always has a miniscope, in every frame label mouse2 consistently. See this labeling w/2.2 demo video. Then, you MUST put the following in the config.yaml file: identity: true

VIDEO TUTORIAL AVAILABLE! - ALSO, if you can tell them apart, label animals them consistently!

  • I have a pre-2.2 single animal project, but I want to use 2.2:

Please read this convert 2 maDLC guide

The options for using DeepLabCut:

Great - now that you get the overall workflow let's jump in! Here, you have several options.

Option 1 DEMOs: for a quick introduction to DLC on our data.

Option 2 Standalone GUI: is the perfect place for beginners who want to start using DeepLabCut on your own data.

Option 3 In the terminal: is best for more advanced users, as with the terminal interface you get the most versatility and options.

(using-demo-notebooks)=

Option 1: Demo Notebooks:

VIDEO TUTORIAL AVAILABLE!

We provide Jupyter and COLAB 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 the Project Manager GUI or terminal, so please follow the instructions below.

(using-project-manager-gui)=

Option 2: using the Project Manager GUI:

VIDEO TUTORIAL!

VIDEO TUTORIAL#2!

Start iPython, or if you are using MacOS, you must use pythonw vs. typing ipython or python, but otherwise it's the same. If you are using DeepLabCut on the cloud, you cannot use the GUIs and you need to first set DLClight=True. If you use Windows, please always open the terminal with administrator privileges. Please read more here, and in our Nature Protocols paper here. And, see our troubleshooting wiki.

Simply open the terminal and type:

python -m deeplabcut

That's it! Follow the GUI for details

(using-the-terminal)=

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

VIDEO TUTORIAL AVAILABLE!

Please decide with mode you want to use DeepLabCut, and follow one of the following: