jabs-behavior-classifier 0.36.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. jabs_behavior_classifier-0.36.0/PKG-INFO +325 -0
  2. jabs_behavior_classifier-0.36.0/README.md +296 -0
  3. jabs_behavior_classifier-0.36.0/pyproject.toml +75 -0
  4. jabs_behavior_classifier-0.36.0/src/jabs/__init__.py +1 -0
  5. jabs_behavior_classifier-0.36.0/src/jabs/__main__.py +4 -0
  6. jabs_behavior_classifier-0.36.0/src/jabs/behavior_search/__init__.py +11 -0
  7. jabs_behavior_classifier-0.36.0/src/jabs/behavior_search/behavior_search_util.py +301 -0
  8. jabs_behavior_classifier-0.36.0/src/jabs/classifier/__init__.py +16 -0
  9. jabs_behavior_classifier-0.36.0/src/jabs/classifier/classifier.py +676 -0
  10. jabs_behavior_classifier-0.36.0/src/jabs/constants.py +10 -0
  11. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/__init__.py +20 -0
  12. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/angle_index.py +99 -0
  13. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/__init__.py +23 -0
  14. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/angles.py +65 -0
  15. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/angular_velocity.py +59 -0
  16. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/base_group.py +43 -0
  17. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/centroid_velocity.py +91 -0
  18. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/pairwise_distances.py +44 -0
  19. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/point_speeds.py +41 -0
  20. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/point_velocities.py +50 -0
  21. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/feature_base_class.py +361 -0
  22. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/feature_group_base_class.py +112 -0
  23. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/features.py +765 -0
  24. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/__init__.py +3 -0
  25. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/corner.py +314 -0
  26. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/food_hopper.py +68 -0
  27. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/landmark_group.py +246 -0
  28. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/lixit.py +321 -0
  29. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/__init__.py +20 -0
  30. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/hu_moments.py +48 -0
  31. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/moment_cache.py +156 -0
  32. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/moments.py +63 -0
  33. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/segment_group.py +45 -0
  34. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/shape_descriptors.py +145 -0
  35. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/__init__.py +21 -0
  36. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/closest_distances.py +51 -0
  37. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/closest_fov_angles.py +57 -0
  38. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/closest_fov_distances.py +47 -0
  39. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/pairwise_social_distances.py +88 -0
  40. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/social_distance.py +172 -0
  41. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/social_group.py +72 -0
  42. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/window_operations/__init__.py +6 -0
  43. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/window_operations/signal_stats.py +155 -0
  44. jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/window_operations/window_stats.py +198 -0
  45. jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/__init__.py +110 -0
  46. jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est.py +379 -0
  47. jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v2.py +146 -0
  48. jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v3.py +335 -0
  49. jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v4.py +319 -0
  50. jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v5.py +117 -0
  51. jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v6.py +143 -0
  52. jabs_behavior_classifier-0.36.0/src/jabs/project/__init__.py +19 -0
  53. jabs_behavior_classifier-0.36.0/src/jabs/project/export_training.py +105 -0
  54. jabs_behavior_classifier-0.36.0/src/jabs/project/feature_manager.py +159 -0
  55. jabs_behavior_classifier-0.36.0/src/jabs/project/prediction_manager.py +172 -0
  56. jabs_behavior_classifier-0.36.0/src/jabs/project/project.py +648 -0
  57. jabs_behavior_classifier-0.36.0/src/jabs/project/project_merge.py +114 -0
  58. jabs_behavior_classifier-0.36.0/src/jabs/project/project_paths.py +84 -0
  59. jabs_behavior_classifier-0.36.0/src/jabs/project/project_pruning.py +56 -0
  60. jabs_behavior_classifier-0.36.0/src/jabs/project/project_utils.py +25 -0
  61. jabs_behavior_classifier-0.36.0/src/jabs/project/read_training.py +123 -0
  62. jabs_behavior_classifier-0.36.0/src/jabs/project/session_tracker.py +340 -0
  63. jabs_behavior_classifier-0.36.0/src/jabs/project/settings_manager.py +182 -0
  64. jabs_behavior_classifier-0.36.0/src/jabs/project/timeline_annotations.py +261 -0
  65. jabs_behavior_classifier-0.36.0/src/jabs/project/track_labels.py +263 -0
  66. jabs_behavior_classifier-0.36.0/src/jabs/project/video_labels.py +244 -0
  67. jabs_behavior_classifier-0.36.0/src/jabs/project/video_manager.py +214 -0
  68. jabs_behavior_classifier-0.36.0/src/jabs/resources/__init__.py +20 -0
  69. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/features/features.md +196 -0
  70. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/StackedImgs.svg +35243 -0
  71. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/centroid-identity-overlay.png +0 -0
  72. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/classifier_controls.png +0 -0
  73. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/floating-identity-overlay.png +0 -0
  74. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/identity_gaps.png +0 -0
  75. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/identity_gaps_with_label.png +0 -0
  76. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/keypoint_legend.png +0 -0
  77. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/label_viz.png +0 -0
  78. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/main_window.png +0 -0
  79. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/minimalist-identity-overlay.png +0 -0
  80. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/pose_overlay.png +0 -0
  81. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/selecting_frames.png +0 -0
  82. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/stacked_timeline.png +0 -0
  83. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/timeline_menu.png +0 -0
  84. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/track_overlay.png +0 -0
  85. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/video-control-overlay.png +0 -0
  86. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/video-control-overlay.svg +178 -0
  87. jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/user_guide.md +841 -0
  88. jabs_behavior_classifier-0.36.0/src/jabs/resources/icon.png +0 -0
  89. jabs_behavior_classifier-0.36.0/src/jabs/schema/__init__.py +1 -0
  90. jabs_behavior_classifier-0.36.0/src/jabs/schema/metadata.py +115 -0
  91. jabs_behavior_classifier-0.36.0/src/jabs/scripts/__init__.py +3 -0
  92. jabs_behavior_classifier-0.36.0/src/jabs/scripts/classify.py +363 -0
  93. jabs_behavior_classifier-0.36.0/src/jabs/scripts/cli.py +109 -0
  94. jabs_behavior_classifier-0.36.0/src/jabs/scripts/convert_parquet.py +331 -0
  95. jabs_behavior_classifier-0.36.0/src/jabs/scripts/generate_features.py +106 -0
  96. jabs_behavior_classifier-0.36.0/src/jabs/scripts/gui_entrypoint.py +46 -0
  97. jabs_behavior_classifier-0.36.0/src/jabs/scripts/initialize_project.py +315 -0
  98. jabs_behavior_classifier-0.36.0/src/jabs/scripts/merge_projects.py +87 -0
  99. jabs_behavior_classifier-0.36.0/src/jabs/scripts/stats.py +136 -0
  100. jabs_behavior_classifier-0.36.0/src/jabs/types/__init__.py +4 -0
  101. jabs_behavior_classifier-0.36.0/src/jabs/types/classifier_types.py +9 -0
  102. jabs_behavior_classifier-0.36.0/src/jabs/types/units.py +8 -0
  103. jabs_behavior_classifier-0.36.0/src/jabs/ui/__init__.py +5 -0
  104. jabs_behavior_classifier-0.36.0/src/jabs/ui/about_dialog.py +42 -0
  105. jabs_behavior_classifier-0.36.0/src/jabs/ui/annotation_edit_dialog.py +377 -0
  106. jabs_behavior_classifier-0.36.0/src/jabs/ui/archive_behavior_dialog.py +70 -0
  107. jabs_behavior_classifier-0.36.0/src/jabs/ui/behavior_search_dialog.py +472 -0
  108. jabs_behavior_classifier-0.36.0/src/jabs/ui/central_widget.py +1301 -0
  109. jabs_behavior_classifier-0.36.0/src/jabs/ui/classification_thread.py +176 -0
  110. jabs_behavior_classifier-0.36.0/src/jabs/ui/colors.py +36 -0
  111. jabs_behavior_classifier-0.36.0/src/jabs/ui/exceptions.py +6 -0
  112. jabs_behavior_classifier-0.36.0/src/jabs/ui/k_fold_slider_widget.py +47 -0
  113. jabs_behavior_classifier-0.36.0/src/jabs/ui/label_count_widget.py +159 -0
  114. jabs_behavior_classifier-0.36.0/src/jabs/ui/license_dialog.py +44 -0
  115. jabs_behavior_classifier-0.36.0/src/jabs/ui/main_control_widget.py +644 -0
  116. jabs_behavior_classifier-0.36.0/src/jabs/ui/main_window.py +912 -0
  117. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/__init__.py +7 -0
  118. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/frame_with_overlays.py +513 -0
  119. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/__init__.py +1 -0
  120. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/annotation_info_dialog.py +154 -0
  121. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/annotation_overlay.py +233 -0
  122. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/control_overlay.py +626 -0
  123. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/floating_id_overlay.py +261 -0
  124. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/label_overlay.py +95 -0
  125. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/overlay.py +90 -0
  126. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/pose_overlay.py +125 -0
  127. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/player_thread.py +286 -0
  128. jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/player_widget.py +608 -0
  129. jabs_behavior_classifier-0.36.0/src/jabs/ui/progress_dialog.py +139 -0
  130. jabs_behavior_classifier-0.36.0/src/jabs/ui/project_loader_thread.py +38 -0
  131. jabs_behavior_classifier-0.36.0/src/jabs/ui/project_pruning_dialog.py +197 -0
  132. jabs_behavior_classifier-0.36.0/src/jabs/ui/search_bar_widget.py +426 -0
  133. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/__init__.py +12 -0
  134. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/frame_labels_widget.py +113 -0
  135. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/__init__.py +18 -0
  136. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/label_overview_util.py +89 -0
  137. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/label_overview_widget.py +190 -0
  138. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/manual_label_widget.py +388 -0
  139. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/predicted_label_widget.py +149 -0
  140. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/prediction_overview_widget.py +41 -0
  141. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/timeline_label_widget.py +259 -0
  142. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/timeline_prediction_widget.py +65 -0
  143. jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/stacked_timeline_widget.py +475 -0
  144. jabs_behavior_classifier-0.36.0/src/jabs/ui/training_thread.py +255 -0
  145. jabs_behavior_classifier-0.36.0/src/jabs/ui/user_guide_dialog.py +81 -0
  146. jabs_behavior_classifier-0.36.0/src/jabs/ui/util.py +38 -0
  147. jabs_behavior_classifier-0.36.0/src/jabs/ui/video_list_widget.py +218 -0
  148. jabs_behavior_classifier-0.36.0/src/jabs/utils/__init__.py +15 -0
  149. jabs_behavior_classifier-0.36.0/src/jabs/utils/pose_util.py +36 -0
  150. jabs_behavior_classifier-0.36.0/src/jabs/utils/sampleposeintervals.py +269 -0
  151. jabs_behavior_classifier-0.36.0/src/jabs/utils/utilities.py +135 -0
  152. jabs_behavior_classifier-0.36.0/src/jabs/version/__init__.py +24 -0
  153. jabs_behavior_classifier-0.36.0/src/jabs/video_reader/__init__.py +21 -0
  154. jabs_behavior_classifier-0.36.0/src/jabs/video_reader/frame_annotation.py +274 -0
  155. jabs_behavior_classifier-0.36.0/src/jabs/video_reader/utilities.py +31 -0
  156. jabs_behavior_classifier-0.36.0/src/jabs/video_reader/video_reader.py +150 -0
