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.
- jabs_behavior_classifier-0.36.0/PKG-INFO +325 -0
- jabs_behavior_classifier-0.36.0/README.md +296 -0
- jabs_behavior_classifier-0.36.0/pyproject.toml +75 -0
- jabs_behavior_classifier-0.36.0/src/jabs/__init__.py +1 -0
- jabs_behavior_classifier-0.36.0/src/jabs/__main__.py +4 -0
- jabs_behavior_classifier-0.36.0/src/jabs/behavior_search/__init__.py +11 -0
- jabs_behavior_classifier-0.36.0/src/jabs/behavior_search/behavior_search_util.py +301 -0
- jabs_behavior_classifier-0.36.0/src/jabs/classifier/__init__.py +16 -0
- jabs_behavior_classifier-0.36.0/src/jabs/classifier/classifier.py +676 -0
- jabs_behavior_classifier-0.36.0/src/jabs/constants.py +10 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/__init__.py +20 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/angle_index.py +99 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/__init__.py +23 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/angles.py +65 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/angular_velocity.py +59 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/base_group.py +43 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/centroid_velocity.py +91 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/pairwise_distances.py +44 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/point_speeds.py +41 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/base_features/point_velocities.py +50 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/feature_base_class.py +361 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/feature_group_base_class.py +112 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/features.py +765 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/__init__.py +3 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/corner.py +314 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/food_hopper.py +68 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/landmark_group.py +246 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/landmark_features/lixit.py +321 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/__init__.py +20 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/hu_moments.py +48 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/moment_cache.py +156 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/moments.py +63 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/segment_group.py +45 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/segmentation_features/shape_descriptors.py +145 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/__init__.py +21 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/closest_distances.py +51 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/closest_fov_angles.py +57 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/closest_fov_distances.py +47 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/pairwise_social_distances.py +88 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/social_distance.py +172 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/social_features/social_group.py +72 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/window_operations/__init__.py +6 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/window_operations/signal_stats.py +155 -0
- jabs_behavior_classifier-0.36.0/src/jabs/feature_extraction/window_operations/window_stats.py +198 -0
- jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/__init__.py +110 -0
- jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est.py +379 -0
- jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v2.py +146 -0
- jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v3.py +335 -0
- jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v4.py +319 -0
- jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v5.py +117 -0
- jabs_behavior_classifier-0.36.0/src/jabs/pose_estimation/pose_est_v6.py +143 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/__init__.py +19 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/export_training.py +105 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/feature_manager.py +159 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/prediction_manager.py +172 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/project.py +648 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/project_merge.py +114 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/project_paths.py +84 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/project_pruning.py +56 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/project_utils.py +25 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/read_training.py +123 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/session_tracker.py +340 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/settings_manager.py +182 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/timeline_annotations.py +261 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/track_labels.py +263 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/video_labels.py +244 -0
- jabs_behavior_classifier-0.36.0/src/jabs/project/video_manager.py +214 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/__init__.py +20 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/features/features.md +196 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/StackedImgs.svg +35243 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/centroid-identity-overlay.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/classifier_controls.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/floating-identity-overlay.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/identity_gaps.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/identity_gaps_with_label.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/keypoint_legend.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/label_viz.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/main_window.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/minimalist-identity-overlay.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/pose_overlay.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/selecting_frames.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/stacked_timeline.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/timeline_menu.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/track_overlay.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/video-control-overlay.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/imgs/video-control-overlay.svg +178 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/docs/user_guide/user_guide.md +841 -0
- jabs_behavior_classifier-0.36.0/src/jabs/resources/icon.png +0 -0
- jabs_behavior_classifier-0.36.0/src/jabs/schema/__init__.py +1 -0
- jabs_behavior_classifier-0.36.0/src/jabs/schema/metadata.py +115 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/__init__.py +3 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/classify.py +363 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/cli.py +109 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/convert_parquet.py +331 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/generate_features.py +106 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/gui_entrypoint.py +46 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/initialize_project.py +315 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/merge_projects.py +87 -0
- jabs_behavior_classifier-0.36.0/src/jabs/scripts/stats.py +136 -0
- jabs_behavior_classifier-0.36.0/src/jabs/types/__init__.py +4 -0
- jabs_behavior_classifier-0.36.0/src/jabs/types/classifier_types.py +9 -0
- jabs_behavior_classifier-0.36.0/src/jabs/types/units.py +8 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/__init__.py +5 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/about_dialog.py +42 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/annotation_edit_dialog.py +377 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/archive_behavior_dialog.py +70 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/behavior_search_dialog.py +472 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/central_widget.py +1301 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/classification_thread.py +176 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/colors.py +36 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/exceptions.py +6 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/k_fold_slider_widget.py +47 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/label_count_widget.py +159 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/license_dialog.py +44 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/main_control_widget.py +644 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/main_window.py +912 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/__init__.py +7 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/frame_with_overlays.py +513 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/__init__.py +1 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/annotation_info_dialog.py +154 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/annotation_overlay.py +233 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/control_overlay.py +626 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/floating_id_overlay.py +261 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/label_overlay.py +95 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/overlay.py +90 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/overlays/pose_overlay.py +125 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/player_thread.py +286 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/player_widget/player_widget.py +608 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/progress_dialog.py +139 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/project_loader_thread.py +38 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/project_pruning_dialog.py +197 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/search_bar_widget.py +426 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/__init__.py +12 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/frame_labels_widget.py +113 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/__init__.py +18 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/label_overview_util.py +89 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/label_overview_widget.py +190 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/manual_label_widget.py +388 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/predicted_label_widget.py +149 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/prediction_overview_widget.py +41 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/timeline_label_widget.py +259 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/label_overview_widget/timeline_prediction_widget.py +65 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/stacked_timeline_widget/stacked_timeline_widget.py +475 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/training_thread.py +255 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/user_guide_dialog.py +81 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/util.py +38 -0
- jabs_behavior_classifier-0.36.0/src/jabs/ui/video_list_widget.py +218 -0
- jabs_behavior_classifier-0.36.0/src/jabs/utils/__init__.py +15 -0
- jabs_behavior_classifier-0.36.0/src/jabs/utils/pose_util.py +36 -0
- jabs_behavior_classifier-0.36.0/src/jabs/utils/sampleposeintervals.py +269 -0
- jabs_behavior_classifier-0.36.0/src/jabs/utils/utilities.py +135 -0
- jabs_behavior_classifier-0.36.0/src/jabs/version/__init__.py +24 -0
- jabs_behavior_classifier-0.36.0/src/jabs/video_reader/__init__.py +21 -0
- jabs_behavior_classifier-0.36.0/src/jabs/video_reader/frame_annotation.py +274 -0
- jabs_behavior_classifier-0.36.0/src/jabs/video_reader/utilities.py +31 -0
- 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
|
+

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

|
|
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"""
|