Add PyTorch🔥 documentation (DeepLabCut#2605)

* added initial pytorch docs * Update _toc.yml * Update user_guide.md * Update architectures.md * Update labelling.md * Update labelling.md * Update codespell.yml * Update README.md * Update installation.md * Delete conda-environments/DEEPLABCUT_M1.yaml * Update DEEPLABCUT.yaml * Update installation.md * Update maDLC_UserGuide.md * Update ModelZoo.md * Update standardDeepLabCut_UserGuide.md * Update standardDeepLabCut_UserGuide.md * Update standardDeepLabCut_UserGuide.md * Update Overviewof3D.md * Update PROJECT_GUI.md * Update UseOverviewGuide.md * Update beginners-guide.md * Update intro.md * Update architectures.md * Update architectures.md * Create course.md - updating and migration from workshop materials * Update _toc.yml * Update manage-project.md * Update beginners-guide.md * Update manage-project.md * Update _toc.yml * Rename labelling.md to labeling.md * Update Training-Evaluation.md * Update video-analysis.md * Update architectures.md * Update architectures.md * Update AUTHORS * Update architectures.md * doc clean up, tested local build * Update beginners-guide.md * Update ModelZoo.md * Update ModelZoo.md * Update ModelZoo.md * Update ModelZoo.md * Update README.md - small resize on homepage * Update ModelZoo.md * Update ModelZoo.md - link update * Update AUTHORS * Update README.md - add badge for python version supported * Update installation.md * Update DEEPLABCUT.yaml - this, for now, will install from branch source (assuming the branch is named "pytorch_dlc" * Update DEEPLABCUT.yaml * Update AUTHORS * fixed typos * Update python-package.yml * Update README.md * Update beginners-guide.md * Update user_guide.md * m1 for tf only * Update README.md --------- Co-authored-by: Mackenzie Mathis <[email protected]> Co-authored-by: Mackenzie Mathis <[email protected]>
wer-kle · Jun 14, 2024 · fa89f7f · fa89f7f
1 parent 2d70052
commit fa89f7f
Show file tree

Hide file tree

Showing 27 changed files with 1,159 additions and 462 deletions.
diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
@@ -17,3 +17,5 @@ jobs:
         uses: actions/checkout@v3
       - name: Codespell
         uses: codespell-project/actions-codespell@v1
+        with:
+           ignore_words_list: bu,BU,td,TD,ctd,CTD, Wither
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -14,7 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-13, windows-latest]
-        python-version: [3.9, "3.10"]
+        python-version: ["3.10"]
         include:
           - os: ubuntu-latest
             path: ~/.cache/pip

diff --git a/AUTHORS b/AUTHORS
@@ -1,5 +1,5 @@
 DeepLabCut (www.deeplabcut.org) was initially developed by
-Alexander & Mackenzie Mathis in collaboration with Matthias Bethge.
+Alexander & Mackenzie Mathis in collaboration with Matthias Bethge in 2017.
 It is actively developed by Alexander & Mackenzie Mathis (steering council and owners).
 
 DeepLabCut is an open-source tool and has benefited from suggestions and edits by many
@@ -108,13 +108,32 @@ A Mathis, [email protected] | https://github.com/AlexEMG
 M Mathis, [email protected] | https://github.com/MMathisLab
 J Lauer, [email protected] | https://github.com/jeylau
 N Poulsen, [email protected] | https://github.com/n-poulsen
-S Ye, https://github.com/yeshaokai
+S Schneider, [email protected] | https://github.com/stes
+S Ye, [email protected] | https://github.com/yeshaokai
 
 Preprint:
-Ye, S., Filippova, A., Lauer, J., Vidal, M., Schneider, S., Qiu, T., Mathis, A., & Mathis, M.W. (2022).
+Ye, S., Filippova, A., Lauer, J., Schneider, S., Vidal, M., Qiu, T., Mathis, A., & Mathis, M.W. (2023).
 SuperAnimal pretrained pose estimation models for behavioral analysis. https://arxiv.org/abs/2203.07436
 
 
 ############################################################################################################
-DeepLabCut 3.0+ additions:
-staty tuned, but includes BUCTD!
+
+DeepLabCut 3.0 Toolbox
+M Mathis, [email protected] | https://github.com/MMathisLab
+A Mathis, [email protected] | https://github.com/AlexEMG
+N Poulsen, [email protected] | https://github.com/n-poulsen
+S Ye, [email protected] | https://github.com/yeshaokai
+A Filippova, [email protected] | https://github.com/nastya236
+Q Macé | https://github.com/QuentinJGMace
+J Lauer, [email protected] | https://github.com/jeylau
+L Stoffl, [email protected] | https://github.com/LucZot
+
+We also greatly thank the 2023 DeepLabCut AI Residents who contributed:
+Anna Teruel-Sanchis | https://github.com/anna-teruel
+Riza Rae Pineda | https://github.com/rizarae-p
+Konrad Danielewski | https://github.com/KonradDanielewski
+
+Products:
+PyTorch backend for DeepLabCut
+Expanded SuperAnimal capabilities
+New model architectures (WIP: stay tuned, but includes BUCTD)
diff --git a/README.md b/README.md
@@ -6,14 +6,14 @@
 </p>
 
 <p align="center">
-<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1665060917309-V0YVY2UKVLKSS6O18XDI/MousereachGIF.gif?format=1000w?format=250w" height="150">
+<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1665060917309-V0YVY2UKVLKSS6O18XDI/MousereachGIF.gif?format=1000w?format=180w" height="150">
 
-<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/daed7f16-527f-4150-8bdd-cbb20e267451/cheetah-ezgif.com-video-to-gif-converter.gif?format=250w" height="150">
+<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/daed7f16-527f-4150-8bdd-cbb20e267451/cheetah-ezgif.com-video-to-gif-converter.gif?format=180w" height="150">
 
 
-<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1534797521117-EIEUED03C68241QZ4KCK/ke17ZwdGBToddI8pDm48kAx9qLOWpcHWRGxWsJQSczRZw-zPPgdn4jUwVcJE1ZvWQUxwkmyExglNqGp0IvTJZUJFbgE-7XRK3dMEBRBhUpwdr4GYy30vFzf31Oe7KAPZKkqgaiEgc5jBNdhZmDPlzxdkDSclo6ofuXZm6YCEhUo/MATHIS_2018_fly.gif?format=250w" height="150">
+<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1534797521117-EIEUED03C68241QZ4KCK/ke17ZwdGBToddI8pDm48kAx9qLOWpcHWRGxWsJQSczRZw-zPPgdn4jUwVcJE1ZvWQUxwkmyExglNqGp0IvTJZUJFbgE-7XRK3dMEBRBhUpwdr4GYy30vFzf31Oe7KAPZKkqgaiEgc5jBNdhZmDPlzxdkDSclo6ofuXZm6YCEhUo/MATHIS_2018_fly.gif?format=180w" height="150">
 
-<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1619609897110-TKSTWKEM6HTGXID9D489/ke17ZwdGBToddI8pDm48kAvjv6tW_eojYQmNU0ncbllZw-zPPgdn4jUwVcJE1ZvWEtT5uBSRWt4vQZAgTJucoTqqXjS3CfNDSuuf31e0tVHBSTXHtjUKlhRtWJ1Vo6l1B2bxJtByvWSjL6Vz3amc5yb8BodarTVrzIWCp72ioWw/triMouseDLC.gif?format=250w" height="150">
+<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1619609897110-TKSTWKEM6HTGXID9D489/ke17ZwdGBToddI8pDm48kAvjv6tW_eojYQmNU0ncbllZw-zPPgdn4jUwVcJE1ZvWEtT5uBSRWt4vQZAgTJucoTqqXjS3CfNDSuuf31e0tVHBSTXHtjUKlhRtWJ1Vo6l1B2bxJtByvWSjL6Vz3amc5yb8BodarTVrzIWCp72ioWw/triMouseDLC.gif?format=180w" height="150">
 
 
 
@@ -34,6 +34,7 @@
 [👩🏾‍💻👨‍💻 DeepLabCut AI Residency](https://www.deeplabcutairesidency.org/) 
 
 
+![Vesion](https://img.shields.io/badge/python_version-3.10-purple)
 [![Downloads](https://pepy.tech/badge/deeplabcut)](https://pepy.tech/project/deeplabcut)
 [![Downloads](https://pepy.tech/badge/deeplabcut/month)](https://pepy.tech/project/deeplabcut)
 [![PyPI version](https://badge.fury.io/py/deeplabcut.svg)](https://badge.fury.io/py/deeplabcut)
@@ -58,8 +59,15 @@
 
 # [Installation: how to install DeepLabCut](https://deeplabcut.github.io/DeepLabCut/docs/installation.html)
 
-Very quick start: `pip install "deeplabcut[gui,tf]"` that 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). Please note that currently we support Python 3.9 (see conda files for guidance).
+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).
+
+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)
 
@@ -209,6 +217,8 @@ SuperAnimal models are provided for research use only (non-commercial use).
 
 - For all versions, please see [here](https://github.com/DeepLabCut/DeepLabCut/releases).
 
+VERSION 3.0: A whole new experience with PyTorch🔥. While the high-level API remains the same, the backend and developer friendliness have greatly improved, along with performance gains!
+
 VERSION 2.3: Model Zoo SuperAnimals, and a whole new GUI experience.
 
 VERSION 2.2: Multi-animal pose estimation, identification, and tracking with DeepLabCut is supported (as well as single-animal projects).
@@ -220,6 +230,8 @@ VERSION 1.0: The initial, Nature Neuroscience version of [DeepLabCut](https://ww
 
 # News (and in the news):
 
+:purple_heart: We released a major update, moving from 2.x --> 3.x with the backend change to PyTorch
+
 :purple_heart: The DeepLabCut Model Zoo launches SuperAnimals, see more [here](http://www.mackenziemathislab.org/dlc-modelzoo/).
 
 :purple_heart: **DeepLabCut supports multi-animal pose estimation!** maDLC is out of beta/rc mode and beta is deprecated, thanks to the testers out there for feedback! Your labeled data will be backwards compatible, but not all other steps. Please see the [new `2.2+` releases](https://github.com/DeepLabCut/DeepLabCut/releases) for what's new & how to install it, please see our new [paper, Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0), and the [new docs]( https://deeplabcut.github.io/DeepLabCut) on how to use it!
@@ -228,6 +240,9 @@ VERSION 1.0: The initial, Nature Neuroscience version of [DeepLabCut](https://ww
 
 :purple_heart: We have a **real-time** package available! http://DLClive.deeplabcut.org
 
+
+- June 2024: Our second DLC paper ['Using DeepLabCut for 3D markerless pose estimation across species and behaviors'](https://www.nature.com/articles/s41596-019-0176-0) in Nature Protocols has surpassed 1,000 Google Scholar citations!
+- May 2024: DeepLabCut was featured in Nature: ['DeepLabCut: the motion-tracking tool that went viral'](https://www.nature.com/articles/d41586-024-01474-x)
 - January 2024: Our original paper ['DeepLabCut: markerless pose estimation of user-defined body parts with deep learning'](https://www.nature.com/articles/s41593-018-0209-y) in Nature Neuroscience has surpassed 3,000 Google Scholar citations! 
 - December 2023: DeepLabCut hit 600,000 downloads!
 - October 2023: DeepLabCut celebrates a milestone with 4,000 🌟 in Github!

diff --git a/_toc.yml b/_toc.yml
@@ -4,6 +4,7 @@ parts:
 - caption: Getting Started
   chapters:
   - file: docs/UseOverviewGuide
+  - file: docs/course
 - caption: Installation
   chapters:
   - file: docs/installation
@@ -17,12 +18,24 @@ parts:
   - file: docs/HelperFunctions
 - caption: Graphical User Interfaces (GUIs)
   chapters:
-  - file: docs/PROJECT_GUI
-  - file: docs/napari_GUI
+  - file: docs/gui/PROJECT_GUI
+  - file: docs/gui/napari_GUI
+- caption: DLC3 PyTorch Specific Docs
+  chapters:
+  - file: docs/pytorch/user_guide.md
+  - file: docs/pytorch/pytorch_config.md
+  - file: docs/pytorch/architectures.md
 - caption: Quick Start Tutorials
   chapters:
-  - file: docs/single_animal_quick_guide
-  - file: docs/tutorial_maDLC
+  - file: docs/quick-start/single_animal_quick_guide
+  - file: docs/quick-start/tutorial_maDLC
+- caption: Beginner's Guide to DeepLabCut
+  chapters:
+  - file: docs/beginner-guides/beginners-guide
+  - file: docs/beginner-guides/manage-project
+  - file: docs/beginner-guides/labeling
+  - file: docs/beginner-guides/Training-Evaluation
+  - file: docs/beginner-guides/video-analysis
 - caption: Hardware Tips
   chapters:
   - file: docs/recipes/TechHardware
@@ -34,7 +47,7 @@ parts:
   - file: docs/ModelZoo
   - file: docs/recipes/UsingModelZooPupil
   - file: docs/recipes/MegaDetectorDLCLive
-- caption: Cookbook
+- caption: Cookbook (detailed helper guides)
   chapters:
   - file: docs/tutorial
   - file: docs/convert_maDLC
@@ -48,13 +61,6 @@ parts:
   - file: docs/recipes/flip_and_rotate
   - file: docs/recipes/pose_cfg_file_breakdown
   - file: docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook
-- caption: Beginner's Guide to DeepLabCut in the GUI
-  chapters:
-  - file: docs/beginners-guide
-  - file: docs/manage-project
-  - file: docs/labelling
-  - file: docs/Training-Evaluation
-  - file: docs/video-analysis
 - caption: DeepLabCut Benchmark
   chapters:
   - file: docs/benchmark

diff --git a/conda-environments/DEEPLABCUT.yaml b/conda-environments/DEEPLABCUT.yaml
@@ -1,11 +1,11 @@
 # DEEPLABCUT.yaml
 
-#DeepLabCut2.0 Toolbox (deeplabcut.org)
+#DeepLabCut Toolbox (deeplabcut.org)
 #© A. & M.W. Mathis Labs
 #https://github.com/DeepLabCut/DeepLabCut
 #Please see AUTHORS for contributors.
 
-#https://github.com/DeepLabCut/DeepLabCut/blob/master/AUTHORS
+#https://github.com/DeepLabCut/DeepLabCut/blob/main/AUTHORS
 #Licensed under GNU Lesser General Public License v3.0
 #
 # DeepLabCut environment
@@ -29,4 +29,4 @@ dependencies:
   - ffmpeg
   - pytables==3.8.0
   - pip:
-    - "deeplabcut[gui,tf]"
+    - "git+https://github.com/DeepLabCut/DeepLabCut.git@pytorch_dlc#egg=deeplabcut[gui,modelzoo,wandb]"