Update function signatures by deruyter92 · Pull Request #3458 · DeepLabCut/DeepLabCut

deruyter92 · 2026-08-21T08:40:32Z

Motivation
The DeepLabCut API was recently streamlined in #3332 and #3198, which introduced consistent paramteter names (e.g. snake case, lowercase internally consistent parameter names). However several function signatures currently still remain to be normalized.

This PR aims to further streamline all function signatures of all API to normalize

config_path: str, config: str --> config: ProjectConfig | str | Path | dict
Shuffles --> shuffles
TrainFraction --> train_fraction
etcetera.

Note

This PR is a placeholder that currently has draft status. I am still considering a smaller scope and the specific renames remain to be discussed and tested properly.

Apply a new parameter-aliasing deprecation round (since 3.0.2) to the public API, GUI, and internals: add @renamed_parameter markers and update signatures, docstrings, and call sites for parameters that still used legacy camelCase or concatenated names (e.g. outlieralgorithm -> outlier_algorithm, filtertype -> filter_type, trainFraction -> train_fraction). Update tests for the new names.

…traction`

…ections`

…ideos_converth5_to_nwb Note that the default None is also expanded only ".mp4" types to all supported videos. This is a minor behavior change that alligns the current function with the rest of API.

…jectConfig

…path

…ets`

…videotype, …)

…analyze/tracklets)

Copilot

🔵 Needs a closer look

Cross-backend routing regressions, unsupported 3D config contracts, and failing legacy call sites remain unresolved.

Pull request overview

Standardizes DeepLabCut API parameters with snake_case names, deprecated aliases, and broader ProjectConfig support.

Changes:

Renames parameters while preserving legacy aliases.
Migrates project APIs toward typed configuration objects.
Updates internal callers, GUI code, examples, and routing tests.

File summaries

File	Description
tests/api/test_pose_estimation.py	Updates routing expectations.
tests/api/test_create_project.py	Updates project API expectations.
examples/testscript_transreid.py	Uses canonical body-part parameter.
examples/testscript_tensorflow_single_animal.py	Uses canonical cropping parameter.
examples/testscript_tensorflow_multi_animal.py	Uses canonical body-part parameter.
deeplabcut/utils/plotting.py	Normalizes plotting parameters/config handling.
deeplabcut/utils/make_labeled_video.py	Normalizes video-creation API.
deeplabcut/utils/conversioncode.py	Normalizes conversion APIs.
deeplabcut/utils/auxfun_multianimal.py	Adds typed config support.
deeplabcut/tensorflow_compat/pose_estimation.py	Adds TensorFlow aliases.
deeplabcut/tensorflow_compat/create_project.py	Normalizes project parameters.
deeplabcut/refine_training_dataset/stitch.py	Normalizes stitching config input.
deeplabcut/refine_training_dataset/outlier_frames.py	Normalizes outlier APIs.
deeplabcut/post_processing/filtering.py	Normalizes filtering parameters.
deeplabcut/post_processing/analyze_skeleton.py	Adds typed config support.
deeplabcut/pose_estimation_pytorch/data/dlcloader.py	Validates object-based configs.
deeplabcut/pose_estimation_pytorch/apis/videos.py	Broadens config input and batch aliasing.
deeplabcut/pose_estimation_pytorch/apis/utils.py	Broadens config input.
deeplabcut/pose_estimation_pytorch/apis/tracklets.py	Normalizes inference config naming.
deeplabcut/pose_estimation_pytorch/apis/tracking_dataset.py	Adds batch-size alias.
deeplabcut/pose_estimation_pytorch/apis/export.py	Renames snapshot parameter.
deeplabcut/pose_estimation_pytorch/apis/evaluation.py	Normalizes evaluation API.
deeplabcut/pose_estimation_pytorch/apis/analyze_images.py	Adds typed config support.
deeplabcut/pose_estimation_3d/triangulation.py	Normalizes 3D API parameters.
deeplabcut/pose_estimation_3d/plotting3D.py	Normalizes 3D plotting parameters.
deeplabcut/pose_estimation_3d/camera_calibration.py	Broadens config annotations.
deeplabcut/gui/tabs/refine_tracklets.py	Updates filtering and merging calls.
deeplabcut/gui/tabs/label_frames.py	Updates label-check call.
deeplabcut/gui/tabs/extract_outlier_frames.py	Updates outlier API calls.
deeplabcut/gui/tabs/extract_frames.py	Uses typed config and canonical names.
deeplabcut/gui/tabs/evaluate_network.py	Updates evaluation calls.
deeplabcut/gui/tabs/create_videos.py	Updates video-creation calls.
deeplabcut/gui/tabs/create_training_dataset.py	Updates shuffle naming.
deeplabcut/gui/tabs/analyze_videos.py	Updates post-processing calls.
deeplabcut/generate_training_dataset/trainingsetmanipulation.py	Normalizes dataset APIs.
deeplabcut/generate_training_dataset/multiple_individuals_trainingsetmanipulation.py	Normalizes multi-animal dataset APIs.
deeplabcut/generate_training_dataset/frame_extraction.py	Adds typed config handling.
deeplabcut/create_project/modelzoo.py	Normalizes pretrained-project parameters.
deeplabcut/create_project/demo_data.py	Renames training-set option.
deeplabcut/create_project/add.py	Adds typed config handling.
deeplabcut/core/deprecation.py	Defines the new deprecation round.
deeplabcut/api/refine_training.py	Normalizes refinement facade.
deeplabcut/api/post_processing.py	Normalizes post-processing facade.
deeplabcut/api/pose_estimation.py	Normalizes pose-estimation facade.
deeplabcut/api/create_project.py	Normalizes project-creation facade.

Review details

Suppressed comments (2)

deeplabcut/pose_estimation_3d/triangulation.py:278

This second analysis branch has the same TF regression: device is forwarded to tensorflow_compat.analyze_videos, whose signature only accepts gputouse. Since the keyword is supplied even for the default None, TensorFlow-backed triangulation fails on every execution of this branch; translate it in the shared router or conditionally pass the backend-specific keyword.

                        device=device,

deeplabcut/api/pose_estimation.py:939

The canonical name does not work on the TensorFlow fallback: the outer router forwards snapshot_index unchanged, while tensorflow_compat.export_model still requires snapshotindex. Thus deeplabcut.export_model(..., snapshot_index=...) fails specifically for TF projects even though the legacy spelling succeeds. Update the TF compatibility signature with its own deprecated alias or add backend-aware translation.

    snapshot_index: int | None = None,

Files reviewed: 45/45 changed files
Comments generated: 10
Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

    trainingsetindex: int = 0,
    comparison_bodyparts: str | list[str] = "all",
-    snapshotindex: str | int | None = None,
+    snapshot_index: str | int | None = None,


    destfolder: str | None = None,
    ignore_bodyparts: list[str] | None = None,
-    inferencecfg: dict | None = None,
+    inference_cfg: dict | None = None,



 def calibrate_cameras(
-    config: str | Path,
+    config: ProjectConfig | dict | Path | str,




-def check_undistortion(config: str | Path, cbrow=8, cbcol=6, plot=True):
+def check_undistortion(config: ProjectConfig | dict | Path | str, cbrow=8, cbcol=6, plot=True):


+@renamed_parameter(old="videotype", new="video_extensions", deprecation_round=DeprecationRound.PARAMETER_ALIASING_302)
 def create_labeled_video_3d(
-    config: str | Path,
+    config: ProjectConfig | dict | Path | str,


+@renamed_parameter(old="gputouse", new="device", deprecation_round=DeprecationRound.PARAMETER_ALIASING_302)
 def triangulate(
-    config: str | Path,
+    config: ProjectConfig | dict | Path | str,


-    filterpredictions=True,
-    filtertype="median",
-    gputouse=None,
+    video_extensions: str | Sequence[str] | None = "",


                            shuffle=shuffle,
                            trainingsetindex=trainingsetindex,
-                            gputouse=gputouse,
+                            device=device,


    shuffle: int = 1,
    trainingsetindex: int = 0,
-    snapshotindex: int | None = None,
+    snapshot_index: int | None = None,




-def compute_deviations(Dataframe, dataname, p_bound, alpha, ARdegree, MAdegree, storeoutput=None):
+def compute_deviations(Dataframe, dataname, p_bound, alpha, ar_degree, ma_degree, storeoutput=None):


deruyter92 changed the base branch from jaap/prepare_tf_deprecation to jaap/lazy-loading August 21, 2026 08:58

C-Achard assigned deruyter92 Aug 21, 2026

C-Achard added enhancement New feature or request backwards compatibility issues concerning prior to current versions labels Aug 21, 2026

deruyter92 added this to the Refresh core API and interface milestone Aug 25, 2026

deruyter92 force-pushed the jaap/update-function-signatures branch from ced1b85 to 16312b9 Compare August 26, 2026 11:34

deruyter92 added the 3.1 label Aug 28, 2026

deruyter92 force-pushed the jaap/lazy-loading branch from 229cfd0 to 1e0896b Compare September 3, 2026 08:55

deruyter92 force-pushed the jaap/update-function-signatures branch from 16312b9 to cd3c546 Compare September 3, 2026 08:58

deruyter92 force-pushed the jaap/lazy-loading branch from c052876 to 62f5b33 Compare September 4, 2026 12:14

deruyter92 and others added 20 commits September 4, 2026 14:15

consistently use ProjectConfig in public API

b0770fe

replace project path with ProjectConfig in add_videos and `frame_ex…

