From 0107c2ac8a12783bf65dc48ca76b0c1b9ca6563b Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 15:20:09 +0200 Subject: [PATCH 01/10] Start updating single animal docs guide Improve user documentation for the GUI and CLI flows: add an important note to always run the terminal as administrator on Windows, rename and rephrase GUI/CLI headings for clarity, and break out stepwise startup instructions. Restructure the create_new_project section with a concise list of required and optional arguments, add a note explaining symbolic links and why Windows requires admin privileges, include a code example and tip block, and fix Windows path formatting. Minor wording and formatting tweaks throughout to improve readability. --- docs/gui/PROJECT_GUI.md | 4 ++ docs/standardDeepLabCut_UserGuide.md | 61 ++++++++++++++++++---------- 2 files changed, 44 insertions(+), 21 deletions(-) diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index fc450bd64..e4b207bbe 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -23,6 +23,10 @@ While several advanced features are not fully available in this Project GUI, we 1. Install DeepLabCut following the instructions in the {ref}`installation page`. 1. Open the terminal and run: `python -m deeplabcut` +```{important} +If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". +``` +

diff --git a/docs/standardDeepLabCut_UserGuide.md b/docs/standardDeepLabCut_UserGuide.md index 914d85d08..8f50c77c5 100644 --- a/docs/standardDeepLabCut_UserGuide.md +++ b/docs/standardDeepLabCut_UserGuide.md @@ -18,19 +18,18 @@ the same), then please see our [maDLC user guide](multi-animal-userguide). To get started, you can use the GUI, or the terminal. See below. -## DeepLabCut Project Manager GUI (recommended for beginners) +## Using the GUI (recommended for beginners) -**GUI:** +1. To begin, navigate to Anaconda Prompt Terminal and right-click to "open as admin "(Windows), or simply launch + "Terminal" (unix/MacOS) on your computer. +1. We assume you have DeepLabCut installed (if not, see {ref}`file:how-to-install`). Next, launch your conda env (i.e., for example `conda activate DEEPLABCUT`). +1. Then, simply run `python -m deeplabcut`. -To begin, navigate to Anaconda Prompt Terminal and right-click to "open as admin "(Windows), or simply launch -"Terminal" (unix/MacOS) on your computer. We assume you have DeepLabCut installed (if not, see -[install docs](how-to-install)!). Next, launch your conda env (i.e., for example `conda activate DEEPLABCUT`). Then, -simply run `python -m deeplabcut`. The below functions are available to you in an easy-to-use graphical user interface. -While most functionality is available, advanced users might want the additional flexibility that command line interface -offers. Read more below. +Most functions are available to you in the GUI. +However, advanced users might prefer the additional flexibility that command line interface offers. Read more below. -```{Hint} -🚨 If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". +```{important} +If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". ```

@@ -42,7 +41,7 @@ As a reminder, the core functions are described in our Additional functions and features are continually added to the package. Thus, we recommend you read over the protocol and then please look at the following documentation and the doctrings. Thanks for using DeepLabCut! -## DeepLabCut in the Terminal/Command line interface: +## Using the CLI To begin, navigate to Anaconda Prompt Terminal and right-click to "open as admin "(Windows), or simply launch "Terminal" (unix/MacOS) on your computer. We assume you have DeepLabCut installed (if not, see Install docs!). Next, @@ -52,24 +51,40 @@ launch your conda env (i.e., for example `conda activate DEEPLABCUT`) and then t import deeplabcut ``` -```{Hint} -🚨 If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". +```{important} +If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". ``` ### (A) Create a New Project +#### Overview + The function `create_new_project` creates a new project directory, required subdirectories, and a basic project configuration file. Each project is identified by the name of the project (e.g. Reaching), name of the experimenter (e.g. YourName), as well as the date at creation. -Thus, this function requires the user to input the name of the project, the name of the experimenter, and the full -path of the videos that are (initially) used to create the training dataset. +Thus, this function requires the user to input: + +- The name of the project +- The name of the experimenter +- The full path of the videos that are (initially) used to create the training dataset. +- Optional arguments specify: + - The working directory + - Where the project directory will be created + - Whether to copy the videos to the project directory -Optional arguments specify the working directory, where the project directory will be created, and if the user wants -to copy the videos (to the project directory). If the optional argument `working_directory` is unspecified, the -project directory is created in the current working directory, and if `copy_videos` is unspecified symbolic links -for the videos are created in the videos directory. Each symbolic link creates a reference to a video and thus +```{note} +If the optional argument `working_directory` is unspecified, the +project directory is created in the current working directory. + +If `copy_videos` is unspecified symbolic links +for the videos are created in the videos directory. +Each symbolic link creates a reference to a video and thus eliminates the need to copy the entire video to the video directory (if the videos remain at the original location). +This is why administrator privileges are required for Windows users, as creating symbolic links requires them. +``` + +#### Code example ```python deeplabcut.create_new_project( @@ -82,13 +97,17 @@ deeplabcut.create_new_project( ) ``` +#### Additional arguments + **Important path formatting note** Windows users, you must input paths as: `r'C:\Users\computername\Videos\reachingvideo1.avi'` or -` 'C:\\Users\\computername\\Videos\\reachingvideo1.avi'` +`'C:\\Users\\computername\\Videos\\reachingvideo1.avi'` -TIP: you can also place `config_path` in front of `deeplabcut.create_new_project` to create a variable that holds +```{tip} +You can also place `config_path` in front of `deeplabcut.create_new_project` to create a variable that holds the path to the config.yaml file, i.e. `config_path=deeplabcut.create_new_project(...)` +``` This set of arguments will create a project directory with the name **++** in the **Working directory** and From 495b9620aa6b5c7d0d108d4cd79cb709035cac01 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 15:38:16 +0200 Subject: [PATCH 02/10] Refactor user guide to MyST format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert the single-animal user guide to MyST-friendly markdown and improve layout and clarity. Changes include: add a table-of-contents directive; replace raw HTML /

blocks with MyST image directives and metadata; introduce admonitions (important/note/caution/hint) for critical points; restructure the project directory section into bulleted lists and an ASCII tree; clarify Windows path guidance and config.yaml parameter notes; normalize API Docs headings and other formatting fixes. These are documentation/formatting updates to improve rendering and readability—no functional code changes. --- docs/standardDeepLabCut_UserGuide.md | 279 ++++++++++++++++++--------- 1 file changed, 190 insertions(+), 89 deletions(-) diff --git a/docs/standardDeepLabCut_UserGuide.md b/docs/standardDeepLabCut_UserGuide.md index 8f50c77c5..44be88692 100644 --- a/docs/standardDeepLabCut_UserGuide.md +++ b/docs/standardDeepLabCut_UserGuide.md @@ -13,6 +13,13 @@ deeplabcut: # Single animal projects +```{contents} +--- +local: +depth: 2 +--- +``` + This document covers single/standard DeepLabCut use. If you have a complicated multi-animal scenario (i.e., they look the same), then please see our [maDLC user guide](multi-animal-userguide). @@ -32,9 +39,12 @@ However, advanced users might prefer the additional flexibility that command lin If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". ``` -

- -

+```{image} https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1572824438905-QY9XQKZ8LAJZG6BLPWOQ/ke17ZwdGBToddI8pDm48kIIa76w436aRzIF_cdFnEbEUqsxRUqqbr1mOJYKfIPR7LoDQ9mXPOjoJoqy81S2I8N_N4V1vUb5AoIIIbLZhVYxCRW4BPu10St3TBAUQYVKcLthF_aOEGVRewCT7qiippiAuU5PSJ9SSYal26FEts0MmqyMIhpMOn8vJAUvOV4MI/guilaunch.jpg?format=1000w +--- +width: 60% +align: center +--- +``` As a reminder, the core functions are described in our [Nature Protocols paper](https://www.nature.com/articles/s41596-019-0176-0) (published at the time of 2.0.6). @@ -55,6 +65,8 @@ import deeplabcut If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". ``` +## Workflow + ### (A) Create a New Project #### Overview @@ -97,12 +109,13 @@ deeplabcut.create_new_project( ) ``` -#### Additional arguments - -**Important path formatting note** +#### Output & directory structure -Windows users, you must input paths as: `r'C:\Users\computername\Videos\reachingvideo1.avi'` or +```{important} +On Windows, input paths as: +`r'C:\Users\computername\Videos\reachingvideo1.avi'` or `'C:\\Users\\computername\\Videos\\reachingvideo1.avi'` +``` ```{tip} You can also place `config_path` in front of `deeplabcut.create_new_project` to create a variable that holds @@ -110,35 +123,63 @@ the path to the config.yaml file, i.e. `config_path=deeplabcut.create_new_projec ``` This set of arguments will create a project directory with the name -**++** in the **Working directory** and -creates the symbolic links to videos in the **videos** directory. The project directory will have subdirectories: -**dlc-models**, **dlc-models-pytorch**, **labeled-data**, **training-datasets**, and **videos**. All the outputs -generated during the course of a project will be stored in one of these subdirectories, thus allowing each project to be -curated in separation from other projects. The purpose of the subdirectories is as follows: - -**dlc-models** and **dlc-models-pytorch** have a similar structure; the first contains files for the TensorFlow engine -while the second contains files for the PyTorch engine. At the top level in these directories, there are directories -referring to different iterations of label refinement (see below): **iteration-0**, **iteration-1**, etc. -The iteration directories store shuffle directories, where each shuffle directory stores model data related to a -particular experiment: trained and tested on a particular training and testing sets, and with a particular model -architecture. Each shuffle directory contains the subdirectories *test* and *train*, each of which holds the meta -information with regard to the parameters of the feature detectors in configuration files. The configuration files are -YAML files, a common human-readable data serialization language. These files can be opened and edited with standard text -editors. The subdirectory *train* will store checkpoints (called snapshots) during training of the model. These -snapshots allow the user to reload the trained model without re-training it, or to pick-up training from a particular -saved checkpoint, in case the training was interrupted. - -**labeled-data:** This directory will store the frames used to create the training dataset. Frames from different videos -are stored in separate subdirectories. Each frame has a filename related to the temporal index within the corresponding -video, which allows the user to trace every frame back to its origin. - -**training-datasets:** This directory will contain the training dataset used to train the network and metadata, which -contains information about how the training dataset was created. - -**videos:** Directory of video links or videos. When **copy_videos** is set to `False`, this directory contains -symbolic links to the videos. If it is set to `True` then the videos will be copied to this directory. The default is -`False`. Additionally, if the user wants to add new videos to the project at any stage, the function -**add_new_videos** can be used. This will update the list of videos in the project's configuration file. +**++** in the **Working directory** and creates the symbolic links to videos in the videos directory. + +The project directory will have subdirectories: + +- dlc-models +- dlc-models-pytorch +- labeled-data +- training-datasets +- videos + All the outputs generated during the course of a project will be stored in one of these subdirectories, thus allowing each project to be + curated in separation from other projects. + +``` +++/ +├── dlc-models/ +│ ├── iteration-0/ +│ ├── iteration-1/ +│ └── ... +├── dlc-models-pytorch/ +│ ├── iteration-0/ +│ │ └── / +│ │ ├── train/ +│ │ └── test/ +│ ├── iteration-1/ +│ └── ... +├── labeled-data/ +│ └──