DeepLabCut · n-poulsen · Feb 10, 2025 · Jan 30, 2025 · Jan 31, 2025 · Jan 31, 2025
diff --git a/.github/workflows/publish-book.yml b/.github/workflows/publish-book.yml
@@ -11,15 +11,15 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - name: Set up Python 3.9
+    - name: Set up Python 3.10
       uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: 3.10
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install .[tf,docs]
+        python -m pip install .[docs]
         pip install jupyter-book sphinxcontrib-mermaid
 
     - name: Build the book

diff --git a/README.md b/README.md
@@ -60,15 +60,22 @@
 
 Please click the link above for all the information you need to get started! Please note that currently we support only Python 3.10+ (see conda files for guidance).
 
-Developers Stable Release:
-- Very quick start: You need to have TensorFlow installed (up to v2.10 supported across platforms) `pip install "deeplabcut[gui,tf]"` that includes all functions plus GUIs, or `pip install deeplabcut[tf]` (headless version with PyTorch and TensorFlow).
-
-Developers Alpha Release:
-- We also have an alpha release of PyTorch DeepLabCut available! [Please see here for instructions and information](https://github.com/DeepLabCut/DeepLabCut/blob/pytorch_docs/docs/pytorch/user_guide.md).
+Developers Stable Release: very quick start (Python 3.10+ required) to install 
+DeepLabCut with the PyTorch engine
+
+- [Install PyTorch](https://pytorch.org/get-started/locally/) (**select the desired
+CUDA version if you want to use a GPU**): `pip install torch torchvision`
+- Then, [install `pytables`](https://www.pytables.org/usersguide/installation.html): `conda install -c conda-forge pytables==3.8.0`
+- Finally, install `DeepLabCut`: `pip install "deeplabcut>=3.0"`!
+
+To use the TensorFlow engine (requires Python 3.10; TF up to v2.10 supported on Windows,
+up to v2.12 on other platforms): you'll need to run `pip install "deeplabcut[gui,tf]"` 
+(which includes all functions plus GUIs) or `pip install "deeplabcut[tf]"` (headless
+version with PyTorch and TensorFlow).
 
 We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the new [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker). 
 
-# [Documentation: The DeepLabCut Process](https://deeplabcut.github.io/DeepLabCut)
+# [Documentation: The DeepLabCut Process](https://deeplabcut.github.io/DeepLabCut/README.html)
 
 Our docs walk you through using DeepLabCut, and key API points. For an overview of the toolbox and workflow for project management, see our step-by-step at [Nature Protocols paper](https://doi.org/10.1038/s41596-019-0176-0).
 

diff --git a/_config.yml b/_config.yml
@@ -5,7 +5,7 @@ only_build_toc_files: true
 
 sphinx:
   config:
-    autodoc_mock_imports: ["wx"]
+    autodoc_mock_imports: ["wx", "matplotlib", "qtpy", "PySide6", "napari", "shiboken6"]
     mermaid_output_format: raw
   extra_extensions:
     - numpydoc

diff --git a/_toc.yml b/_toc.yml
@@ -49,7 +49,6 @@ parts:
   - file: docs/recipes/MegaDetectorDLCLive
 - caption: 🧑‍🍳 Cookbook (detailed helper guides)
   chapters:
-  - file: docs/tutorial
   - file: docs/convert_maDLC
   - file: docs/recipes/OtherData
   - file: docs/recipes/io

diff --git a/conda-environments/DEEPLABCUT_M1.yaml b/conda-environments/DEEPLABCUT_M1.yaml
diff --git a/deeplabcut/utils/visualization.py b/deeplabcut/utils/visualization.py
@@ -17,6 +17,7 @@
 https://github.com/DeepLabCut/DeepLabCut/blob/master/AUTHORS
 Licensed under GNU Lesser General Public License v3.0
 """
+from __future__ import annotations
 
 import os
 from pathlib import Path

diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md
@@ -18,11 +18,11 @@ We are primarily a package that enables deep learning-based pose estimation. We
 
 - Decide on your needs: there are **two main modes, standard DeepLabCut or multi-animal DeepLabCut**. We highly recommend carefully considering which one is best for your needs. For example, a white mouse + black mouse would call for standard, while two black mice would use multi-animal. **[Important Information on how to use DLC in different scenarios (single vs multi animal)](important-info-regd-usage)** Then pick a user guide:
 
-- (1) [How to use standard DeepLabCut](single-animal-userguide)
-- (2) [How to use multi-animal DeepLabCut](multi-animal-userguide)
+  - (1) [How to use standard DeepLabCut](single-animal-userguide)
+  - (2) [How to use multi-animal DeepLabCut](multi-animal-userguide)
 
 - To note, as of DLC3+ the single and multi-animal code bases are more integrated and we support **top-down**,  **bottom-up**, and a new "hybrid" approach that is state-of-the-art, called **BUCTD** (bottom-up conditional top down), models.
-   - If these terms are new to you, check out our [Primer on Motion Capture with Deep Learning!](https://www.sciencedirect.com/science/article/pii/S0896627320307170). In brief, both work for single or multiple animals and each method can be better or worse on your data. 
+  - If these terms are new to you, check out our [Primer on Motion Capture with Deep Learning!](https://www.sciencedirect.com/science/article/pii/S0896627320307170). In brief, both work for single or multiple animals and each method can be better or worse on your data.
 
 <p align="center">
 <img src= https://ars.els-cdn.com/content/image/1-s2.0-S0896627320307170-gr5_lrg.jpg?format=1000w width="50%">
@@ -67,15 +67,19 @@ Getting Started: [a video tutorial on navigating the documentation!](https://www
  </p>
 
  <p align="center">
- <img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1560124235138-A9VEZB45SQPD5Z0BDEXA/ke17ZwdGBToddI8pDm48kKsvCFNoOAts8bgs5LXY20UUqsxRUqqbr1mOJYKfIPR7LoDQ9mXPOjoJoqy81S2I8N_N4V1vUb5AoIIIbLZhVYxCRW4BPu10St3TBAUQYVKcZaDohTswVrVk6oKw3G03bTl18OXeDyNJsBjNlGiyPYGo9Ewyd5AI5wx6CleNeBtf/dlc_steps.jpg?format=1000w" height="270">
+ <img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1560124235138-A9VEZB45SQPD5Z0BDEXA/ke17ZwdGBToddI8pDm48kKsvCFNoOAts8bgs5LXY20UUqsxRUqqbr1mOJYKfIPR7LoDQ9mXPOjoJoqy81S2I8N_N4V1vUb5AoIIIbLZhVYxCRW4BPu10St3TBAUQYVKcZaDohTswVrVk6oKw3G03bTl18OXeDyNJsBjNlGiyPYGo9Ewyd5AI5wx6CleNeBtf/dlc_steps.jpg?format=1000w" width="80%">
 </p>
 
 ### 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](functionDetails.md). For additional assistance, you can use the [help](UseOverviewGuide.md#help) function to better understand what each function does.
 
- <p align="center">
-<img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5cca272524a69435c3251c40/1556752170424/flowfig.jpg?format=1000w" height="270">
-
+<p align="center">
+  <img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5cca272524a69435c3251c40/1556752170424/flowfig.jpg?format=1000w" width=95%>
+  <br>
+  <em>
+   <a href="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5cca272524a69435c3251c40/1556752170424/flowfig.jpg?format=1000w">View in full screen</a>
+  </em>
+</p>
 
 You can have as many projects on your computer as you wish. You can have DeepLabCut installed in an [environment](/conda-environments) 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](/docs/UseOverviewGuide.md#tips-for-daily-use)! The documentation below will take you through the individual steps.
 
@@ -136,7 +140,7 @@ with the terminal interface you get the most versatility and options.
 ## Option 1: Demo Notebooks:
 [VIDEO TUTORIAL AVAILABLE!](https://www.youtube.com/watch?v=DRT-Cq2vdWs)
 
-We provide Jupyter and COLAB notebooks for using DeepLabCut on both a pre-labeled dataset, and on the end user’s
+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!](/examples) 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)=

diff --git a/docs/api/deeplabcut.analyze_videos.rst b/docs/api/deeplabcut.analyze_videos.rst
@@ -1 +1 @@
-.. autofunction:: deeplabcut.pose_estimation_tensorflow.predict_videos.analyze_videos
+.. autofunction:: deeplabcut.compat.analyze_videos
diff --git a/docs/api/deeplabcut.convert_detections2tracklets.rst b/docs/api/deeplabcut.convert_detections2tracklets.rst
@@ -0,0 +1 @@
+.. autofunction:: deeplabcut.compat.convert_detections2tracklets
diff --git a/docs/api/deeplabcut.create_training_dataset_from_existing_split.rst b/docs/api/deeplabcut.create_training_dataset_from_existing_split.rst
@@ -0,0 +1 @@
+.. autofunction:: deeplabcut.generate_training_dataset.trainingsetmanipulation.create_training_dataset_from_existing_split
diff --git a/docs/api/deeplabcut.evaluate_network.rst b/docs/api/deeplabcut.evaluate_network.rst
@@ -1 +1 @@
-.. autofunction:: deeplabcut.pose_estimation_tensorflow.core.evaluate.evaluate_network
+.. autofunction:: deeplabcut.compat.evaluate_network
diff --git a/docs/api/deeplabcut.label_frames.rst b/docs/api/deeplabcut.label_frames.rst
@@ -1 +1 @@
-.. autofunction:: deeplabcut.gui.label_frames.label_frames
+.. autofunction:: deeplabcut.gui.tabs.label_frames.label_frames
diff --git a/docs/api/deeplabcut.refine_labels.rst b/docs/api/deeplabcut.refine_labels.rst
@@ -1 +1 @@
-.. autofunction:: deeplabcut.gui.refine_labels.refine_labels
+.. autofunction:: deeplabcut.gui.tabs.label_frames.refine_labels
diff --git a/docs/api/deeplabcut.stitch_tracklets.rst b/docs/api/deeplabcut.stitch_tracklets.rst
@@ -0,0 +1 @@
+.. autofunction:: deeplabcut.refine_training_dataset.stitch.stitch_tracklets
diff --git a/docs/api/deeplabcut.train_network.rst b/docs/api/deeplabcut.train_network.rst
@@ -1 +1 @@
-.. autofunction:: deeplabcut.pose_estimation_tensorflow.training.train_network
+.. autofunction:: deeplabcut.compat.train_network
diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md
@@ -38,13 +38,13 @@ Now, we are going to install the core dependencies. The way this works is that t
 
 `PyTorch` is the backend deep-learning language we wrote DLC3 in. To select the right version, head to the [“Install PyTorch”](https://pytorch.org/get-started/locally/) instructions in the official PyTorch Docs. Select your desired PyTorch build, operating system, select conda as your package manager and Python as the language. Select your compute platform (either a CUDA version or CPU only). Then, use the command to install the PyTorch package. Below are a few possible examples:
 
-- **GPU version of pytorch for CUDA 11.8**
+- **GPU version of pytorch for CUDA 12.4**
 ```
-conda install pytorch cudatoolkit=11.8 -c pytorch
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
 ```
 - **CPU only version of pytorch, using the latest version**
 ```
-conda install pytorch cpuonly -c pytorch
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
 ```
 
 **(2) Install DeepLabCut** 
@@ -61,7 +61,7 @@ pip install "git+https://github.com/DeepLabCut/DeepLabCut.git@pytorch_dlc#egg=de
 ```
 - OR run for the **Stable release:**
 ```
-pip install "deeplabcut[gui,modelzoo,tf]"
+pip install "deeplabcut[gui,modelzoo,wandb]"
 ```
 - This gives you DeepLabCut, the DLC GUI (gui), our latest neural networks (modelzoo) and a cool data logger (wandb) if you choose to use it later on!
 

diff --git a/docs/benchmark.md b/docs/benchmark.md
@@ -32,4 +32,4 @@ benchmarks. For an example of how to implement a benchmark submission, refer to
 .. automodule:: deeplabcut.benchmark.metrics
    :members:
    :show-inheritance:
-```
+```
diff --git a/docs/gui/napari_GUI.md b/docs/gui/napari_GUI.md
@@ -1,3 +1,4 @@
+(napari-gui)=
 # napari labeling GUI
 
 We replaced wxPython with PySide6 + as of version 2.3. Here is how to use the napari-aspects of the new GUI. It is available in napari-hub as a stand alone GUI as well as integrated into our main GUI, [please see docs here](https://deeplabcut.github.io/DeepLabCut/docs/PROJECT_GUI.html).

diff --git a/docs/images/box1-multi.png b/docs/images/box1-multi.png
diff --git a/docs/images/box1-single.png b/docs/images/box1-single.png
diff --git a/docs/installation.md b/docs/installation.md
@@ -24,15 +24,15 @@
   - **Apple M-chip GPU?** Be sure to install miniconda3, and your GPU will be used by default.
 ````
 
-
 ### Step 1: Install Python via Anaconda
 
-#### Install [anaconda](https://www.anaconda.com/distribution/), or use miniconda3 for MacOS users (see below)
+#### Install [anaconda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html#), or use miniconda3 for MacOS users (see below)
 
 - Anaconda is an easy way to install Python and additional packages across various operating systems. With Anaconda you create all the dependencies in an [environment](https://conda.io/docs/user-guide/tasks/manage-environments.html) on your machine.
 
 ```{Hint}
-Download anaconda for your operating system: https://www.anaconda.com/distribution/.
+Download anaconda for your operating system: [anaconda.com/download/
+](https://www.anaconda.com/download/)
 ```
 
 - IF you use a M1 or M2 chip in your MacBook with v12.5+ (typically 2020 or newer machines), we recommend **miniconda3,** which operates with the same principles as anaconda. This is straight forward and explained in detail here: https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html. But in short, open the program "terminal" and copy/paste and run the code that is supplied below.
@@ -84,10 +84,44 @@ Now you should see (`nameofenv`) on the left of your terminal screen, i.e. ``(DE
 NOTE: no need to run pip install deeplabcut, as it is already installed!!! :)
 
 #### 💡 Notice: PyTorch and TensorFlow Support within DeepLabCut
-```{Hint}
+
+````{admonition} DeepLabCut TensorFlow Support
 :class: dropdown
-As of June 2024 we have a PyTorch Engine backend and we will be depreciating the TensorFlow backend by the end of 2024. Currently, if you want to use TensorFlow, you need to run `pip install deeplabcut[tf]` in order to install the correct version of TensorFlow in your conda env. Please note, we will be providing bug fixes, but we will not be supporting new TensorFlow versions beyond 2.10 (Windows), and 2.12 for other OS.
+As of June 2024 we have a PyTorch Engine backend and we will be depreciating the 
+TensorFlow backend by the end of 2024. Currently, if you want to use TensorFlow, you 
+need to run `pip install deeplabcut[tf]` in order to install the correct version of 
+TensorFlow in your conda env. Please note, we will be providing bug fixes, but we will 
+not be supporting new TensorFlow versions beyond 2.10 (Windows), and 2.12 for other OS.
+
+Installing TensorFlow and getting it to have access to the GPU can be a bit tricky. 
+Check TensorFlow's [compatibility matrix](https://www.tensorflow.org/install/source#gpu)
+to know which version of CUDA and cuDNN you should install.
+
+We have found that installing DeepLabCut with the following commands works well for
+Linux users to install PyTorch 2.3.1, TensorFlow 2.12, CUDA 11.8 and cuDNN 8 in a Conda
+environment:
+
+```script
+conda create -n deeplabcut-with-tf "python=3.10"
+conda activate deeplabcut-with-tf
+
+# Install the desired TensorFlow version, built for CUDA 11.8 and cuDNN 8
+pip install "tensorflow==2.12" "tensorpack>=0.11" "tf_slim>=1.1.0"
+
+# Install PyTorch with a version using CUDA 11.8 and cuDNN 8
+pip install "torch==2.3.1" torchvision --index-url https://download.pytorch.org/whl/cu118
+
+# Create symbolic links to NVIDIA shared libraries for TensorFlow
+#   -> as described in their installation docs:
+#      https://www.tensorflow.org/install/pip#step-by-step_instructions
+
+pushd $(dirname $(python -c 'print(__import__("tensorflow").__file__)'))
+ln -svf ../nvidia/*/lib/*.so* .
+popd
+
+pip install deeplabcut
 ```
+````
 
 **Great, that's it! DeepLabCut is installed!** 🎉💜
 
@@ -168,7 +202,7 @@ The ONLY thing you need to do **first** if you have an NVIDIA GPU and the matchi
 
   `nvcc -V` to check your installed version(s).
 
-- The best practice is to then run the supplied `testscript.py` (this is inside the examples folder you acquired when you git cloned the repo). Here is more information/a short [video on running the testscript](https://www.youtube.com/watch?v=IOWtKn3l33s).
+- The best practice is to then run the supplied `testscript_pytorch_single_animal.py` (or `testscript.py` for the TensorFlow engine); this is inside the examples folder you acquired when you git cloned the repo. Here is more information/a short [video on running the testscript](https://www.youtube.com/watch?v=IOWtKn3l33s).
 
 - Additionally, if you want to use the bleeding edge, with yout git clone you also get the latest code. While inside the main DeepLabCut folder, you can run `./reinstall.sh` to be sure it's installed (more here: https://github.com/DeepLabCut/DeepLabCut/wiki/How-to-use-the-latest-GitHub-code)
 
@@ -230,7 +264,3 @@ If you perform the system-wide installation, and the computer has other Python p
        - If you want to use a pre3.0 version, you will need [TensorFlow](https://www.tensorflow.org/) (we used version 1.0 in the Nature Neuroscience paper, later versions also work with the provided code (we tested **TensorFlow versions 1.0 to 1.15, and 2.0 to 2.10**; we recommend TF2.10 now) for Python 3.8, 3.9, 3.10 with GPU support.
         - To note, is it possible to run DeepLabCut on your CPU, but it will be VERY slow (see: [Mathis & Warren](https://www.biorxiv.org/content/early/2018/10/30/457242)). However, this is the preferred path if you want to test DeepLabCut on your own computer/data before purchasing a GPU, with the added benefit of a straightforward installation! Otherwise, use our COLAB notebooks for GPU access for testing.
      - Docker: We highly recommend advanced users use the supplied [Docker container](docker-containers)
-
-
-
-Return to [readme](readme).
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		.. autofunction:: deeplabcut.pose_estimation_tensorflow.predict_videos.analyze_videos
		.. autofunction:: deeplabcut.compat.analyze_videos
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		.. autofunction:: deeplabcut.compat.convert_detections2tracklets
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		.. autofunction:: deeplabcut.generate_training_dataset.trainingsetmanipulation.create_training_dataset_from_existing_split
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		.. autofunction:: deeplabcut.pose_estimation_tensorflow.core.evaluate.evaluate_network
		.. autofunction:: deeplabcut.compat.evaluate_network
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		.. autofunction:: deeplabcut.gui.label_frames.label_frames
		.. autofunction:: deeplabcut.gui.tabs.label_frames.label_frames
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		.. autofunction:: deeplabcut.gui.refine_labels.refine_labels
		.. autofunction:: deeplabcut.gui.tabs.label_frames.refine_labels
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		.. autofunction:: deeplabcut.refine_training_dataset.stitch.stitch_tracklets
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		.. autofunction:: deeplabcut.pose_estimation_tensorflow.training.train_network
		.. autofunction:: deeplabcut.compat.train_network