Skip to content

Commit 4a1d500

Browse files
rahulporuriMMathisLabjeylau
authored
Add more API documentation in user guide (DeepLabCut#1814)
* DOCS : Add more API documentation in user guide API documentation for the following functions is added in this commit - deeplabcut.analyze_videos - deeplabcut.analyzeskeleton - deeplabcut.create_labeled_video - deeplabcut.evaluate_network - deeplabcut.extract_outlier_frames - deeplabcut.filterpredictions - deeplabcut.merge_datasets - deeplabcut.plot_trajectories modified: deeplabcut/pose_estimation_tensorflow/core/evaluate.py modified: deeplabcut/pose_estimation_tensorflow/predict_videos.py modified: deeplabcut/post_processing/analyze_skeleton.py modified: deeplabcut/post_processing/filtering.py modified: deeplabcut/refine_training_dataset/outlier_frames.py modified: deeplabcut/utils/make_labeled_video.py modified: deeplabcut/utils/plotting.py new file: docs/api/deeplabcut.analyze_videos.rst new file: docs/api/deeplabcut.analyzeskeleton.rst new file: docs/api/deeplabcut.create_labeled_video.rst new file: docs/api/deeplabcut.evaluate_network.rst new file: docs/api/deeplabcut.extract_outlier_frames.rst new file: docs/api/deeplabcut.filterpredictions.rst new file: docs/api/deeplabcut.merge_datasets.rst new file: docs/api/deeplabcut.plot_trajectories.rst modified: docs/standardDeepLabCut_UserGuide.md * DOC: Add missing documentation for function args * DOC: API docs for label_frames and refine_labels and minor corrections and improvements to existing api docs and install gui dependencies when building jupyter book documentation. this is necessary as the modules containing the above functions rely on GUI dependencies * DOC: API docs for deeplabcut.create_training_model_comparison this is the last function that needs to be documented in the user guide - now there are no more links to the wiki page in the user guide modified: deeplabcut/generate_training_dataset/trainingsetmanipulation.py new file: docs/api/deeplabcut.create_training_model_comparison.rst modified: docs/standardDeepLabCut_UserGuide.md * Update standardDeepLabCut_UserGuide.md - cleaned up the formatting to be consistent * Apply suggestions from code review Co-authored-by: Jessy Lauer <30733203+jeylau@users.noreply.github.com> Co-authored-by: Mackenzie Mathis <mathis@rowland.harvard.edu> Co-authored-by: Jessy Lauer <30733203+jeylau@users.noreply.github.com>
1 parent 7ee6ccd commit 4a1d500

24 files changed

Lines changed: 876 additions & 463 deletions

‎.github/workflows/publish-book.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ jobs:
1919
- name: Install dependencies
2020
run: |
2121
python -m pip install --upgrade pip
22-
python -m pip install -e .[docs]
22+
python -m pip install -e .[gui,docs]
2323
pip install jupyter-book
2424
2525
- name: Build the book

‎deeplabcut/generate_training_dataset/trainingsetmanipulation.py‎

Lines changed: 68 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1113,51 +1113,90 @@ def create_training_model_comparison(
11131113
userfeedback=False,
11141114
windows2linux=False,
11151115
):
1116-
"""
1117-
Creates a training dataset with different networks and augmentation types (dataset_loader) so that the shuffles
1118-
have same training and testing indices.
1116+
"""Creates a training dataset to compare networks and augmentation types.
11191117
1120-
Therefore, this function is useful for benchmarking the performance of different network and augmentation types on the same training/testdata.\n
1118+
The datasets are created such that the shuffles have same training and testing
1119+
indices. Therefore, this function is useful for benchmarking the performance of
1120+
different network and augmentation types on the same training/testdata.
11211121
1122-
Parameter
1122+
Parameters
11231123
----------
1124-
config : string
1125-
Full path of the config.yaml file as a string.
1124+
config: str
1125+
Full path of the config.yaml file.
11261126
1127-
trainindex: int, optional
1128-
Either (in case uniform = True) indexes which element of TrainingFraction in the config file should be used (note it is a list!).
1129-
Alternatively (uniform = False) indexes which folder is dropped, i.e. the first if trainindex=0, the second if trainindex =1, etc.
1127+
trainindex: int, optional, default=0
1128+
Either (in case uniform = True) indexes which element of TrainingFraction in
1129+
the config file should be used (note it is a list!).
1130+
Alternatively (uniform = False) indexes which folder is dropped, i.e. the first
1131+
if trainindex=0, the second if trainindex=1, etc.
11301132
1131-
num_shuffles : int, optional
1132-
Number of shuffles of training dataset to create, i.e. [1,2,3] for num_shuffles=3. Default is set to 1.
1133+
num_shuffles : int, optional, default=1
1134+
Number of shuffles of training dataset to create,
1135+
i.e. [1,2,3] for num_shuffles=3.
1136+
1137+
net_types: list[str], optional, default=["resnet_50"]
1138+
Currently supported networks are
1139+
1140+
* ``"resnet_50"``
1141+
* ``"resnet_101"``
1142+
* ``"resnet_152"``
1143+
* ``"mobilenet_v2_1.0"``
1144+
* ``"mobilenet_v2_0.75"``
1145+
* ``"mobilenet_v2_0.5"``
1146+
* ``"mobilenet_v2_0.35"``
1147+
* ``"efficientnet-b0"``
1148+
* ``"efficientnet-b1"``
1149+
* ``"efficientnet-b2"``
1150+
* ``"efficientnet-b3"``
1151+
* ``"efficientnet-b4"``
1152+
* ``"efficientnet-b5"``
1153+
* ``"efficientnet-b6"``
1154+
1155+
augmenter_types: list[str], optional, default=["imgaug"]
1156+
Currently supported augmenters are
1157+
1158+
* ``"default"``
1159+
* ``"imgaug"``
1160+
* ``"tensorpack"``
1161+
* ``"deterministic"``
11331162
1134-
net_types: list
1135-
Type of networks. Currently resnet_50, resnet_101, resnet_152, mobilenet_v2_1.0,mobilenet_v2_0.75, mobilenet_v2_0.5, mobilenet_v2_0.35,
1136-
efficientnet-b0, efficientnet-b1, efficientnet-b2, efficientnet-b3, efficientnet-b4,
1137-
efficientnet-b5, and efficientnet-b6 are supported.
1163+
userfeedback: bool, optional, default=False
1164+
If ``False``, then all requested train/test splits are created, no matter if
1165+
they already exist. If you want to assure that previous splits etc. are not
1166+
overwritten, then set this to True and you will be asked for each split.
11381167
1139-
augmenter_types: list
1140-
Type of augmenters. Currently "default", "imgaug", "tensorpack", and "deterministic" are supported.
1168+
windows2linux
11411169
1142-
userfeedback: bool, optional
1143-
If this is set to false, then all requested train/test splits are created (no matter if they already exist). If you
1144-
want to assure that previous splits etc. are not overwritten, then set this to True and you will be asked for each split.
1170+
..deprecated::
1171+
Has no effect since 2.2.0.4 and will be removed in 2.2.1.
11451172
11461173
Returns
1147-
----------
1174+
-------
11481175
shuffle_list: list
1149-
List of indices corresponding to the trainigsplits/models that were created.
1176+
List of indices corresponding to the trainingsplits/models that were created.
11501177
1151-
Example
1178+
Examples
11521179
--------
1153-
>>> shuffle_list = deeplabcut.create_training_model_comparison('/analysis/project/reaching-task/config.yaml',num_shuffles=1,net_types=['resnet_50','resnet_152'],augmenter_types=['tensorpack','deterministic'])
1180+
On Linux/MacOS
11541181
1155-
Windows:
1156-
>>> shuffle_list = deeplabcut.create_training_model_comparison('C:\\Users\\Ulf\\looming-task\\config.yaml',num_shuffles=1,net_types=['resnet_50','resnet_152'],augmenter_types=['tensorpack','deterministic'])
1182+
>>> shuffle_list = deeplabcut.create_training_model_comparison(
1183+
'/analysis/project/reaching-task/config.yaml',
1184+
num_shuffles=1,
1185+
net_types=['resnet_50','resnet_152'],
1186+
augmenter_types=['tensorpack','deterministic'],
1187+
)
11571188
1158-
See examples/testscript_openfielddata_augmentationcomparison.py for an example of how to use shuffle_list.
1189+
On Windows
11591190
1160-
--------
1191+
>>> shuffle_list = deeplabcut.create_training_model_comparison(
1192+
'C:\\Users\\Ulf\\looming-task\\config.yaml',
1193+
num_shuffles=1,
1194+
net_types=['resnet_50','resnet_152'],
1195+
augmenter_types=['tensorpack','deterministic'],
1196+
)
1197+
1198+
See ``examples/testscript_openfielddata_augmentationcomparison.py`` for an example
1199+
of how to use ``shuffle_list``.
11611200
"""
11621201
# read cfg file
11631202
cfg = auxiliaryfunctions.read_config(config)

‎deeplabcut/gui/label_frames.py‎

Lines changed: 44 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -29,43 +29,63 @@ def label_frames(
2929
sourceCam=None,
3030
jump_unlabeled=False,
3131
):
32-
"""
33-
Manually label/annotate the extracted frames. Update the list of body parts you want to localize in the config.yaml file first.
32+
"""Manually label/annotate the extracted frames.
33+
34+
Update the list of body parts you want to localize in the config.yaml file first.
3435
35-
Parameter
36+
Parameters
3637
----------
37-
config : string
38-
String containing the full path of the config file in the project.
38+
config: str
39+
Full path of the config.yaml file.
40+
41+
multiple_individualsGUI: bool, optional, default=False
42+
If ``True``, a user can label multiple individuals. Note for
43+
``"multianimalproject=True"`` this is automatically used.
3944
40-
multiple_individualsGUI: bool, optional
41-
If this is set to True, a user can label multiple individuals. Note for "multianimalproject=True" this is automatically used.
42-
The default is ``False``; if provided it must be either ``True`` or ``False``.
45+
imtypes: list[str], optional, default=["*.png"]
46+
Image types to look for in the folder. By default only png images are labeled.
4347
44-
imtypes: list of imagetypes to look for in folder to be labeled.
45-
By default only png images are considered.
48+
config3d: str or None, optional, default=None
49+
Full path of the config file in the 3D project. Include when epipolar lines
50+
would be helpful for labeling additional camera angles.
4651
47-
config3d: string, optional
48-
String containing the full path of the config file in the 3D project. Include when epipolar lines would be helpful for labeling additional camera angles.
52+
sourceCam: str or None, optional, default=None
53+
The camera name from which to pull labeling data to generate epipolar lines.
54+
This must match the pattern in ``'camera_names'`` in the 3D config file.
55+
If no value is entered, data will be pulled from either cam1 or cam2.
4956
50-
sourceCam: string, optional
51-
String containing the camera name from which to pull labeling data to generate epipolar lines. This must match the pattern in 'camera_names' in the 3D config file.
52-
If no value is entered, data will be pulled from either cam1 or cam2
57+
jump_unlabeled: bool, optional, default=False
58+
Aumatically jump to the next folder containing unlabeled images.
5359
54-
Example
60+
Returns
61+
-------
62+
None
63+
64+
Examples
5565
--------
56-
Standard use case:
66+
Standard use case
67+
5768
>>> deeplabcut.label_frames('/myawesomeproject/reaching4thestars/config.yaml')
5869
59-
To label multiple individuals (without having a multiple individuals project); otherwise this GUI is loaded automatically
60-
>>> deeplabcut.label_frames('/analysis/project/reaching-task/config.yaml',multiple_individualsGUI=True)
70+
To label multiple individuals (without having a multiple individuals project);
71+
otherwise this GUI is loaded automatically
6172
62-
To label other image types
63-
>>> label_frames(config,multiple=False,imtypes=['*.jpg','*.jpeg'])
73+
>>> deeplabcut.label_frames(
74+
'/analysis/project/reaching-task/config.yaml',
75+
multiple_individualsGUI=True,
76+
)
6477
65-
To label with epipolar lines projected from labels in another camera angle #+++
66-
>>> label_frames(config, config3d='/analysis/project/reaching-task/reaching-task-3d/config.yaml', sourceCam='cam1')
67-
--------
78+
To label non-default image types
79+
80+
>>> label_frames(config, multiple=False, imtypes=['*.jpg','*.jpeg'])
81+
82+
To label with epipolar lines projected from labels in another camera angle.
6883
84+
>>> label_frames(
85+
config,
86+
config3d='/analysis/project/reaching-task/reaching-task-3d/config.yaml',
87+
sourceCam='cam1',
88+
)
6989
"""
7090
startpath = os.getcwd()
7191
wd = Path(config).resolve().parents[0]

‎deeplabcut/gui/refine_labels.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,27 +22,27 @@
2222

2323

2424
def refine_labels(config, multianimal=False, jump_unlabeled=False):
25-
"""
26-
Refines the labels of the outlier frames extracted from the analyzed videos.\n Helps in augmenting the training dataset.
27-
Use the function ``analyze_video`` to analyze a video and extracts the outlier frames using the function
28-
``extract_outlier_frames`` before refining the labels.
25+
"""Refines the labels of the outlier frames extracted from the analyzed videos.
26+
27+
Helps in augmenting the training dataset. Use ``deeplabcut.analyze_videos`` to
28+
analyze a video and extracts the outlier frames using
29+
``deeplabcut.extract_outlier_frames`` before refining the labels.
2930
3031
Parameters
3132
----------
32-
config : string
33-
Full path of the config.yaml file as a string.
34-
35-
Screens : int value of the number of Screens in landscape mode, i.e. if you have 2 screens, enter 2. Default is 1.
33+
config: str
34+
Full path of the config.yaml file.
3635
37-
scale_h & scale_w : you can modify how much of the screen the GUI should occupy. The default is .9 and .8, respectively.
36+
multianimal, bool, optional, default=False
37+
If ``True``, a user can label multiple individuals. Note for
38+
``"multianimalproject=True"`` this is automatically used.
3839
39-
img_scale : if you want to make the plot of the frame larger, consider changing this to .008 or more. Be careful though, too large and you will not see the buttons fully!
40+
jump_unlabeled: bool, optional, default=False
41+
Aumatically jump to the next folder containing unlabeled images.
4042
4143
Examples
4244
--------
43-
>>> deeplabcut.refine_labels('/analysis/project/reaching-task/config.yaml', Screens=2, imag_scale=.0075)
44-
--------
45-
45+
>>> deeplabcut.refine_labels('/analysis/project/reaching-task/config.yaml')
4646
"""
4747

4848
startpath = os.getcwd()

‎deeplabcut/pose_estimation_tensorflow/core/evaluate.py‎

Lines changed: 62 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -502,58 +502,87 @@ def evaluate_network(
502502
rescale=False,
503503
modelprefix="",
504504
):
505-
"""
505+
"""Evaluates the network.
506+
507+
Evaluates the network based on the saved models at different stages of the training
508+
network. The evaluation results are stored in the .h5 and .csv file under the
509+
subdirectory 'evaluation_results'. Change the snapshotindex parameter in the config
510+
file to 'all' in order to evaluate all the saved models.
506511
507-
Evaluates the network based on the saved models at different stages of the training network.\n
508-
The evaluation results are stored in the .h5 and .csv file under the subdirectory 'evaluation_results'.
509-
Change the snapshotindex parameter in the config file to 'all' in order to evaluate all the saved models.
510512
Parameters
511513
----------
512514
config : string
513-
Full path of the config.yaml file as a string.
515+
Full path of the config.yaml file.
514516
515-
Shuffles: list, optional
516-
List of integers specifying the shuffle indices of the training dataset. The default is [1]
517+
Shuffles: list, optional, default=[1]
518+
List of integers specifying the shuffle indices of the training dataset.
517519
518-
trainingsetindex: int, optional
519-
Integer specifying which TrainingsetFraction to use. By default the first (note that TrainingFraction is a list in config.yaml). This
520-
variable can also be set to "all".
520+
trainingsetindex: int or str, optional, default=0
521+
Integer specifying which "TrainingsetFraction" to use.
522+
Note that "TrainingFraction" is a list in config.yaml. This variable can also
523+
be set to "all".
521524
522-
plotting: bool or str, optional
525+
plotting: bool or str, optional, default=False
523526
Plots the predictions on the train and test images.
524-
The default is ``False``; if provided it must be either ``True``, ``False``, "bodypart", or "individual".
525-
Setting to ``True`` defaults as "bodypart" for multi-animal projects.
527+
If provided it must be either ``True``, ``False``, ``"bodypart"``, or
528+
``"individual"``. Setting to ``True`` defaults as ``"bodypart"`` for
529+
multi-animal projects.
526530
527-
show_errors: bool, optional
528-
Display train and test errors. The default is `True``
531+
show_errors: bool, optional, default=True
532+
Display train and test errors.
529533
530-
comparisonbodyparts: list of bodyparts, Default is "all".
531-
The average error will be computed for those body parts only (Has to be a subset of the body parts).
534+
comparisonbodyparts: str or list, optional, default="all"
535+
The average error will be computed for those body parts only.
536+
The provided list has to be a subset of the defined body parts.
532537
533-
gputouse: int, optional. Natural number indicating the number of your GPU (see number in nvidia-smi). If you do not have a GPU put None.
538+
gputouse: int or None, optional, default=None
539+
Indicates the GPU to use (see number in ``nvidia-smi``). If you do not have a
540+
GPU put `None``.
534541
See: https://nvidia.custhelp.com/app/answers/detail/a_id/3751/~/useful-nvidia-smi-queries
535542
536-
rescale: bool, default False
537-
Evaluate the model at the 'global_scale' variable (as set in the test/pose_config.yaml file for a particular project). I.e. every
538-
image will be resized according to that scale and prediction will be compared to the resized ground truth. The error will be reported
539-
in pixels at rescaled to the *original* size. I.e. For a [200,200] pixel image evaluated at global_scale=.5, the predictions are calculated
540-
on [100,100] pixel images, compared to 1/2*ground truth and this error is then multiplied by 2!. The evaluation images are also shown for the
541-
original size!
543+
rescale: bool, optional, default=False
544+
Evaluate the model at the ``'global_scale'`` variable (as set in the
545+
``pose_config.yaml`` file for a particular project). I.e. every image will be
546+
resized according to that scale and prediction will be compared to the resized
547+
ground truth. The error will be reported in pixels at rescaled to the
548+
*original* size. I.e. For a [200,200] pixel image evaluated at
549+
``global_scale=.5``, the predictions are calculated on [100,100] pixel images,
550+
compared to 1/2*ground truth and this error is then multiplied by 2!.
551+
The evaluation images are also shown for the original size!
552+
553+
modelprefix: str, optional, default=""
554+
Directory containing the deeplabcut models to use when evaluating the network.
555+
By default, the models are assumed to exist in the project folder.
556+
557+
Returns
558+
-------
559+
None
542560
543561
Examples
544562
--------
545-
If you do not want to plot, just evaluate shuffle 1.
546-
>>> deeplabcut.evaluate_network('/analysis/project/reaching-task/config.yaml', Shuffles=[1])
547-
--------
548-
If you want to plot and evaluate shuffle 0 and 1.
549-
>>> deeplabcut.evaluate_network('/analysis/project/reaching-task/config.yaml',Shuffles=[0, 1],plotting = True)
563+
If you do not want to plot and evaluate with shuffle set to 1.
550564
551-
--------
552-
If you want to plot assemblies for a maDLC project:
553-
>>> deeplabcut.evaluate_network('/analysis/project/reaching-task/config.yaml',Shuffles=[1],plotting = "individual")
565+
>>> deeplabcut.evaluate_network(
566+
'/analysis/project/reaching-task/config.yaml', Shuffles=[1],
567+
)
568+
569+
If you want to plot and evaluate with shuffle set to 0 and 1.
570+
571+
>>> deeplabcut.evaluate_network(
572+
'/analysis/project/reaching-task/config.yaml',
573+
Shuffles=[0, 1],
574+
plotting=True,
575+
)
576+
577+
If you want to plot assemblies for a maDLC project
554578
555-
Note: this defaults to standard plotting for single-animal projects.
579+
>>> deeplabcut.evaluate_network(
580+
'/analysis/project/reaching-task/config.yaml',
581+
Shuffles=[1],
582+
plotting="individual",
583+
)
556584
585+
Note: This defaults to standard plotting for single-animal projects.
557586
"""
558587
if plotting not in (True, False, "bodypart", "individual"):
559588
raise ValueError(f"Unknown value for `plotting`={plotting}")

0 commit comments

Comments
 (0)