jabs-behavior-classifier 0.46.2__tar.gz → 0.46.3__tar.gz

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: jabs-behavior-classifier
-Version: 0.46.2
+Version: 0.46.3
 Summary: 
 Author: Glen Beane, Brian Geuther, Keith Sheppard, Alexander Berger-Liedtka
 License-Expression: MIT
 License-File: LICENSE
-Requires-Dist: jabs-behavior==0.46.2
-Requires-Dist: jabs-core==0.46.2
-Requires-Dist: jabs-io==0.46.2
+Requires-Dist: jabs-behavior==0.46.3
+Requires-Dist: jabs-core==0.46.3
+Requires-Dist: jabs-io==0.46.3
 Requires-Dist: h5py>=3.10.0,<4.0.0
 Requires-Dist: markdown2>=2.5.1,<3.0.0
 Requires-Dist: numpy>=2.0.0,<3.0.0
@@ -22,7 +22,6 @@ Requires-Dist: toml>=0.10.2,<0.11.0
 Requires-Dist: xgboost>=2.0.0,<3.0.0
 Requires-Dist: pyarrow>=23.0.1,<24.0.0
 Requires-Dist: rich>=14.0.0,<15.0.0
-Requires-Dist: rich-argparse>=1.7.1,<2.0.0
 Requires-Dist: intervaltree>=3.1.0,<4.0.0
 Requires-Dist: qt-material-icons>=0.2.0,<0.3.0
 Requires-Dist: jsonschema>=4.25.1,<5.0.0
@@ -51,14 +50,14 @@ Description-Content-Type: text/markdown
 
 [![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://img.shields.io/pypi/v/jabs-behavior-classifier.svg)](https://pypi.org/project/jabs-behavior-classifier/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/LICENSE)
 [![DOI](https://img.shields.io/badge/DOI-10.7554%2FeLife.107259.2-green.svg)](https://doi.org/10.7554/eLife.107259.2)
 
-[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
+[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
 
 ---
 
-![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.46.2/docs/assets/images/jabs_screenshot.png)
+![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.46.3/docs/assets/images/jabs_screenshot.png)
 
 </div>
 
@@ -188,7 +187,7 @@ JABS requires pose files generated from the Kumar Lab's mouse pose estimation ne
 
 We provide Singularity/Apptainer definition files and SLURM batch scripts for running
 JABS on Linux compute clusters. See
-[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/vm/README.md)
+[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/vm/README.md)
 for build instructions and usage details.
 
 ## Project Portability
@@ -224,14 +223,14 @@ JABS uses four version numbers to track compatibility:
 ## Documentation
 
 - **[ReadTheDocs Tutorial](https://jabs-tutorial.readthedocs.io/)** — Complete user guide and tutorials
-- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/docs/user-guide/overview.md)** — Markdown documentation
+- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/docs/user-guide/overview.md)** — Markdown documentation
 - **[Sample Data](https://doi.org/10.5281/zenodo.16697331)** — Test datasets for demonstration
 
 ## Contributing
 
 Interested in contributing? Check out our:
-- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/CONTRIBUTING.md)
-- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/docs/development/development.md)
+- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/CONTRIBUTING.md)
+- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/docs/development/development.md)
 
 ## Citation
 

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/README.md

@@ -8,14 +8,14 @@
 
 [![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://img.shields.io/pypi/v/jabs-behavior-classifier.svg)](https://pypi.org/project/jabs-behavior-classifier/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/LICENSE)
 [![DOI](https://img.shields.io/badge/DOI-10.7554%2FeLife.107259.2-green.svg)](https://doi.org/10.7554/eLife.107259.2)
 
-[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
+[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
 
 ---
 
-![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.46.2/docs/assets/images/jabs_screenshot.png)
+![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.46.3/docs/assets/images/jabs_screenshot.png)
 
 </div>
 
@@ -145,7 +145,7 @@ JABS requires pose files generated from the Kumar Lab's mouse pose estimation ne
 
 We provide Singularity/Apptainer definition files and SLURM batch scripts for running
 JABS on Linux compute clusters. See
-[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/vm/README.md)
+[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/vm/README.md)
 for build instructions and usage details.
 
 ## Project Portability
@@ -181,14 +181,14 @@ JABS uses four version numbers to track compatibility:
 ## Documentation
 
 - **[ReadTheDocs Tutorial](https://jabs-tutorial.readthedocs.io/)** — Complete user guide and tutorials
-- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/docs/user-guide/overview.md)** — Markdown documentation
+- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/docs/user-guide/overview.md)** — Markdown documentation
 - **[Sample Data](https://doi.org/10.5281/zenodo.16697331)** — Test datasets for demonstration
 
 ## Contributing
 
 Interested in contributing? Check out our:
-- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/CONTRIBUTING.md)
-- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.2/docs/development/development.md)
+- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/CONTRIBUTING.md)
+- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.3/docs/development/development.md)
 
 ## Citation
 

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jabs-behavior-classifier"
-version = "0.46.2"
+version = "0.46.3"
 description = ""
 readme = "README.md"
 requires-python = ">=3.10,<3.15"
@@ -15,9 +15,9 @@ authors = [
 ]
 
 dependencies = [
-  "jabs-behavior==0.46.2",
-  "jabs-core==0.46.2",
-  "jabs-io==0.46.2",
+  "jabs-behavior==0.46.3",
+  "jabs-core==0.46.3",
+  "jabs-io==0.46.3",
   "h5py>=3.10.0,<4.0.0",
   "markdown2>=2.5.1,<3.0.0",
   "numpy>=2.0.0,<3.0.0",
@@ -32,7 +32,6 @@ dependencies = [
   "xgboost>=2.0.0,<3.0.0",
   "pyarrow>=23.0.1,<24.0.0",
   "rich>=14.0.0,<15.0.0",
-  "rich-argparse>=1.7.1,<2.0.0",
   "intervaltree>=3.1.0,<4.0.0",
   "qt-material-icons>=0.2.0,<0.3.0",
   "jsonschema>=4.25.1,<5.0.0",
@@ -87,7 +86,6 @@ jabs = "jabs.scripts.gui_entrypoint:main"
 "jabs-classify" = "jabs.scripts.classify:main"
 "jabs-init" = "jabs.scripts.initialize_project:main"
 "jabs-features" = "jabs.scripts.generate_features:main"
-"jabs-project-merge" = "jabs.scripts.merge_projects:main"
 "jabs-cli" = "jabs.scripts.cli:main"
 
 [tool.uv.workspace]

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/src/jabs/feature_extraction/feature_base_class.py

@@ -197,7 +197,7 @@ class Feature(abc.ABC):
             non_circular = per_frame_features
 
         # standard method for computing window features on non-circular values
-        non_circular_features = self._window_standard(identity, window_size, non_circular)
+        non_circular_features = self._window_standard(window_size, non_circular)
 
         # non_circular_features and circular_features are both dicts of dicts, but they may have overlapping *top level* keys.
         merged = dict(non_circular_features)  # start with dict1's keys/values
@@ -209,30 +209,45 @@ class Feature(abc.ABC):
 
         return merged
 
-    def _window_standard(self, identity: int, window_size: int, per_frame_values: dict) -> dict:
+    def _window_standard(self, window_size: int, per_frame_values: dict) -> dict:
         """standard method for computing standard window feature values
 
+        This path does not take an identity mask: per-frame values are nan for frames
+        where the identity is not present, and the operations in
+        `window_operations.window_stats` already ignore nan values. Frames are only
+        masked explicitly on the circular path, which builds each window itself
+        (see `_compute_window_features_circular`).
+
         NOTE: some features may need to override this (for example, those with
         circular values such as angles)
+
+        Args:
+            window_size: number of frames (in each direction) to include in the
+                window. The actual number of frames is 2 * window_size + 1
+            per_frame_values: dict of per-frame values for this identity
+
+        Returns:
+            dict of window and signal processing feature values
         """
         values = {}
         for op in self._window_operations:
             values[op] = self._compute_window_feature(
                 per_frame_values,
-                self._poses.identity_mask(identity),
                 window_size,
                 self._window_operations[op],
             )
         # Also include signal features
-        signal_features = self._window_signal(identity, window_size, per_frame_values)
+        signal_features = self._window_signal(window_size, per_frame_values)
         values.update(signal_features)
         return values
 
-    def _window_signal(self, identity: int, window_size: int, per_frame_values: dict) -> dict:
+    def _window_signal(self, window_size: int, per_frame_values: dict) -> dict:
         """The standard method for computing signal processing window features.
 
+        As with `_window_standard`, this path does not take an identity mask: nan
+        per-frame values are zero-filled before the short-time Fourier transform.
+
         Args:
-            identity: The identity of the mouse.
             window_size: The window size used for signal formation.
             per_frame_values: The values for a particular feature.
 
@@ -277,15 +292,12 @@ class Feature(abc.ABC):
                         self._compute_signal_features(
                             freqs,
                             psd_data,
-                            self._poses.identity_mask(identity),
                             op,
                             **band,
                         )
                     )
             else:
-                values[op_name] = self._compute_signal_features(
-                    freqs, psd_data, self._poses.identity_mask(identity), op
-                )
+                values[op_name] = self._compute_signal_features(freqs, psd_data, op)
 
         return values
 
@@ -310,7 +322,6 @@ class Feature(abc.ABC):
     def _compute_window_feature(
         self,
         feature_values: dict,
-        frame_mask: np.ndarray,
         window_size: int,
         op: typing.Callable,
     ) -> dict:
@@ -318,16 +329,15 @@ class Feature(abc.ABC):
 
         Args:
             feature_values: dict of per frame feature values
-            frame_mask: array indicating which frames are valid for the current identity
             window_size: number of frames (in each direction) to include in the window. The actual number of frames is 2 * window_size + 1
             op: function to perform the actual computation
 
         Returns:
-            dict containing feature values
+            dict mapping each per-frame feature name to its window feature values
         """
         values = {}
         for key, val in feature_values.items():
-            values[f"{key}"] = op(val, window=window_size)
+            values[key] = op(val, window=window_size)
 
         return values
 
@@ -335,7 +345,6 @@ class Feature(abc.ABC):
         self,
         freqs: np.ndarray,
         psd: dict,
-        frame_mask: np.ndarray,
         op: typing.Callable,
         **kwargs,
     ) -> dict:
@@ -344,18 +353,15 @@ class Feature(abc.ABC):
         Args:
             freqs: frequency values for psd matrices
             psd: dict of power spectral density
-            frame_mask: array indicating which frames are valid for the current identity
             op: function to perform the actual computation. Operation must accept frequencies and psd as input
             **kwargs: additional keyword args used by op
 
-
-
         Returns:
-            numpy nd array containing feature values
+            dict mapping each per-frame feature name to its signal feature values
         """
         values = {}
         for key, value in psd.items():
-            values[f"{key}"] = op(freqs, value, **kwargs)
+            values[key] = op(freqs, value, **kwargs)
 
         return values
 

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/src/jabs/feature_extraction/landmark_features/corner.py

@@ -28,6 +28,11 @@ class CornerDistanceInfo:
         self._cached_bearings = {}
         self._all_wall_distances = {}
 
+        # None until cache_features() runs; it is then set to the arena's average
+        # wall length, or NaN when the pose file has no "corners" static object.
+        # get_avg_wall_length() relies on this None to know it must still compute.
+        self._avg_wall_length: float | None = None
+
     def cache_features(self, identity: int):
         """cache corner distances and bearings for a given identity
 
@@ -199,11 +204,17 @@ class CornerDistanceInfo:
     def get_avg_wall_length(self, identity: int = 0) -> float:
         """gets the average wall length
 
+        The average wall length is a property of the arena rather than of an
+        individual mouse, so a single instance-wide value is shared by every
+        identity. ``cache_features()`` derives it from the same static corners
+        every time it runs for a new identity, overwriting the stored value
+        with an identical one.
+
         Args:
             identity: identity to cache if not yet calculated
 
         Returns:
-            average wall length
+            average wall length, or NaN if the pose file has no corners
         """
         if self._avg_wall_length is None:
             self.cache_features(identity)

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/src/jabs/feature_extraction/window_operations/signal_stats.py

@@ -64,14 +64,18 @@ def psd_mean_band(
 ) -> np.ndarray:
     """Calculates the mean power spectral density in a band
 
+    Unlike the other functions in this module, this one uses ``freqs`` -- it is
+    what selects the rows of ``psd`` that fall inside the band.
+
     Args:
-        freqs: frequencies in the psd, ignored
+        freqs: frequencies in the psd, used to select the band
         psd: power spectral density matrix
-        band_low: lower bound of the frequency band
-        band_high: upper bound of the frequency band
+        band_low: inclusive lower bound of the frequency band
+        band_high: exclusive upper bound of the frequency band
 
     Returns:
-        mean of power
+        mean of power over the frequencies in the band, or an array of nan if no
+        frequency falls inside the band
     """
     idx = np.logical_and(freqs >= band_low, freqs < band_high)
 
@@ -109,12 +113,16 @@ def psd_std_dev(freqs: np.ndarray, psd: np.ndarray) -> np.ndarray:
 def psd_kurtosis(freqs: np.ndarray, psd: np.ndarray) -> np.ndarray:
     """Calculates the kurtosis power spectral density
 
+    This uses scipy's default, which is Fisher (excess) kurtosis. The ``kurtosis``
+    window operation in ``window_operations.window_stats`` reports Pearson
+    (non-excess) kurtosis instead, so the two are offset by 3.0.
+
     Args:
         freqs: frequencies in the psd, ignored
         psd: power spectral density matrix
 
     Returns:
-        kurtosis of power
+        excess kurtosis of power
     """
     with warnings.catch_warnings():
         warnings.simplefilter("ignore", category=RuntimeWarning)

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/src/jabs/feature_extraction/window_operations/window_stats.py

@@ -8,13 +8,14 @@ def pad_sliding_window(arr: np.ndarray, window: int, pad_const: float | None = N
 
     Args:
         arr: 1d array to generate a sliding window
-        window: half size of sliding window
+        window: number of frames to include on each side of the center frame. The
+            resulting window spans ``2 * window + 1`` frames.
         pad_const: Constant to pad the array with. None will pad with value at the edge.
 
     Returns:
         an unmodifiable 2d view of the input array where the first axis is time and the second axis is the window. Note that typical usage will use summary stats with axis=1.
     """
-    if pad_const:
+    if pad_const is not None:
         arr_ext = np.concatenate([np.full(window, pad_const), arr, np.full(window, pad_const)])
     else:
         arr_ext = np.concatenate([np.full(window, arr[0]), arr, np.full(window, arr[-1])])
@@ -22,21 +23,25 @@ def pad_sliding_window(arr: np.ndarray, window: int, pad_const: float | None = N
 
 
 def get_window_masks(sliding_window_view: np.ndarray, const: float) -> np.ndarray:
-    """Creates a mask for invalid values in a sliding window matrix.
+    """Creates a mask identifying the usable values in a sliding window matrix.
 
     Args:
         sliding_window_view: sliding window matrix from `pad_sliding_window`
         const: constant pad value
 
     Returns:
-        matrix describing valid (0) and invalid (1) window values
+        boolean matrix that is True for valid window values and False for values
+        equal to the pad constant. Rows where every value is the pad constant are
+        returned as all True, since masking them entirely would leave the
+        downstream reduction with no data to operate on.
     """
     if np.isnan(const):
         window_masks = ~np.isnan(sliding_window_view)
     else:
         window_masks = sliding_window_view != const
-    for no_data_row in np.where(np.all(~window_masks, axis=1)):
-        window_masks[no_data_row] = True
+
+    no_data_rows = np.all(~window_masks, axis=1)
+    window_masks[no_data_rows] = True
 
     return window_masks
 
@@ -46,7 +51,8 @@ def window_mean(values: np.ndarray, window: int) -> np.ndarray:
 
     Args:
         values: 1d np.ndarray of values
-        window: window size
+        window: number of frames to include on each side of the center frame. The
+            window used for each output value spans ``2 * window + 1`` frames.
 
     Returns:
         sliding window mean values
@@ -63,7 +69,8 @@ def window_median(values: np.ndarray, window: int) -> np.ndarray:
 
     Args:
         values: 1d np.ndarray of values
-        window: window size
+        window: number of frames to include on each side of the center frame. The
+            window used for each output value spans ``2 * window + 1`` frames.
 
     Returns:
         sliding window median values
@@ -78,7 +85,8 @@ def window_std_dev(values: np.ndarray, window: int) -> np.ndarray:
 
     Args:
         values: 1d np.ndarray of values
-        window: window size
+        window: number of frames to include on each side of the center frame. The
+            window used for each output value spans ``2 * window + 1`` frames.
 
     Returns:
         sliding window standard deviation values
@@ -93,14 +101,26 @@ def window_std_dev(values: np.ndarray, window: int) -> np.ndarray:
 def np_kurtosis(values: np.ndarray) -> np.ndarray:
     """Calculates kurtosis in a rolling window faster than scipy
 
+    This computes Pearson (non-excess) kurtosis, equivalent to
+    ``scipy.stats.kurtosis(values, axis=1, nan_policy="omit", fisher=False)``. It is
+    *not* equivalent to scipy's default, which subtracts 3.0 to give Fisher (excess)
+    kurtosis: values returned here are 3.0 larger than
+    ``scipy.stats.kurtosis(values, axis=1, nan_policy="omit")``.
+
+    Note that ``signal_stats.psd_kurtosis`` calls scipy with its default arguments, so
+    the ``kurtosis`` window feature and the ``psd_kurtosis`` signal feature do not use
+    the same convention.
+
     Args:
-        values: 2d array of with time and a window
+        values: 2d array with time on the first axis and the window on the second
 
     Returns:
-        kurtosis values that match scipy.stats.kurtosis(values, axis, nan_policy='omit')
+        Pearson kurtosis of the non-nan values in each window. A window that is
+        entirely nan yields nan.
 
-    Raises:
-        RuntimeWarning when an entire window is nans
+    Note:
+        numpy emits (does not raise) a RuntimeWarning when an entire window is nan.
+        Callers such as `window_kurtosis` suppress that warning.
     """
     mean = np.nanmean(values, axis=1)
     std = np.nanstd(values, axis=1)
@@ -115,7 +135,8 @@ def window_kurtosis(values: np.ndarray, window: int) -> np.ndarray:
 
     Args:
         values: 1d np.ndarray of values
-        window: window size
+        window: number of frames to include on each side of the center frame. The
+            window used for each output value spans ``2 * window + 1`` frames.
 
     Returns:
         sliding window kurtosis values
@@ -130,14 +151,19 @@ def window_kurtosis(values: np.ndarray, window: int) -> np.ndarray:
 def np_skew(values: np.ndarray) -> np.ndarray:
     """Calculates skew in a rolling window faster than scipy
 
+    This computes the biased (population) skew, equivalent to
+    ``scipy.stats.skew(values, axis=1, nan_policy="omit")``, which is scipy's default.
+
     Args:
-        values: 2d array of with time and a window
+        values: 2d array with time on the first axis and the window on the second
 
     Returns:
-        skew values that match scipy.stats.skew(values, axis, nan_policy='omit')
+        skew of the non-nan values in each window. A window that is entirely nan
+        yields nan.
 
-    Raises:
-        RuntimeWarning when an entire window is nans
+    Note:
+        numpy emits (does not raise) a RuntimeWarning when an entire window is nan.
+        Callers such as `window_skew` suppress that warning.
     """
     mean = np.nanmean(values, axis=1)
     std = np.nanstd(values, axis=1)
@@ -152,7 +178,8 @@ def window_skew(values: np.ndarray, window: int) -> np.ndarray:
 
     Args:
         values: 1d np.ndarray of values
-        window: window size
+        window: number of frames to include on each side of the center frame. The
+            window used for each output value spans ``2 * window + 1`` frames.
 
     Returns:
         sliding window skew values
@@ -165,14 +192,15 @@ def window_skew(values: np.ndarray, window: int) -> np.ndarray:
 
 
 def window_min(values: np.ndarray, window: int) -> np.ndarray:
-    """Calculates a masked maximum of a window
+    """Calculates a masked minimum of a window
 
     Args:
         values: 1d np.ndarray of values
-        window: window size
+        window: number of frames to include on each side of the center frame. The
+            window used for each output value spans ``2 * window + 1`` frames.
 
     Returns:
-        sliding window maximum values
+        sliding window minimum values
     """
     window_values = pad_sliding_window(values, window, pad_const=np.nan)
     window_masks = get_window_masks(window_values, np.nan)
@@ -186,7 +214,8 @@ def window_max(values: np.ndarray, window: int) -> np.ndarray:
 
     Args:
         values: 1d np.ndarray of values
-        window: window size
+        window: number of frames to include on each side of the center frame. The
+            window used for each output value spans ``2 * window + 1`` frames.
 
     Returns:
         sliding window maximum values

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/src/jabs/pose_estimation/__init__.py

@@ -63,20 +63,32 @@ def get_pose_path(video_path: Path, pose_dir: Path | None = None):
     raise ValueError("Video does not have pose file")
 
 
-def get_pose_file_major_version(path: Path):
+# matches the version suffix of a pose file name, e.g. "_v6.h5" in
+# "video_pose_est_v6.h5". Anchored at the end so only the filename's suffix can
+# supply the version.
+_POSE_VERSION_RE = re.compile(r"_v(\d+)\.h5$")
+
+
+def get_pose_file_major_version(path: Path) -> int:
     """get the major version of a pose file from the _filename_
 
-    Note: does not inspect contents of file, assumes file name matches
-    video_name_v[version number].h5
+    Note: does not inspect contents of file, assumes the file name follows the
+    JABS convention ``<video name>_pose_est_v<major version>.h5``.
 
     Args:
         path: path of pose file
 
     Returns:
         integer major version number
+
+    Raises:
+        ValueError: if the file name does not end with a ``_v<major version>.h5``
+            suffix
     """
-    v = re.search(r"_v([0-9])+\.h5", str(path)).group(1)
-    return int(v)
+    match = _POSE_VERSION_RE.search(path.name)
+    if match is None:
+        raise ValueError(f"'{path.name}' is not a valid pose file name")
+    return int(match.group(1))
 
 
 def get_frames_from_file(path: Path):

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/src/jabs/pose_estimation/pose_est_v4.py

@@ -87,10 +87,16 @@ class PoseEstimationV4(PoseEstimation):
 
                 self._num_frames = len(all_points)
 
-                max_instance_id = (
-                    np.max(np.ma.array(instance_embed_id[...], mask=id_mask[...]))
+                valid_instance_embed_id = (
+                    instance_embed_id[id_mask == 0]
                     if instance_embed_id.shape[1] > 0
-                    else 0
+                    else np.array([], dtype=instance_embed_id.dtype)
+                )
+                max_instance_id = (
+                    valid_instance_embed_id.max() if valid_instance_embed_id.size > 0 else 0
+                )
+                min_instance_id = (
+                    valid_instance_embed_id.min() if valid_instance_embed_id.size > 0 else 1
                 )
 
                 if "instance_id_center" in pose_grp:
@@ -101,12 +107,21 @@ class PoseEstimationV4(PoseEstimation):
                     print(f"Warning: No identities found in pose file: {file_path}")
                     self._num_identities = 0
 
-            # Validate instance_embed_id range: must be in [0, self._num_identities]
+            # Validate instance_embed_id range for unmasked (id_mask == 0) data:
+            # must be in [1, self._num_identities].
             if max_instance_id > self._num_identities:
                 raise PoseIdEmbeddingException(
                     f"Invalid instance_embed_id, values out of range: {file_path.name}"
                 )
 
+            # instance_embed_id values are 1-based; a value of 0 on unmasked
+            # data would wrap around to a large positive index when we
+            # subtract 1 to build a 0-based identity index below.
+            if min_instance_id < 1:
+                raise PoseIdEmbeddingException(
+                    f"Invalid instance_embed_id, unmasked values must be >= 1: {file_path.name}"
+                )
+
             # generate list of identities based on the max number of instances
             # in the pose file
             if self._num_identities > 0:

{jabs_behavior_classifier-0.46.2 → jabs_behavior_classifier-0.46.3}/src/jabs/project/__init__.py

@@ -1,6 +1,12 @@
 """jabs project module"""
 
 from .export_training import export_training_data, export_training_data_multiclass
+from .feature_cache_status import (
+    VideoFeatureCacheStatus,
+    scan_project_feature_cache,
+    scan_project_video_feature_cache,
+    scan_video_feature_cache,
+)
 from .project import Project
 from .project_pruning import get_videos_to_prune
 from .read_training import load_multiclass_training_data, load_training_data
@@ -12,10 +18,14 @@ __all__ = [
     "Project",
     "TimelineAnnotations",
     "TrackLabels",
+    "VideoFeatureCacheStatus",
     "VideoLabels",
     "export_training_data",
     "export_training_data_multiclass",
     "get_videos_to_prune",
     "load_multiclass_training_data",
     "load_training_data",
+    "scan_project_feature_cache",
+    "scan_project_video_feature_cache",
+    "scan_video_feature_cache",
 ]