@@ -0,0 +1,325 @@
1
+ Metadata-Version: 2.3
2
+ Name: jabs-behavior-classifier
3
+ Version: 0.36.0
4
+ Summary:
5
+ Author: Glen Beane, Brian Geuther, Keith Sheppard
6
+ License: Proprietary
7
+ Requires-Dist: h5py>=3.10.0,<4.0.0
8
+ Requires-Dist: markdown2>=2.5.1,<3.0.0
9
+ Requires-Dist: numpy>=2.0.0,<3.0.0
10
+ Requires-Dist: opencv-python-headless>=4.8.1.78,<5.0.0
11
+ Requires-Dist: pandas>=2.2.2,<3.0.0
12
+ Requires-Dist: pyside6>=6.8.0,!=6.9.0
13
+ Requires-Dist: scikit-learn>=1.5.0,<2.0.0
14
+ Requires-Dist: shapely>=2.0.1,<3.0.0
15
+ Requires-Dist: tabulate>=0.9.0,<1.0.0
16
+ Requires-Dist: toml>=0.10.2,<0.11.0
17
+ Requires-Dist: xgboost>=2.0.0,<3.0.0
18
+ Requires-Dist: pyarrow>=20.0.0,<21.0.0
19
+ Requires-Dist: rich>=14.0.0,<15.0.0
20
+ Requires-Dist: rich-argparse>=1.7.1,<2.0.0
21
+ Requires-Dist: intervaltree>=3.1.0,<4.0.0
22
+ Requires-Dist: qt-material-icons>=0.2.0,<0.3.0
23
+ Requires-Dist: jsonschema>=4.25.1,<5.0.0
24
+ Requires-Dist: click>=8.2.1
25
+ Requires-Python: >=3.10, <3.14
26
+ Project-URL: Issues, https://github.com/KumarLabJax/JABS-behavior-classifier/issues
27
+ Project-URL: Repository, https://github.com/KumarLabJax/JABS-behavior-classifier
28
+ Description-Content-Type: text/markdown
29
+
30
+ # JAX Animal Behavior System (JABS)
31
+
32
+ ![JABS Screen Shot](img/jabs_screenshot.png)
33
+
34
+ ## ReadTheDocs Tutorial and User Guide
35
+
36
+ https://jabs-tutorial.readthedocs.io/en/latest/index.html
37
+
38
+ [User Guide (Markdown)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/main/src/jabs/resources/docs/user_guide/user_guide.md)
39
+
40
+ ## Copyright
41
+
42
+ Copyright 2023 The Jackson Laboratory -- All rights reserved.
43
+
44
+ ## Contact
45
+
46
+ email us at jabs@jax.org
47
+
48
+ ## License
49
+
50
+ JABS is licensed under a non-commercial use license, see LICENSE for more information. Contact us for information about
51
+ licensing for commercial use.
52
+
53
+ ## Pose Files
54
+
55
+ JABS requires pose files generated from the Kumar Lab's mouse pose estimation neural networks. Single mouse pose files
56
+ are generated from [this repository](https://github.com/KumarLabJax/deep-hrnet-mouse). Multi-mouse is still under development. Contact us for more information.
57
+
58
+ ## Requirements
59
+
60
+ JABS was initially developed and tested on Python 3.10. See the `pyproject.toml` for a list of required Python
61
+ packages. These packages are available from the Python Package Index (PyPI).
62
+
63
+ Currently, JABS supports Python 3.10 through 3.13.
64
+
65
+ ## Python Environment Setup
66
+
67
+ We recommend creating a Python Virtualenv for JABS:
68
+
69
+ ```
70
+ python -m venv jabs.venv
71
+
72
+ # Linux and MacOS
73
+ source jabs.venv/bin/activate
74
+
75
+ # Windows
76
+ jabs.venv\Scripts\activate.bat
77
+ ```
78
+
79
+ ### JABS Installation
80
+
81
+ Developers should follow the Developer Setup section below. This section describes how to install JABS into a Python
82
+ environment for a non-developer user.
83
+
84
+ #### PyPI
85
+
86
+ JABS is not available on PyPI at this time, but we hope to begin publishing it there soon.
87
+
88
+ #### Pip install from Github
89
+
90
+ With the jabs.venv virtualenv activated, run the following command to install JABS from our git repository. This will
91
+ install the latest commit from the main branch:
92
+ `pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git`
93
+
94
+ you can also specify a branch or tag:
95
+
96
+ `pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git@branch-name`
97
+
98
+ or a specific commit:
99
+
100
+ `pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git@commit-hash`
101
+
102
+ #### Pip install from local source
103
+
104
+ If you've cloned the JABS repository, you can install by running the following command in the project root directory:
105
+
106
+ `pip install .`
107
+
108
+ #### Windows .bat scripts
109
+
110
+ There are two scripts that Windows users can use to simplify installing and running JABS. These can be executed by
111
+ double-clicking on them in Windows Explorer.
112
+
113
+ * setup_windows.bat: this will create a Python virtualenv called jabs.venv in the project root and then install JABS as
114
+ a Python package.
115
+ * launch_jabs.bat: this script will activate the jabs.venv environment and then launch the JABS GUI.
116
+
117
+ ### Running JABS
118
+
119
+ After installing JABS, five commands will be added to the bin directory of your Python virtualenv:
120
+
121
+ * jabs: launch the JABS GUI
122
+ * jabs-init: initialize a new JABS project directory from the command line
123
+ * jabs-classify: run a trained classifier from the command line
124
+ * jabs-stats: print accuracy statistics for the given classifier
125
+ * jabs-convert-parquet: convert parquet pose file to JABS pose file format
126
+
127
+ You can run the `<jabs command> --help` to get usage information for each of the commands.
128
+
129
+ **NOTE: On some platforms, the first time you run the JABS GUI it might take several minutes to launch. Subsequent
130
+ startup times should be significantly reduced.**
131
+
132
+ ### Developer Setup
133
+
134
+ The following instructions are for Linux or macOS Developers. Commands for JABS developers using Windows might be
135
+ slightly different.
136
+
137
+ This project now uses **uv** for dependency management and building. Poetry is no longer required.
138
+
139
+ JABS developers will need to install uv by following the instructions on
140
+ [uv's official website](https://docs.astral.sh/uv/getting-started/installation/).
141
+
142
+ 1) **Clone** the repository and enter the project directory.
143
+
144
+ 2) **Create/activate** a virtual environment (uv recommended):
145
+
146
+ Note, if you don't want to activate the virtualenv, you can use `uv run <command>` to run commands in the virtualenv.
147
+ If you don't want to activate the virtualenv, you can skip this step.
148
+
149
+ ```bash
150
+ uv venv
151
+ source .venv/bin/activate # Linux/macOS
152
+ # .venv\Scripts\Activate.ps1 # Windows PowerShell
153
+ ```
154
+
155
+ 3) **Install dependencies** in editable mode:
156
+
157
+ ```bash
158
+ uv sync
159
+ ```
160
+
161
+ This will install all dependencies and JABS will be installed in "editable" mode, meaning that the JABS Python modules
162
+ installed in the virtualenv will be links to the files in the cloned git repository. JABS code changes will be
163
+ reflected immediately in the Python environment.
164
+
165
+ Note to Developers: JABS uses package metadata to determine the version number. If you change the version number in the
166
+ pyproject.toml file, you will need to run `uv sync` to update the version number in the installed package so
167
+ that the GUI will display the correct version.
168
+
169
+
170
+ #### Adding Dependencies
171
+ ```
172
+ uv add <package> # runtime dependency
173
+ uv add --dev <package> # dev-only dependency
174
+ ```
175
+
176
+
177
+ #### Code Style
178
+
179
+ JABS uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting. Developers should run `ruff check` and `ruff format` before
180
+ committing code. A pre-commit hook is provided to run these commands automatically.
181
+
182
+ To install pre-commit hooks for linting and formatting run:
183
+
184
+ ```commandline
185
+ pre-commit install
186
+ ```
187
+
188
+ You can also run [ruff](https://docs.astral.sh/ruff/) directly from command line:
189
+
190
+ ```commandline
191
+ ruff check src/packagepath/modulename.py
192
+ ruff format src/packagepath/modulename.py
193
+ ```
194
+
195
+ #### Building Python Packages
196
+
197
+ Build wheels and source distributions with uv:
198
+
199
+ ```bash
200
+ uv build
201
+ ```
202
+
203
+ This will produce both a .tar.gz and a Python Wheel file (.whl) in the dist directory.
204
+
205
+ The wheel file can be installed with pip:
206
+ ```
207
+ pip install jabs_behavior_classifier-<version>-py3-none-any.whl
208
+ ```
209
+
210
+ Since the Wheel does not contain any compiled code it is platform independent.
211
+
212
+ ### Enabling XGBoost Classifier
213
+
214
+ The XGBoost Classifier has a dependency on the OpenMP library. This does not ship with macOS. XGBoost should work "out
215
+ of the box" on other platforms. On macOS, you can install libomp with Homebrew (preferred) with the following
216
+ command `brew install libomp`. You can also install libomp from source if you can't use Homebrew, but this is beyond
217
+ the scope of this Readme.
218
+
219
+ ### Singularity/Linux
220
+
221
+ We supply a tested pair of singularity definition files. The [first vm](vm/behavior-classifier-vm.def) is intended for command-line use on
222
+ compute clusters when scaling inferences. The [second vm](vm/behavior-classifier-vm-gui.def) is designed for interacting with the GUI in a portable
223
+ environment. Please inspect the definition files for related linux packages to run the software.
224
+
225
+ # JABS Project Portability
226
+
227
+ We have 4 version numbers in our software:
228
+
229
+ * JABS Python package version. This gets bumped every release.
230
+ * Feature version. This gets bumped every time we change feature values or the format used to store
231
+ calculated features.
232
+ * Classifier version. This gets bumped every time we change characteristics of classifiers.
233
+ * Prediction version. This gets bumped every time we change how predictions are stored.
234
+
235
+ ## Long Term Support of JABS-based Classifiers
236
+
237
+ There are multiple JABS Classifier artifacts that have different compatibility and portability characteristics.
238
+
239
+ * Project folders. These are the most compatible for upgrades. The vast majority of our upgrades to JABS will allow
240
+ transparent upgrades (e.g. re-generation of features) within the project folder without user interaction. We will
241
+ provide instructions for changes that are not.
242
+ * Exported training data. These are compatible across computers, but should generally not be considered compatible
243
+ across JABS package versions. Once we add the appropriate version checks, the error message should be a bit more
244
+ clear when and why these aren't compatible across versions.
245
+ * Classifier pickle files. These are only compatible within a specific install of the package (e.g. mac will not
246
+ be compatible with windows). These are the serialized trained classifiers, so load really fast, but should not be
247
+ considered portable beyond the computer and specific JABS install that created them.
248
+
249
+ Project folders are big, but are almost always compatible across JABS versions.
250
+
251
+ Exported classifiers are smaller and easier to move around, but might require the same JABS package version to run. These
252
+ are good for sharing or archiving specific versions (e.g. a version we use in a paper). A comon use case is to export
253
+ training data from a project folder, transfer it to our HPC cluster, and then train a and run classifier using the
254
+ `jabs-classify` command from same version of JABS that was used to export the training file.
255
+
256
+ Pickle files are tiny and efficient, but are not transferable across computers. We use these for large-scale
257
+ predictions in pipelines (for example, using exported training data to train a classifier saved as a .pickle file,
258
+ which can then be used to classify many videos as part of a pipeline).
259
+
260
+ ## CI/CD and Release Management
261
+
262
+ JABS uses GitHub Actions for continuous integration and automated releases to PyPI.
263
+ The CI/CD pipeline is defined in `.github/workflows/` and automatically manages package building, testing, and publishing.
264
+
265
+ ### Pull Request Checks
266
+
267
+ Pull requests to the `main` branch trigger automated checks to ensure code quality and functionality:
268
+
269
+ 1. **Code Formatting and Linting**: Ensures code adheres to style guidelines
270
+ 2. **Test Execution**: Runs the full test suite to verify functionality
271
+
272
+ ### Automated Release Process
273
+
274
+ The release process is triggered automatically when the version number in `pyproject.toml` is changed on the `main` branch:
275
+
276
+ 1. **Version Detection**: The workflow monitors changes to `pyproject.toml` and extracts the version number
277
+ 2. **Pre-release Detection**: Versions containing letters (e.g., `1.0.0a1`, `2.1.0rc1`) are automatically marked as pre-releases
278
+ 3. **Build Pipeline**: If version changed, the system runs:
279
+ - Code formatting and linting checks
280
+ - Test execution
281
+ - Package building with `uv build`
282
+ 4. **PyPI Publishing**: Successfully built packages are automatically published to PyPI
283
+ 5. **GitHub Release**: A corresponding GitHub release is created with build artifacts
284
+
285
+ ### Release Workflow Files
286
+
287
+ - **`.github/workflows/release.yml`**: Main release workflow that orchestrates the entire process
288
+ - **`.github/workflows/_format-lint-action.yml`**: Reusable workflow for code quality checks
289
+ - **`.github/workflows/_run-tests-action.yml`**: Reusable workflow for test execution
290
+ - **`.github/workflows/pull-request.yml`**: CI checks for pull requests
291
+
292
+ ### Creating a New Release
293
+
294
+ To create a new release:
295
+
296
+ 1. Update the version number in `pyproject.toml`:
297
+ ```toml
298
+ version = "X.Y.Z" # for stable releases
299
+ version = "X.Y.Za1" # for alpha pre-releases
300
+ version = "X.Y.Zrc1" # for release candidates
301
+ ```
302
+
303
+ 2. Re-lock the uv lock file:
304
+ ```bash
305
+ uv lock
306
+ ```
307
+
308
+ 3. Commit and push the change:
309
+ ```bash
310
+ git add pyproject.toml uv.lock
311
+ git commit -m "Bump version to X.Y.Z"
312
+ ```
313
+
314
+ 4. Merge your changes into the `main` branch via a pull request.
315
+
316
+ 3. The CI/CD pipeline will automatically:
317
+ - Detect the version change
318
+ - Run all quality checks and tests
319
+ - Build and publish the package to PyPI
320
+ - Create a GitHub release with generated release notes
321
+
322
+ ### Environment Requirements
323
+
324
+ The release workflow requires:
325
+ - **PyPI API Token**: Stored as `PYPI_API_TOKEN` in GitHub repository secrets
@@ -0,0 +1,296 @@
1
+ # JAX Animal Behavior System (JABS)
2
+
3
+ ![JABS Screen Shot](img/jabs_screenshot.png)
4
+
5
+ ## ReadTheDocs Tutorial and User Guide
6
+
7
+ https://jabs-tutorial.readthedocs.io/en/latest/index.html
8
+
9
+ [User Guide (Markdown)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/main/src/jabs/resources/docs/user_guide/user_guide.md)
10
+
11
+ ## Copyright
12
+
13
+ Copyright 2023 The Jackson Laboratory -- All rights reserved.
14
+
15
+ ## Contact
16
+
17
+ email us at jabs@jax.org
18
+
19
+ ## License
20
+
21
+ JABS is licensed under a non-commercial use license, see LICENSE for more information. Contact us for information about
22
+ licensing for commercial use.
23
+
24
+ ## Pose Files
25
+
26
+ JABS requires pose files generated from the Kumar Lab's mouse pose estimation neural networks. Single mouse pose files
27
+ are generated from [this repository](https://github.com/KumarLabJax/deep-hrnet-mouse). Multi-mouse is still under development. Contact us for more information.
28
+
29
+ ## Requirements
30
+
31
+ JABS was initially developed and tested on Python 3.10. See the `pyproject.toml` for a list of required Python
32
+ packages. These packages are available from the Python Package Index (PyPI).
33
+
34
+ Currently, JABS supports Python 3.10 through 3.13.
35
+
36
+ ## Python Environment Setup
37
+
38
+ We recommend creating a Python Virtualenv for JABS:
39
+
40
+ ```
41
+ python -m venv jabs.venv
42
+
43
+ # Linux and MacOS
44
+ source jabs.venv/bin/activate
45
+
46
+ # Windows
47
+ jabs.venv\Scripts\activate.bat
48
+ ```
49
+
50
+ ### JABS Installation
51
+
52
+ Developers should follow the Developer Setup section below. This section describes how to install JABS into a Python
53
+ environment for a non-developer user.
54
+
55
+ #### PyPI
56
+
57
+ JABS is not available on PyPI at this time, but we hope to begin publishing it there soon.
58
+
59
+ #### Pip install from Github
60
+
61
+ With the jabs.venv virtualenv activated, run the following command to install JABS from our git repository. This will
62
+ install the latest commit from the main branch:
63
+ `pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git`
64
+
65
+ you can also specify a branch or tag:
66
+
67
+ `pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git@branch-name`
68
+
69
+ or a specific commit:
70
+
71
+ `pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git@commit-hash`
72
+
73
+ #### Pip install from local source
74
+
75
+ If you've cloned the JABS repository, you can install by running the following command in the project root directory:
76
+
77
+ `pip install .`
78
+
79
+ #### Windows .bat scripts
80
+
81
+ There are two scripts that Windows users can use to simplify installing and running JABS. These can be executed by
82
+ double-clicking on them in Windows Explorer.
83
+
84
+ * setup_windows.bat: this will create a Python virtualenv called jabs.venv in the project root and then install JABS as
85
+ a Python package.
86
+ * launch_jabs.bat: this script will activate the jabs.venv environment and then launch the JABS GUI.
87
+
88
+ ### Running JABS
89
+
90
+ After installing JABS, five commands will be added to the bin directory of your Python virtualenv:
91
+
92
+ * jabs: launch the JABS GUI
93
+ * jabs-init: initialize a new JABS project directory from the command line
94
+ * jabs-classify: run a trained classifier from the command line
95
+ * jabs-stats: print accuracy statistics for the given classifier
96
+ * jabs-convert-parquet: convert parquet pose file to JABS pose file format
97
+
98
+ You can run the `<jabs command> --help` to get usage information for each of the commands.
99
+
100
+ **NOTE: On some platforms, the first time you run the JABS GUI it might take several minutes to launch. Subsequent
101
+ startup times should be significantly reduced.**
102
+
103
+ ### Developer Setup
104
+
105
+ The following instructions are for Linux or macOS Developers. Commands for JABS developers using Windows might be
106
+ slightly different.
107
+
108
+ This project now uses **uv** for dependency management and building. Poetry is no longer required.
109
+
110
+ JABS developers will need to install uv by following the instructions on
111
+ [uv's official website](https://docs.astral.sh/uv/getting-started/installation/).
112
+
113
+ 1) **Clone** the repository and enter the project directory.
114
+
115
+ 2) **Create/activate** a virtual environment (uv recommended):
116
+
117
+ Note, if you don't want to activate the virtualenv, you can use `uv run <command>` to run commands in the virtualenv.
118
+ If you don't want to activate the virtualenv, you can skip this step.
119
+
120
+ ```bash
121
+ uv venv
122
+ source .venv/bin/activate # Linux/macOS
123
+ # .venv\Scripts\Activate.ps1 # Windows PowerShell
124
+ ```
125
+
126
+ 3) **Install dependencies** in editable mode:
127
+
128
+ ```bash
129
+ uv sync
130
+ ```
131
+
132
+ This will install all dependencies and JABS will be installed in "editable" mode, meaning that the JABS Python modules
133
+ installed in the virtualenv will be links to the files in the cloned git repository. JABS code changes will be
134
+ reflected immediately in the Python environment.
135
+
136
+ Note to Developers: JABS uses package metadata to determine the version number. If you change the version number in the
137
+ pyproject.toml file, you will need to run `uv sync` to update the version number in the installed package so
138
+ that the GUI will display the correct version.
139
+
140
+
141
+ #### Adding Dependencies
142
+ ```
143
+ uv add <package> # runtime dependency
144
+ uv add --dev <package> # dev-only dependency
145
+ ```
146
+
147
+
148
+ #### Code Style
149
+
150
+ JABS uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting. Developers should run `ruff check` and `ruff format` before
151
+ committing code. A pre-commit hook is provided to run these commands automatically.
152
+
153
+ To install pre-commit hooks for linting and formatting run:
154
+
155
+ ```commandline
156
+ pre-commit install
157
+ ```
158
+
159
+ You can also run [ruff](https://docs.astral.sh/ruff/) directly from command line:
160
+
161
+ ```commandline
162
+ ruff check src/packagepath/modulename.py
163
+ ruff format src/packagepath/modulename.py
164
+ ```
165
+
166
+ #### Building Python Packages
167
+
168
+ Build wheels and source distributions with uv:
169
+
170
+ ```bash
171
+ uv build
172
+ ```
173
+
174
+ This will produce both a .tar.gz and a Python Wheel file (.whl) in the dist directory.
175
+
176
+ The wheel file can be installed with pip:
177
+ ```
178
+ pip install jabs_behavior_classifier-<version>-py3-none-any.whl
179
+ ```
180
+
181
+ Since the Wheel does not contain any compiled code it is platform independent.
182
+
183
+ ### Enabling XGBoost Classifier
184
+
185
+ The XGBoost Classifier has a dependency on the OpenMP library. This does not ship with macOS. XGBoost should work "out
186
+ of the box" on other platforms. On macOS, you can install libomp with Homebrew (preferred) with the following
187
+ command `brew install libomp`. You can also install libomp from source if you can't use Homebrew, but this is beyond
188
+ the scope of this Readme.
189
+
190
+ ### Singularity/Linux
191
+
192
+ We supply a tested pair of singularity definition files. The [first vm](vm/behavior-classifier-vm.def) is intended for command-line use on
193
+ compute clusters when scaling inferences. The [second vm](vm/behavior-classifier-vm-gui.def) is designed for interacting with the GUI in a portable
194
+ environment. Please inspect the definition files for related linux packages to run the software.
195
+
196
+ # JABS Project Portability
197
+
198
+ We have 4 version numbers in our software:
199
+
200
+ * JABS Python package version. This gets bumped every release.
201
+ * Feature version. This gets bumped every time we change feature values or the format used to store
202
+ calculated features.
203
+ * Classifier version. This gets bumped every time we change characteristics of classifiers.
204
+ * Prediction version. This gets bumped every time we change how predictions are stored.
205
+
206
+ ## Long Term Support of JABS-based Classifiers
207
+
208
+ There are multiple JABS Classifier artifacts that have different compatibility and portability characteristics.
209
+
210
+ * Project folders. These are the most compatible for upgrades. The vast majority of our upgrades to JABS will allow
211
+ transparent upgrades (e.g. re-generation of features) within the project folder without user interaction. We will
212
+ provide instructions for changes that are not.
213
+ * Exported training data. These are compatible across computers, but should generally not be considered compatible
214
+ across JABS package versions. Once we add the appropriate version checks, the error message should be a bit more
215
+ clear when and why these aren't compatible across versions.
216
+ * Classifier pickle files. These are only compatible within a specific install of the package (e.g. mac will not
217
+ be compatible with windows). These are the serialized trained classifiers, so load really fast, but should not be
218
+ considered portable beyond the computer and specific JABS install that created them.
219
+
220
+ Project folders are big, but are almost always compatible across JABS versions.
221
+
222
+ Exported classifiers are smaller and easier to move around, but might require the same JABS package version to run. These
223
+ are good for sharing or archiving specific versions (e.g. a version we use in a paper). A comon use case is to export
224
+ training data from a project folder, transfer it to our HPC cluster, and then train a and run classifier using the
225
+ `jabs-classify` command from same version of JABS that was used to export the training file.
226
+
227
+ Pickle files are tiny and efficient, but are not transferable across computers. We use these for large-scale
228
+ predictions in pipelines (for example, using exported training data to train a classifier saved as a .pickle file,
229
+ which can then be used to classify many videos as part of a pipeline).
230
+
231
+ ## CI/CD and Release Management
232
+
233
+ JABS uses GitHub Actions for continuous integration and automated releases to PyPI.
234
+ The CI/CD pipeline is defined in `.github/workflows/` and automatically manages package building, testing, and publishing.
235
+
236
+ ### Pull Request Checks
237
+
238
+ Pull requests to the `main` branch trigger automated checks to ensure code quality and functionality:
239
+
240
+ 1. **Code Formatting and Linting**: Ensures code adheres to style guidelines
241
+ 2. **Test Execution**: Runs the full test suite to verify functionality
242
+
243
+ ### Automated Release Process
244
+
245
+ The release process is triggered automatically when the version number in `pyproject.toml` is changed on the `main` branch:
246
+
247
+ 1. **Version Detection**: The workflow monitors changes to `pyproject.toml` and extracts the version number
248
+ 2. **Pre-release Detection**: Versions containing letters (e.g., `1.0.0a1`, `2.1.0rc1`) are automatically marked as pre-releases
249
+ 3. **Build Pipeline**: If version changed, the system runs:
250
+ - Code formatting and linting checks
251
+ - Test execution
252
+ - Package building with `uv build`
253
+ 4. **PyPI Publishing**: Successfully built packages are automatically published to PyPI
254
+ 5. **GitHub Release**: A corresponding GitHub release is created with build artifacts
255
+
256
+ ### Release Workflow Files
257
+
258
+ - **`.github/workflows/release.yml`**: Main release workflow that orchestrates the entire process
259
+ - **`.github/workflows/_format-lint-action.yml`**: Reusable workflow for code quality checks
260
+ - **`.github/workflows/_run-tests-action.yml`**: Reusable workflow for test execution
261
+ - **`.github/workflows/pull-request.yml`**: CI checks for pull requests
262
+
263
+ ### Creating a New Release
264
+
265
+ To create a new release:
266
+
267
+ 1. Update the version number in `pyproject.toml`:
268
+ ```toml
269
+ version = "X.Y.Z" # for stable releases
270
+ version = "X.Y.Za1" # for alpha pre-releases
271
+ version = "X.Y.Zrc1" # for release candidates
272
+ ```
273
+
274
+ 2. Re-lock the uv lock file:
275
+ ```bash
276
+ uv lock
277
+ ```
278
+
279
+ 3. Commit and push the change:
280
+ ```bash
281
+ git add pyproject.toml uv.lock
282
+ git commit -m "Bump version to X.Y.Z"
283
+ ```
284
+
285
+ 4. Merge your changes into the `main` branch via a pull request.
286
+
287
+ 3. The CI/CD pipeline will automatically:
288
+ - Detect the version change
289
+ - Run all quality checks and tests
290
+ - Build and publish the package to PyPI
291
+ - Create a GitHub release with generated release notes
292
+
293
+ ### Environment Requirements
294
+
295
+ The release workflow requires:
296
+ - **PyPI API Token**: Stored as `PYPI_API_TOKEN` in GitHub repository secrets
@@ -0,0 +1,75 @@
1
+ [project]
2
+ name = "jabs-behavior-classifier"
3
+ version = "0.36.0"
4
+ description = ""
5
+ readme = "README.md"
6
+ requires-python = ">=3.10,<3.14"
7
+ license = { text = "Proprietary" }
8
+
9
+ authors = [
10
+ { name = "Glen Beane" },
11
+ { name = "Brian Geuther" },
12
+ { name = "Keith Sheppard" },
13
+ ]
14
+
15
+ dependencies = [
16
+ "h5py>=3.10.0,<4.0.0",
17
+ "markdown2>=2.5.1,<3.0.0",
18
+ "numpy>=2.0.0,<3.0.0",
19
+ "opencv-python-headless>=4.8.1.78,<5.0.0",
20
+ "pandas>=2.2.2,<3.0.0",
21
+ "pyside6>=6.8.0,!=6.9.0",
22
+ "scikit-learn>=1.5.0,<2.0.0",
23
+ "shapely>=2.0.1,<3.0.0",
24
+ "tabulate>=0.9.0,<1.0.0",
25
+ "toml>=0.10.2,<0.11.0",
26
+ "xgboost>=2.0.0,<3.0.0",
27
+ "pyarrow>=20.0.0,<21.0.0",
28
+ "rich>=14.0.0,<15.0.0",
29
+ "rich-argparse>=1.7.1,<2.0.0",
30
+ "intervaltree>=3.1.0,<4.0.0",
31
+ "qt-material-icons>=0.2.0,<0.3.0",
32
+ "jsonschema>=4.25.1,<5.0.0",
33
+ "click>=8.2.1",
34
+ ]
35
+
36
+ [dependency-groups]
37
+ dev = [
38
+ {include-group = "lint"},
39
+ {include-group = "test"},
40
+ "pre-commit>=4.2.0,<5.0.0",
41
+ ]
42
+ test = [
43
+ "pytest>=8.3.4,<9.0.0",
44
+ "matplotlib>=3.9.3,<4.0.0",
45
+ ]
46
+ lint = [
47
+ "ruff>=0.11.5,<0.12.0",
48
+ ]
49
+
50
+ [project.urls]
51
+ Repository = "https://github.com/KumarLabJax/JABS-behavior-classifier"
52
+ Issues = "https://github.com/KumarLabJax/JABS-behavior-classifier/issues"
53
+
54
+ [project.scripts]
55
+ jabs = "jabs.scripts.gui_entrypoint:main"
56
+ "jabs-classify" = "jabs.scripts.classify:main"
57
+ "jabs-init" = "jabs.scripts.initialize_project:main"
58
+ "jabs-features" = "jabs.scripts.generate_features:main"
59
+ "jabs-stats" = "jabs.scripts.stats:main"
60
+ "jabs-convert-parquet" = "jabs.scripts.convert_parquet:main"
61
+ "jabs-project-merge" = "jabs.scripts.merge_projects:main"
62
+ "jabs-cli" = "jabs.scripts.cli:main"
63
+
64
+ # Poetry-specific config kept for src/ layout and Poetry's own dev group
65
+ [tool.poetry]
66
+ packages = [
67
+ { include = "jabs", from = "src" },
68
+ ]
69
+
70
+ [build-system]
71
+ requires = ["uv_build>=0.7.19,<0.8.0"]
72
+ build-backend = "uv_build"
73
+
74
+ [tool.uv.build-backend]
75
+ module-name = "jabs"
@@ -0,0 +1 @@
1
+ """JABS Behavior Classifier"""