1c20da5

…traction`

replace project path with ProjectConfig in plot_trajectories

c7b4820

replace project path with ProjectConfig in return_train_network_path

9c2f356

replace project path with ProjectConfig in create_labeled_video

8f5e89e

replace project path with ProjectConfig in convert2_maDLC

d782a56

replace project path with ProjectConfig in `create_video_with_all_det…

3cc7725

…ections`

replace project path with ProjectConfig in convertcsv2h5

ff7b9ac

rename videotype to video_extensions for consistency in analyze_v…

eeeb913

…ideos_converth5_to_nwb Note that the default None is also expanded only ".mp4" types to all supported videos. This is a minor behavior change that alligns the current function with the rest of API.

update load_demo_data signature: require config path not dict / Pro…

547b84a

…jectConfig

validate project_path in DLCLoader when config is not a filesystem …

94e6c03

…path

replace project path with ProjectConfig in evaluate_network

7106d9c

replace project path with ProjectConfig in analyze_images

6ff7591

replace project path with ProjectConfig in `convert_detections2trackl…

d1030c0

…ets`

replace project path with ProjectConfig in analyze_videos

84d5d7d

replace project path with ProjectConfig in analyzeskeleton

62a765d

replace project path with ProjectConfig in filterpredictions

2e21c13

replace project path with ProjectConfig in outlier_frames.py

adc1ee5

replace project path with ProjectConfig in stitch_tracklets

558e2e5

deruyter92 force-pushed the jaap/update-function-signatures branch from 4ea3a89 to 558e2e5 Compare September 4, 2026 12:16

deruyter92 added 2 commits September 4, 2026 14:37

rename public params to snake_case (Frames2plot, displayedbodyparts, …

114facd

…videotype, …)

mirror API parameter aliases onto impls (filter, outliers, evaluate, …

98393c3

…analyze/tracklets)

deruyter92 requested a balanced review from Copilot September 7, 2026 07:49

Copilot started reviewing on behalf of deruyter92 September 7, 2026 07:49 View session

Copilot AI reviewed Sep 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

Update function signatures - #3458

Update function signatures#3458
deruyter92 wants to merge 22 commits into
jaap/lazy-loadingfrom
jaap/update-function-signatures

deruyter92 commented Aug 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants



		def check_undistortion(config: str \| Path, cbrow=8, cbcol=6, plot=True):
		def check_undistortion(config: ProjectConfig \| dict \| Path \| str, cbrow=8, cbcol=6, plot=True):



		def compute_deviations(Dataframe, dataname, p_bound, alpha, ARdegree, MAdegree, storeoutput=None):
		def compute_deviations(Dataframe, dataname, p_bound, alpha, ar_degree, ma_degree, storeoutput=None):

Uh oh!

Conversation

deruyter92 commented Aug 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Suppressed comments (2)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants