Documentation : Update formatting of single animal guide by C-Achard · Pull Request #3315 · DeepLabCut/DeepLabCut

C-Achard · 2026-05-07T08:34:41Z

Motivation

The single animal guide has some older formatting present that could be improved in order to help navigation in the document, and better focus the attention of users on important concepts.

Scope

Refreshes the guide's format to be more MyST-like, more consistent, and provide better navigation with a contents table and working links, as well as more bullet lists and consistent section headers throughout.

TODO

Finish converting images to figures with proper refs
Fix markdown links using []() to be proper {ref} directives.

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.

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 <img>/<p> 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.

Update documentation for the single-animal user guide: convert local link refs to file:single-animal-userguide, fix napari link formatting, and reorganize/clarify many sections in standardDeepLabCut_UserGuide.md. Added consistent subsection headings (Overview, Code example, Output, etc.), separators, code block language annotations, a schematic of the training dataset layout, and improved wording/indentation for lists and examples. Also updated UseOverviewGuide.md to point to the revised single-animal guide. These changes improve readability, provide clearer examples, and make the workflow steps and outputs easier to follow.

Minor documentation cleanup in docs/standardDeepLabCut_UserGuide.md: split the conda activation into its own numbered step, simplify wording and line breaks for clarity, and remove bold all-caps headings (OVERVIEW and MODEL COMPARISON) in favor of normal sentences. Purely editorial changes; no functional code changes.

Copilot

Pull request overview

Updates the single-animal documentation to use more consistent MyST/Sphinx-friendly formatting (admonitions, images/figures, headings) and improves navigability via an in-page contents block and reorganized sections.

Changes:

Refactors standardDeepLabCut_UserGuide.md into a more structured MyST format (contents directive, admonitions, images-as-directives, reorganized headings/lists).
Updates UseOverviewGuide.md to point readers to the single-animal guide using the new target label.
Adds a Windows “run as administrator” admonition to the Project Manager GUI doc.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
docs/UseOverviewGuide.md	Updates links pointing to the single-animal guide.
docs/standardDeepLabCut_UserGuide.md	Major MyST formatting refresh: contents block, directive-based images, admonitions, and section restructuring.
docs/gui/PROJECT_GUI.md	Adds an `{important}` note about Windows admin terminal usage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

  - 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)
+  - (1) \[How to use standard DeepLabCut\](file:single-animal-userguide)


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

- (1) [How to use standard DeepLabCut](single-animal-userguide)
+- (1) \[How to use standard DeepLabCut\](file:single-animal-userguide)


deruyter92 · 2026-05-12T14:17:29Z

 all the extracted frames using an interactive graphical user interface (GUI). The user
 should have already named the bodyparts to label (points of interest) in the
 project’s configuration file by providing a list. The following command invokes the
 napari-deeplabcut labelling GUI. Checkout the \[napari-deeplabcut docs\](file:napari-gui-landing) for


Seems like a valid concern? This occurs multiple times, maybe worth addressing if that is possible.

@@ -285,22 +415,30 @@ Saving the labels after all the images are labelled will append the new labels t
 For more information, checkout the \[napari-deeplabcut docs\](file:napari-gui-landing) for


@@ -1033,6 +1281,8 @@ This will launch a GUI where the user can refine the labels.

 Please refer to the \[napari-deeplabcut docs\](file:napari-gui-landing) for more information about the labelling workflow.


+  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.
+


deruyter92 · 2026-05-12T14:06:53Z

-parameters in the config.yaml file. Also, the user can change the number of frames to extract from each video using
-the numframes2extract in the config.yaml file.
+parameters in the config.yaml file.
+Also, the user can change the number of frames to extract from each video using the numframes2extract in the config.yaml file.


Suggested change

Also, the user can change the number of frames to extract from each video using the numframes2extract in the config.yaml file.

Also, the user can change the number of frames to extract from each video using the numframes2pick in the config.yaml file.

deruyter92 · 2026-05-12T14:11:58Z


+#### Overview
+
 You can also filter the predictions with a median filter (default) or with a [SARIMAX model](https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAX.html), if you wish. This creates a new .h5 file with the ending *\_filtered* that you can use in create_labeled_data and/or plot trajectories.


Suggested change

You can also filter the predictions with a median filter (default) or with a [SARIMAX model](https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAX.html), if you wish. This creates a new .h5 file with the ending *\_filtered* that you can use in create_labeled_data and/or plot trajectories.

You can also filter the predictions with a median filter (default) or with a [SARIMAX model](https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAX.html), if you wish. This creates a new .h5 file with the ending *\_filtered* that you can use in create_labeled_video and/or plot trajectories.

deruyter92 · 2026-05-12T14:12:34Z

+
 To draw a skeleton, you need to first define the pairs of connected nodes (in the `config.yaml` file) and set the
 skeleton color (in the `config.yaml` file). There is also a GUI to help you do this, use by calling
 `deeplabcut.SkeletonBuilder(configpath)`!


Suggested change

`deeplabcut.SkeletonBuilder(configpath)`!

`deeplabcut.SkeletonBuilder(config_path)`!

deruyter92 · 2026-05-12T14:14:05Z

@@ -713,10 +902,16 @@ dynamic: triple containing (state, detectiontreshold, margin)
    given the movement of the animal).


Suggested change

fraction, you can crop around your animal/object to make processing speeds faster. For example, if you have a large open

field experiment but only track the mouse, this will speed up your analysis (also helpful for real-time applications).

To use this simply add `dynamic=(True,.5,10)` when you call `analyze_videos`.

```python

dynamic: triple containing (state, detectionthreshold, margin)

If the state is true, then dynamic cropping will be performed.

That means that if an object is detected (i.e., any body part > detectionthreshold),

then object boundaries are computed according to the smallest/largest x position and

smallest/largest y position of all body parts. This window is expanded by the margin

and from then on only the posture within this crop is analyzed (until the object is lost;

i.e., < detectionthreshold). The current position is utilized for updating the crop window

for the next frame (this is why the margin is important and should be set large enough

given the movement of the animal).

deruyter92 · 2026-05-12T14:14:37Z

+
+#### Optional addition of more labels

 OPTIONAL: In the event of adding more labels to the existing labeled dataset, the user need to append the new


Suggested change

OPTIONAL: In the event of adding more labels to the existing labeled dataset, the user need to append the new

OPTIONAL: In the event of adding more labels to the existing labeled dataset, the user needs to append the new

deruyter92 · 2026-05-12T14:15:03Z

+   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


Suggested change

particular experiment: trained and tested on a particular training and testing sets, and with a particular model

particular experiment: trained and tested on a particular training and testing set, and with a particular model

deruyter92 · 2026-05-12T14:15:27Z

@@ -357,7 +518,7 @@ and `augmenter_type` when you call the function.
  suggest seeing our [dedicated documentation on models](dlc3-architectures) for more information (


Suggested change

and `augmenter_type` when you call the function.

- Networks: ImageNet pre-trained networks OR SuperAnimal pre-trained network weights will be downloaded, as you

select. You can decide to do transfer-learning (recommended) or "fine-tune" both the backbone and the decoder head. We

suggest seeing our [dedicated documentation on models](dlc3-architectures) for more information (

deruyter92 · 2026-05-12T14:15:55Z

+#### Overview
+
 The plotting components of this toolbox utilizes matplotlib. Therefore, these plots can easily be customized by
 the end user. We also provide a function to plot the trajectory of the extracted poses across the analyzed video, which
 can be called by typing:

-```
-deeplabcut.plot_trajectories(config_path, [‘fullpath/analysis/project/videos/reachingvideo1.avi’])
+#### Code example


Suggested change

#### Overview

The plotting components of this toolbox utilizes matplotlib. Therefore, these plots can easily be customized by

the end user. We also provide a function to plot the trajectory of the extracted poses across the analyzed video, which

can be called by typing:

```

deeplabcut.plot_trajectories(config_path, [‘fullpath/analysis/project/videos/reachingvideo1.avi’])

#### Code example

#### Overview

The plotting components of this toolbox utilize matplotlib. Therefore, these plots can easily be customized by

the end user. We also provide a function to plot the trajectory of the extracted poses across the analyzed video, which

can be called by typing:

#### Code example

deruyter92 · 2026-05-12T14:17:29Z

 all the extracted frames using an interactive graphical user interface (GUI). The user
 should have already named the bodyparts to label (points of interest) in the
 project’s configuration file by providing a list. The following command invokes the
 napari-deeplabcut labelling GUI. Checkout the \[napari-deeplabcut docs\](file:napari-gui-landing) for


Seems like a valid concern? This occurs multiple times, maybe worth addressing if that is possible.

C-Achard added 5 commits May 6, 2026 15:20

Fix figure

97a3e7a

C-Achard added this to the Docs audit: April 2026 milestone May 7, 2026

C-Achard requested a review from Copilot May 7, 2026 08:34

C-Achard self-assigned this May 7, 2026

C-Achard added enhancement New feature or request documentation documentation updates/comments labels May 7, 2026

Copilot started reviewing on behalf of C-Achard May 7, 2026 08:35 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

deruyter92 self-requested a review May 11, 2026 14:05

deruyter92 reviewed May 12, 2026

View reviewed changes

deruyter92 approved these changes May 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Documentation : Update formatting of single animal guide#3315

Documentation : Update formatting of single animal guide#3315
C-Achard wants to merge 5 commits into
cy/docs-audit-2026-toc-updatefrom
cy/docs-audit-2026-update-single-animal

C-Achard commented May 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

deruyter92 May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -285,22 +415,30 @@ Saving the labels after all the images are labelled will append the new labels t
		For more information, checkout the \[napari-deeplabcut docs\](file:napari-gui-landing) for

		@@ -1033,6 +1281,8 @@ This will launch a GUI where the user can refine the labels.

		Please refer to the \[napari-deeplabcut docs\](file:napari-gui-landing) for more information about the labelling workflow.

		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.

	Also, the user can change the number of frames to extract from each video using the numframes2extract in the config.yaml file.
	Also, the user can change the number of frames to extract from each video using the numframes2pick in the config.yaml file.


		#### Overview

		You can also filter the predictions with a median filter (default) or with a [SARIMAX model](https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAX.html), if you wish. This creates a new .h5 file with the ending \_filtered that you can use in create_labeled_data and/or plot trajectories.

	`deeplabcut.SkeletonBuilder(configpath)`!
	`deeplabcut.SkeletonBuilder(config_path)`!

		@@ -713,10 +902,16 @@ dynamic: triple containing (state, detectiontreshold, margin)
		given the movement of the animal).

+fraction, you can crop around your animal/object to make processing speeds faster. For example, if you have a large open
+field experiment but only track the mouse, this will speed up your analysis (also helpful for real-time applications).
+To use this simply add `dynamic=(True,.5,10)` when you call `analyze_videos`.
+```python
+dynamic: triple containing (state, detectionthreshold, margin)
+    If the state is true, then dynamic cropping will be performed.
+    That means that if an object is detected (i.e., any body part > detectionthreshold),
+    then object boundaries are computed according to the smallest/largest x position and
+    smallest/largest y position of all body parts. This window is expanded by the margin
+    and from then on only the posture within this crop is analyzed (until the object is lost;
+    i.e., < detectionthreshold). The current position is utilized for updating the crop window
+    for the next frame (this is why the margin is important and should be set large enough
+    given the movement of the animal).


		#### Optional addition of more labels

		OPTIONAL: In the event of adding more labels to the existing labeled dataset, the user need to append the new

	particular experiment: trained and tested on a particular training and testing sets, and with a particular model
	particular experiment: trained and tested on a particular training and testing set, and with a particular model

		@@ -357,7 +518,7 @@ and `augmenter_type` when you call the function.
		suggest seeing our [dedicated documentation on models](dlc3-architectures) for more information (

Uh oh!

Conversation

C-Achard commented May 7, 2026

Motivation

Scope

TODO

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants