simba-uw-tf-dev 5.3.9__tar.gz → 5.4.1__tar.gz

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: simba_uw_tf_dev
-Version: 5.3.9
+Version: 5.4.1
 Summary: Toolkit for computer classification and analysis of behaviors in experimental animals
 Home-page: https://github.com/sgoldenlab/simba
 Author: Simon Nilsson, Jia Jie Choong, Sophia Hwang

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/setup.py

@@ -30,7 +30,7 @@ with open(GPU_REQUIREMENTS_PATH, "r") as f:
 # Setup configuration
 setuptools.setup(
     name="simba_uw_tf_dev",
-    version="5.3.9",
+    version="5.4.1",
     author="Simon Nilsson, Jia Jie Choong, Sophia Hwang",
     author_email="sronilsson@gmail.com",
     description="Toolkit for computer classification and analysis of behaviors in experimental animals",

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/simba/assets/.recent_projects.txt

@@ -1,3 +1,5 @@
+G:/projects/sleap_bp_order/by_order/project_folder/project_config.ini
+H:/projects/brainwide_trap/brainwide_trap/project_folder/project_config.ini
 D:/troubleshooting/open_field_below/project_folder/project_config.ini
 G:/projects/jason_zhang/jason_project/project_folder/project_config.ini
 G:/projects/edmayelle/superanimal_multianimal_project/project_folder/project_config.ini

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/simba/data_processors/freezing_detector.py

@@ -28,6 +28,11 @@ class FreezingDetector(ConfigReader):
     of key body parts (nape, nose, and tail-base) and identifying periods where movement falls below
     a specified threshold for a minimum duration.
 
+    .. seealso::
+       :class:`~simba.data_processors.freezing_detector_v2.FreezingDetector` - revised version, adding an explicit
+       FREEZING / IMMOBILITY split and millisecond-based duration parameters (``min_freezing_ms``, ``clean_ms``,
+       ``min_immobility_ms``).
+
 
     .. video:: _static/img/FreezingDetector.webm
        :width: 1000

simba_uw_tf_dev-5.4.1/simba/data_processors/freezing_detector_v2.py

@@ -0,0 +1,237 @@
+import os
+from typing import Optional, Union
+
+import numpy as np
+import pandas as pd
+from numba import typed
+
+from simba.mixins.config_reader import ConfigReader
+from simba.mixins.feature_extraction_mixin import FeatureExtractionMixin
+from simba.mixins.timeseries_features_mixin import TimeseriesFeatureMixin
+from simba.utils.checks import (
+    check_all_file_names_are_represented_in_video_log, check_if_dir_exists,
+    check_int, check_str, check_valid_dataframe)
+from simba.utils.data import detect_bouts, plug_holes_shortest_bout
+from simba.utils.enums import Formats
+from simba.utils.errors import InvalidInputError
+from simba.utils.printing import stdout_success
+from simba.utils.read_write import (find_files_of_filetypes_in_directory,
+                                    get_current_time, get_fn_ext, read_df,
+                                    read_video_info)
+
+NAPE_X, NAPE_Y = 'nape_x', 'nape_y'
+FREEZING = 'FREEZING'
+IMMOBILITY = 'IMMOBILITY'
+
+class FreezingDetector(ConfigReader):
+    """
+    Detect freezing behavior using heuristic rules based on movement velocity thresholds.
+    Analyzes pose-estimation data to detect freezing episodes by computing the mean velocity
+    of key body parts (nape, nose, and tail-base) and identifying periods where movement falls below
+    a specified threshold for a minimum duration.
+
+    .. seealso::
+       :class:`~simba.data_processors.freezing_detector.FreezingDetector` - the original version, with
+       ``time_window`` / ``shortest_bout`` parameters and freezing-only output.
+
+
+    .. video:: _static/img/FreezingDetector.webm
+       :width: 1000
+       :autoplay:
+       :loop:
+       :muted:
+       :align: center
+
+    .. video:: _static/img/FreezingDetector_2.webm
+       :width: 1000
+       :autoplay:
+       :loop:
+       :muted:
+       :align: center
+
+    .. image:: _static/img/FreezingDetector_pipeline.png
+       :width: 1000
+       :align: center
+
+    .. note::
+       The method uses the left and right ear body-parts to compute the `nape` location of the animal
+       as the midpoint between the ears. The nape, nose, and tail-base movements are averaged to compute
+       overall animal movement velocity.
+
+    :param Union[str, os.PathLike] data_dir: Path to directory containing pose-estimated body-part data in CSV format. Each CSV file should contain pose estimation data for one video.
+    :param Union[str, os.PathLike] config_path: Path to SimBA project config file (`.ini` format) containing project settings and video information.
+    :param Optional[str] nose_name: The name of the pose-estimated nose body-part column (without _x/_y suffix). Defaults to 'nose'.
+    :param Optional[str] left_ear_name: The name of the pose-estimated left ear body-part column (without _x/_y suffix). Defaults to 'Left_ear'.
+    :param Optional[str] right_ear_name: The name of the pose-estimated right ear body-part column (without _x/_y suffix). Defaults to 'right_ear'.
+    :param Optional[str] tail_base_name: The name of the pose-estimated tail base body-part column (without _x/_y suffix). Defaults to 'tail_base'.
+    :param Optional[int] min_freezing_ms: Minimum duration in milliseconds of sustained low movement to be scored as freezing. Shorter bouts are ignored. This is the lower edge of the freezing band. Defaults to 2000.
+    :param Optional[int] movement_threshold: Movement threshold in millimeters per second. Frames with mean velocity below this threshold are considered potential freezing. Higher and more freezing will be detected. Lower and less freezing will be detected. Defaults to 5.
+    :param Optional[int] clean_ms: De-noising window in milliseconds. Brief sub-threshold movement interruptions shorter than this are bridged (so jitter does not split one freeze into two), and stray bouts shorter than this are dropped, before the duration tests. Keep small relative to ``min_freezing_ms``. Defaults to 100.
+    :param Optional[int] min_immobility_ms: Minimum duration in milliseconds at which sustained freezing is instead scored as immobility. Bouts at least this long are flagged in an `IMMOBILITY` column (1 = immobility, 0 = not) and removed from `FREEZING` (the two are mutually exclusive), with extra aggregate statistics; bouts between ``min_freezing_ms`` and this remain freezing. Must be greater than or equal to ``min_freezing_ms`` (when equal, there is no freezing band and every sustained bout is immobility). If None, no immobility is computed and every bout at least ``min_freezing_ms`` long is freezing. Defaults to None.
+    :param Optional[Union[str, os.PathLike]] save_dir: Directory where to store the results. If None, then results are stored in a timestamped subdirectory within the ``logs`` directory of the SimBA project.
+    :returns: None. Results are saved to CSV files in the specified save directory:
+        - Individual video results: One CSV file per video with freezing annotations added as a 'FREEZING' column (1 = freezing, 0 = not freezing)
+        - Aggregate results: `aggregate_freezing_results.csv` containing summary statistics for all videos
+
+    :example:
+    >>> x = FreezingDetector(data_dir=r'D:\\troubleshooting\\mitra\\project_folder\\csv\\outlier_corrected_movement_location', config_path=r"D:\\troubleshooting\\mitra\\project_folder\\project_config.ini", min_freezing_ms=1500, movement_threshold=5, min_immobility_ms=2000)
+    >>> x.run()
+
+    references
+    ----------
+    ..
+    .. [1] Sabnis et al., Visual detection of seizures in mice using supervised machine learning, `biorxiv`, doi: https://doi.org/10.1101/2024.05.29.596520.
+    .. [2] Lopez et al., Region-specific Nucleus Accumbens Dopamine Signals Encode Distinct Aspects of Avoidance Learning, `biorxiv`, doi: https://doi.org/10.1101/2024.08.28.610149
+    .. [3] Lopez, Gabriela C., Louis D. Van Camp, Ryan F. Kovaleski, et al. "Region-Specific Nucleus Accumbens Dopamine Signals Encode Distinct Aspects of Avoidance Learning." `Cell Biology`, Volume 35, Issue 10p2433-2443.e5May 19, 2025. DOI: 10.1016/j.cub.2025.04.006
+    .. [4] Lazaro et al., Brainwide Genetic Capture for Conscious State Transitions, `biorxiv`, doi: https://doi.org/10.1101/2025.03.28.646066
+    .. [5] Sabnis et al., Visual detection of seizures in mice using supervised machine learning, 2025, Cell Reports Methods 5, 101242 December 15, 2025.
+    """
+
+    def __init__(self,
+                 config_path: Union[str, os.PathLike],
+                 nose_name: str = 'nose',
+                 left_ear_name: str = 'left_ear',
+                 right_ear_name: str = 'right_ear',
+                 tail_base_name: str = 'tail_base',
+                 data_dir: Optional[Union[str, os.PathLike]] = None,
+                 min_freezing_ms: int = 2000,
+                 movement_threshold: int = 5,
+                 clean_ms: int = 100,
+                 min_immobility_ms: Optional[int] = None,
+                 save_dir: Optional[Union[str, os.PathLike]] = None):
+
+        for bp_name in [nose_name, left_ear_name, right_ear_name, tail_base_name]: check_str(name='body part name', value=bp_name, allow_blank=False)
+        ConfigReader.__init__(self, config_path=config_path, read_video_info=True, create_logger=False)
+        if data_dir is not None:
+            check_if_dir_exists(in_dir=data_dir)
+        else:
+            data_dir = self.outlier_corrected_dir
+        self.data_paths = find_files_of_filetypes_in_directory(directory=data_dir, extensions=['.csv'])
+        self.nose_heads = [f'{nose_name}_x'.lower(), f'{nose_name}_y'.lower()]
+        self.left_ear_heads = [f'{left_ear_name}_x'.lower(), f'{left_ear_name}_y'.lower()]
+        self.right_ear_heads = [f'{right_ear_name}_x'.lower(), f'{right_ear_name}_y'.lower()]
+        self.tail_base_heads = [f'{tail_base_name}_x'.lower(), f'{tail_base_name}_y'.lower()]
+        self.required_field = self.nose_heads + self.left_ear_heads + self.right_ear_heads + self.tail_base_heads
+        check_int(name='min_freezing_ms', value=min_freezing_ms, min_value=1)
+        check_int(name='movement_threshold', value=movement_threshold, min_value=1)
+        check_int(name='clean_ms', value=clean_ms, min_value=1)
+        if min_immobility_ms is not None:
+            check_int(name='min_immobility_ms', value=min_immobility_ms, min_value=1)
+            if int(min_immobility_ms) < int(min_freezing_ms):
+                raise InvalidInputError(msg=f'min_immobility_ms ({min_immobility_ms} ms) must be greater than or equal to min_freezing_ms ({min_freezing_ms} ms). At equal values there is no freezing band and every sustained bout is immobility.', source=self.__class__.__name__)
+        self.min_immobility_ms = min_immobility_ms
+        self.save_dir = save_dir
+        if self.save_dir is None:
+            self.save_dir = os.path.join(self.logs_path, f'freezing_data_minfreeze_{min_freezing_ms}ms_{movement_threshold}mm_{self.datetime}')
+            os.makedirs(self.save_dir)
+        else:
+            check_if_dir_exists(in_dir=self.save_dir)
+        self.min_freezing_ms, self.movement_threshold, self.clean_ms = min_freezing_ms, movement_threshold, clean_ms
+    def run(self):
+        freezing_cols = ['VIDEO', 'FREEZING FRAMES', 'FREEZING TIME (S)', 'FREEZING BOUT COUNTS', 'FREEZING PCT OF SESSION']
+        immobility_cols = ['IMMOBILITY FRAMES', 'IMMOBILITY TIME (S)', 'IMMOBILITY BOUT COUNTS', 'IMMOBILITY PCT OF SESSION'] if self.min_immobility_ms is not None else []
+        video_cols = ['VIDEO TOTAL FRAMES', 'VIDEO TOTAL TIME (S)']
+        agg_results = pd.DataFrame(columns=freezing_cols + immobility_cols + video_cols)
+        agg_results_path = os.path.join(self.save_dir, f'aggregate_freezing_results_{self.datetime}.csv')
+        check_all_file_names_are_represented_in_video_log(video_info_df=self.video_info_df, data_paths=self.data_paths)
+        for file_cnt, file_path in enumerate(self.data_paths):
+            video_name = get_fn_ext(filepath=file_path)[1]
+            print(f'[{get_current_time()}] Analyzing freezing {video_name}...(video {file_cnt+1}/{len(self.data_paths)})')
+            save_file_path = os.path.join(self.save_dir, f'{video_name}.csv')
+            df = read_df(file_path=file_path, file_type='csv').reset_index(drop=True)
+            _, px_per_mm, fps = read_video_info(vid_info_df=self.video_info_df, video_name=video_name)
+            df.columns = [str(x).lower() for x in df.columns]
+            check_valid_dataframe(df=df, valid_dtypes=Formats.NUMERIC_DTYPES.value, required_fields=self.required_field)
+            nose_shifted = FeatureExtractionMixin.create_shifted_df(df[self.nose_heads])
+            nose_1, nose_2 = nose_shifted.iloc[:, 0:2].values, nose_shifted.iloc[:, 2:4].values
+            nose_movement = FeatureExtractionMixin.euclidean_distance(bp_1_x=nose_1[:, 0].flatten(), bp_2_x=nose_2[:, 0].flatten(), bp_1_y=nose_1[:, 1].flatten(), bp_2_y=nose_2[:, 1].flatten(), px_per_mm=px_per_mm)
+            tail_base_shifted = FeatureExtractionMixin.create_shifted_df(df[self.tail_base_heads])
+            tail_base_shifted_1, tail_base_shifted_2 = tail_base_shifted.iloc[:, 0:2].values, tail_base_shifted.iloc[:, 2:4].values
+            tail_base_movement = FeatureExtractionMixin.euclidean_distance(bp_1_x=tail_base_shifted_1[:, 0].flatten(), bp_2_x=tail_base_shifted_2[:, 0].flatten(), bp_1_y=tail_base_shifted_1[:, 1].flatten(), bp_2_y=tail_base_shifted_2[:, 1].flatten(), px_per_mm=px_per_mm)
+            left_ear_arr = df[self.left_ear_heads].values.astype(np.int64)
+            right_ear_arr = df[self.right_ear_heads].values.astype(np.int64)
+            nape_arr = pd.DataFrame(FeatureExtractionMixin.find_midpoints(bp_1=left_ear_arr, bp_2=right_ear_arr, percentile=np.float64(0.5)), columns=[NAPE_X, NAPE_Y])
+            nape_shifted = FeatureExtractionMixin.create_shifted_df(nape_arr[[NAPE_X, NAPE_Y]])
+            nape_shifted_1, nape_shifted_2 = nape_shifted.iloc[:, 0:2].values, nape_shifted.iloc[:, 2:4].values
+            nape_movement = FeatureExtractionMixin.euclidean_distance(bp_1_x=nape_shifted_1[:, 0].flatten(), bp_2_x=nape_shifted_2[:, 0].flatten(), bp_1_y=nape_shifted_1[:, 1].flatten(),  bp_2_y=nape_shifted_2[:, 1].flatten(), px_per_mm=px_per_mm)
+            movement = np.hstack([nose_movement.reshape(-1, 1), nape_movement.reshape(-1, 1), tail_base_movement.reshape(-1, 1)])
+            mean_movement = np.mean(movement, axis=1)
+            mm_s = TimeseriesFeatureMixin.sliding_descriptive_statistics(data=mean_movement.astype(np.float32), window_sizes=np.array([1], dtype=np.float64), sample_rate=int(fps), statistics=typed.List(["sum"]))[0].flatten()
+            freezing_idx = np.argwhere((mm_s >= 0) & (mm_s <= self.movement_threshold)).astype(np.int32).flatten()
+            df[f'Probability_{FREEZING}'] = 0
+            df[FREEZING] = 0
+            df.loc[freezing_idx, FREEZING] = 1
+            df = plug_holes_shortest_bout(data_df=df, clf_name=FREEZING, fps=fps, shortest_bout=self.clean_ms)
+            bouts = detect_bouts(data_df=df, target_lst=[FREEZING], fps=fps)
+            bouts = bouts[bouts['Bout_time'] >= (self.min_freezing_ms / 1000)]
+            if self.min_immobility_ms is not None:
+                immobility_bouts = bouts[bouts['Bout_time'] >= (self.min_immobility_ms / 1000)]
+                bouts = bouts[bouts['Bout_time'] < (self.min_immobility_ms / 1000)]
+            if len(bouts) > 0:
+                df[FREEZING] = 0
+                freezing_idx = list(bouts.apply(lambda x: list(range(int(x["Start_frame"]), int(x["End_frame"]) + 1)), 1))
+                freezing_idx = [x for xs in freezing_idx for x in xs]
+                df.loc[freezing_idx, FREEZING] = 1
+                df.loc[freezing_idx, f'Probability_{FREEZING}'] = 1
+            else:
+                df[FREEZING] = 0
+                freezing_idx = []
+            if self.min_immobility_ms is not None:
+                df[f'Probability_{IMMOBILITY}'] = 0
+                df[IMMOBILITY] = 0
+                if len(immobility_bouts) > 0:
+                    immobility_idx = list(immobility_bouts.apply(lambda x: list(range(int(x["Start_frame"]), int(x["End_frame"]) + 1)), 1))
+                    immobility_idx = [x for xs in immobility_idx for x in xs]
+                    df.loc[immobility_idx, IMMOBILITY] = 1
+                    df.loc[immobility_idx, f'Probability_{IMMOBILITY}'] = 1
+                else:
+                    immobility_idx = []
+            df.to_csv(save_file_path)
+            agg_row = [video_name, len(freezing_idx), round(len(freezing_idx) / fps, 4), len(bouts), round((len(freezing_idx) / len(df)) * 100, 4)]
+            if self.min_immobility_ms is not None:
+                agg_row += [len(immobility_idx), round(len(immobility_idx) / fps, 4), len(immobility_bouts), round((len(immobility_idx) / len(df)) * 100, 4)]
+            agg_row += [len(df), round(len(df)/fps, 2)]
+            agg_results.loc[len(agg_results)] = agg_row
+        agg_results.to_csv(agg_results_path)
+        self.timer.stop_timer(); stdout_success(msg=f'Results saved in {self.save_dir} directory.', elapsed_time=self.timer.elapsed_time_str)
+
+
+
+# FreezingDetector(
+#     data_dir=r'H:\projects\brainwide_trap\brainwide_trap\project_folder\csv\outlier_corrected_movement_location',
+#     config_path=r"H:\projects\brainwide_trap\brainwide_trap\project_folder\project_config.ini",
+#     movement_threshold=3,
+#     clean_ms=100,            # bridge jitter / drop blips shorter than this
+#     min_freezing_ms=3000,    # freezing = stillness >= 3.0 s ...
+#     min_immobility_ms=4500,  # ... until >= 6.0 s, where it becomes immobility (None = no immobility)
+# ).run()
+
+
+#
+# FreezingDetector(
+#     data_dir=r'G:\projects\jason_zhang\jason_project\project_folder\csv\outlier_corrected_movement_location',
+#     config_path=r"G:\projects\jason_zhang\jason_project\project_folder\project_config.ini",
+#     time_window=3,
+#     movement_threshold=3,
+#     shortest_bout=100
+# ).run()
+
+
+
+# FreezingDetector(
+#     data_dir=r'F:\troubleshooting\sam\sam\project_folder\csv\outlier_corrected_movement_location',
+#     config_path=r"F:\troubleshooting\sam\sam\project_folder\project_config.ini",
+#     save_dir=r'F:\troubleshooting\sam\sam\project_folder\logs\freezing_500',
+#     time_window=3,
+#     movement_threshold=5,
+#     shortest_bout=100
+# ).run()
+
+
+# FreezingDetector(
+#     data_dir=r'E:\troubleshooting\mitra_emergence_hour\project_folder\csv\outlier_corrected_movement_location',
+#     config_path=r"E:\troubleshooting\mitra_emergence_hour\project_folder\project_config.ini",
+#     time_window=3,
+#     movement_threshold=5,
+#     shortest_bout=100
+# ).run()

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/simba/feature_extractors/mitra_feature_extractor.py

@@ -22,14 +22,14 @@ from simba.utils.read_write import (SimbaTimer, get_fn_ext, read_df,
                                     write_df)
 
 NOSE = 'nose'
-LEFT_SIDE = 'lat_left'
-RIGHT_SIDE = 'lat_right'
+LEFT_SIDE = 'left_side'
+RIGHT_SIDE = 'right_side'
 LEFT_EAR = 'left_ear'
 RIGHT_EAR = 'right_ear'
 CENTER = 'center'
 TAIL_BASE = 'tail_base'
 TAIL_CENTER = 'tail_center'
-TAIL_TIP = 'tail_end'
+TAIL_TIP = 'tail_tip'
 
 TIME_WINDOWS = np.array([0.25, 0.5, 1.0, 2.0])
 
@@ -231,8 +231,8 @@ class MitraFeatureExtractor(ConfigReader,
 #     feature_extractor = MitraFeatureExtractor(config_path=args.config_path)
 #     feature_extractor.run()
 #
-# feature_extractor = MitraFeatureExtractor(config_path=r"G:\projects\jason_zhang\jason_project\project_folder\project_config.ini")
-# feature_extractor.run()
+feature_extractor = MitraFeatureExtractor(config_path=r"H:\projects\brainwide_trap\brainwide_trap\project_folder\project_config.ini")
+feature_extractor.run()
 
 
 # feature_extractor = MitraFeatureExtractor(config_path=r"E:\troubleshooting\mitra_pbn\mitra_pbn\project_folder\project_config.ini")
@@ -245,3 +245,4 @@ class MitraFeatureExtractor(ConfigReader,
 
 
 
+

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/simba/labelling/labelling_interface.py

@@ -26,8 +26,8 @@ from simba.mixins.config_reader import ConfigReader
 from simba.ui.tkinter_functions import (CreateLabelFrameWithIcon, Entry_Box,
                                         SimbaButton, SimbaCheckbox, SimBALabel)
 from simba.utils.checks import (check_file_exist_and_readable, check_float,
-                                check_int, check_str, check_valid_boolean, check_valid_dataframe,
-                                check_valid_dict)
+                                check_int, check_str, check_valid_boolean,
+                                check_valid_dataframe, check_valid_dict)
 from simba.utils.enums import ConfigKey, Dtypes, Formats, Options, TagNames
 from simba.utils.errors import FrameRangeError, NoDataError, NoFilesFoundError
 from simba.utils.lookups import (get_current_time, get_display_resolution,

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/simba/labelling/standard_labeller.py

@@ -21,13 +21,17 @@ except ImportError:
 
 import simba
 from simba.mixins.config_reader import ConfigReader
+from simba.mixins.plotting_mixin import PlottingMixin
 from simba.ui.tkinter_functions import (CreateLabelFrameWithIcon, Entry_Box,
-                                        SimbaButton, SimbaCheckbox, SimBALabel, get_menu_icons, SimBAScaleBar)
+                                        SimbaButton, SimbaCheckbox,
+                                        SimBADropDown, SimBALabel,
+                                        SimBAScaleBar, get_menu_icons)
 from simba.utils.checks import (check_file_exist_and_readable, check_int,
                                 check_that_column_exist, check_valid_boolean,
                                 check_valid_dataframe, check_valid_dict,
-                                check_video_and_data_frm_count_align)
-from simba.utils.enums import Formats, TagNames
+                                check_video_and_data_frm_count_align,
+                                is_img_greyscale)
+from simba.utils.enums import Formats, TagNames, TextOptions
 from simba.utils.errors import (FrameRangeError, NoDataError,
                                 NoFilesFoundError, SimbaError)
 from simba.utils.lookups import (get_current_time, get_display_resolution,
@@ -37,7 +41,8 @@ from simba.utils.lookups import (get_current_time, get_display_resolution,
 from simba.utils.printing import log_event, stdout_success
 from simba.utils.read_write import (find_closest_readable_frame,
                                     get_video_meta_data, read_config_entry,
-                                    read_df, read_frm_of_video, write_df)
+                                    read_df, read_frm_of_video,
+                                    seconds_to_timestamp, str_2_bool, write_df)
 from simba.utils.warnings import DataHeaderWarning, FrameRangeWarning
 
 PLAY_VIDEO_SCRIPT_PATH = os.path.join(os.path.dirname(simba.__file__), "labelling/play_annotation_video.py")
@@ -45,6 +50,8 @@ PADDING = 5
 
 DISPLAY_RESOLUTION = get_display_resolution()
 MAX_FRAME_RATI0 = (0.6, 0.6) # W * H RATIO OF IMAGE FRAME ONLY
+DEFAULT_IMG_GREYSCALE = 'FALSE'
+DEFAULT_SAVE_VERBOSITY = 'TRUE'
 
 
 class LabellingInterface(ConfigReader):
@@ -87,6 +94,8 @@ class LabellingInterface(ConfigReader):
         self.targets_inserted_file_path = os.path.join(self.targets_folder, f"{self.video_name}.{self.file_type}")
         self.machine_results_file_path = os.path.join(self.machine_results_dir, f"{self.video_name}.{self.file_type}")
         self.cap = cv2.VideoCapture(self.video_path)
+        self.img_greyscale, self.save_verbosity = str_2_bool(input_str=DEFAULT_IMG_GREYSCALE), str_2_bool(input_str=DEFAULT_SAVE_VERBOSITY)
+        self.show_video_timer = False
         self.img_kbd_bindings = get_labelling_img_kbd_bindings()
         self.video_kbd_bindings = get_labelling_video_kbd_bindings()
         self.max_frm_id = self.video_meta_data["frame_count"] - 1
@@ -157,7 +166,7 @@ class LabellingInterface(ConfigReader):
         self.img_lbl = Label(self.img_frm, name='img_lbl')
         self.img_frm.grid(row=0, column=0, sticky=NW, padx=10, pady=10, columnspan=3, rowspan=2)
         self.img_lbl.grid(row=0, column=0, sticky=NW)
-
+        self.font_size, self.space_x, self.spacing_scale = PlottingMixin().get_optimal_font_scales(text='999999', accepted_px_width=int(self.img_display_size[0] / 8), accepted_px_height=int(self.img_display_size[1] / 8))
 
         self.navigation_frm = CreateLabelFrameWithIcon(parent=self.main_window, header='FRAME NAVIGATION',  icon_name='navigation', relief='solid')
         self.current_frm_eb = Entry_Box(parent=self.navigation_frm, fileDescription='CURRENT FRAME: ', labelwidth=20, validation='numeric', entry_box_width=10, value=self.img_idx, justify='center', label_font=Formats.FONT_HEADER.value, entry_font=Formats.FONT_HEADER.value)
@@ -167,7 +176,7 @@ class LabellingInterface(ConfigReader):
         self.forward_btn = SimbaButton(parent=self.navigation_frm, txt="", img='play_large_green', tooltip_txt="+1 FRAME", cmd=self.__advance_frame, cmd_kwargs={'frm_id': lambda: self.img_idx + 1})
         self.last_frm_btn = SimbaButton(parent=self.navigation_frm, txt="", img='skip_forward_large', tooltip_txt="GO TO LAST FRAME", cmd=self.__advance_frame, cmd_kwargs={'frm_id': self.max_frm_id})
 
-        self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=self.img_idx, display_size=self.img_display_size)
+        self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=self.img_idx, display_size=self.img_display_size, show_timer=self.show_video_timer)
 
         self.navigation_frm.grid(row=2, column=0, sticky=NSEW, pady=10, padx=10, columnspan=1)
         self.current_frm_eb.grid(row=0, column=0, sticky=EW, columnspan=4)
@@ -285,9 +294,9 @@ class LabellingInterface(ConfigReader):
                 img_lbl: Label,
                 video_path: Union[str, os.PathLike],
                 img_idx: int,
-                display_size: Optional[Tuple[int, int]] = None):
-
-        self.img = read_frm_of_video(video_path=video_path, frame_index=img_idx, size=display_size, raise_error=False)
+                display_size: Optional[Tuple[int, int]] = None,
+                show_timer: bool = False):
+        self.img = read_frm_of_video(video_path=video_path, frame_index=img_idx, size=display_size, raise_error=False, greyscale=self.img_greyscale)
         if self.img is None:
             FrameRangeWarning(msg=f'Frame {img_idx} could not be read in video {video_path}. Attempting to find closest readable frame...')
             img, img_idx = find_closest_readable_frame(video_path=video_path, target_frame=img_idx, max_search_range=50)
@@ -298,7 +307,11 @@ class LabellingInterface(ConfigReader):
                 self.current_frm_eb.entry_set(val=str(img_idx))
             else:
                 raise FrameRangeError(msg=f'Could not find a readable frame (± frames of {img_idx}) in video {video_path}. Cannot proceed with annotations in this video.', source=self.__class__.__name__)
-        img_rgb = cv2.cvtColor(self.img, cv2.COLOR_BGR2RGB)
+        if show_timer:
+            timestamp = seconds_to_timestamp(seconds=self.img_idx / self.video_meta_data['fps'], hh_mm_ss_sss=True)
+            self.img = PlottingMixin().put_text(img=self.img, text=timestamp, pos=(TextOptions.BORDER_BUFFER_X.value, int((self.img.shape[0] - self.spacing_scale * 2))), font_size=self.font_size, font_thickness=TextOptions.TEXT_THICKNESS.value + 1, text_bg_alpha=0.6, text_color=(255, 255, 255))
+        grey_img = is_img_greyscale(img=self.img, raise_error=False, source=f'{self.__class__.__name__} img_idx')
+        img_rgb = cv2.cvtColor(self.img, cv2.COLOR_BGR2RGB) if not grey_img else self.img
         self.pil_image = Image.fromarray(img_rgb)
         self.tk_image = ImageTk.PhotoImage(self.pil_image)
         img_lbl.configure(image=self.tk_image)
@@ -343,7 +356,8 @@ class LabellingInterface(ConfigReader):
             raise FrameRangeError(msg=f"TRYING TO SHOW FRAME {frm_id} WHICH CANNOT BE SHOWN. FRAME INDEX HAS TO BE 0 OR ABOVE")
         else:
             prior_frm_idx = int(self.current_frm_eb.entry_get)
-            self.__create_print_statements(frame=prior_frm_idx)
+            if self.save_verbosity:
+                self.__create_print_statements(frame=prior_frm_idx)
             self.current_frm_eb.entry_set(val=frm_id)
             for clf in self.clf_names:
                 self.save_behavior_in_frm(clf_name=clf, frame_idx=prior_frm_idx)
@@ -352,7 +366,7 @@ class LabellingInterface(ConfigReader):
                 else:
                     self.clf_cbs[clf].set(bool(self.data_df_targets[clf].loc[frm_id]))
             self.img_idx = deepcopy(frm_id)
-            self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=frm_id, display_size=self.img_display_size)
+            self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=frm_id, display_size=self.img_display_size, show_timer=self.show_video_timer)
 
     def __save_behavior_in_range(self,
                                  start_frm: int,
@@ -367,8 +381,9 @@ class LabellingInterface(ConfigReader):
             self.data_df_targets[target].loc[start_frm:end_frm] = int(self.clf_cbs[target].get())
         self.current_frm_eb.entry_set(end_frm)
         self.img_idx = deepcopy(end_frm)
-        self.__create_print_statements(frame=(start_frm, end_frm))
-        self.main_window.after(1, lambda: self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=end_frm, display_size=self.img_display_size))
+        if self.save_verbosity:
+            self.__create_print_statements(frame=(start_frm, end_frm))
+        self.main_window.after(1, lambda: self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=end_frm, display_size=self.img_display_size, show_timer=self.show_video_timer))
 
     def save_behavior_in_frm(self,
                              frame_idx: int,
@@ -421,7 +436,6 @@ class LabellingInterface(ConfigReader):
         self.preferences_frm.minsize(400, 300)
         self.preferences_frm.wm_title("PREFERENCES")
         self.preferences_frm.iconphoto(False, self.menu_icons['settings']["img"])
-
         size_frm_panel = CreateLabelFrameWithIcon(parent=self.preferences_frm, header="IMAGE SIZE", icon_name='size', padx=5, pady=5)
         size_frm_panel.grid(row=0, column=0, sticky="NW")
         self.max_width_scaler = SimBAScaleBar(parent=size_frm_panel, label="MAX IMAGE WIDTH (%): ", orient=HORIZONTAL, length=200, value=MAX_FRAME_RATI0[0]*100, label_width=25, lbl_img='width', from_=10, to=100)
@@ -429,15 +443,33 @@ class LabellingInterface(ConfigReader):
         self.max_width_scaler.grid(row=0, column=0, sticky="NW")
         self.max_height_scaler.grid(row=1, column=0, sticky="NW")
 
+        img_clr_panel = CreateLabelFrameWithIcon(parent=self.preferences_frm, header="IMAGE COLOR", icon_name='size', padx=5, pady=5)
+        img_clr_panel.grid(row=1, column=0, sticky="NW")
+        self.img_grey_dropdown = SimBADropDown(parent=img_clr_panel, dropdown_options=['TRUE', 'FALSE'], label="IMAGE GREYSCALE: ", label_width=20, value='TRUE' if self.img_greyscale else 'FALSE', dropdown_width=10, img='grey')
+        self.img_grey_dropdown.grid(row=0, column=0, sticky="NW")
+
+        verbosity_panel = CreateLabelFrameWithIcon(parent=self.preferences_frm, header="VEBOSITY", icon_name='verbose', padx=5, pady=5)
+        verbosity_panel.grid(row=2, column=0, sticky="NW")
+        self.verbosity_dropdown = SimBADropDown(parent=verbosity_panel, dropdown_options=['TRUE', 'FALSE'], label="SAVE VERBOSITY: ", label_width=20, value='TRUE' if self.save_verbosity else 'FALSE', dropdown_width=10, img='verbose')
+        self.verbosity_dropdown.grid(row=0, column=0, sticky="NW")
+
+        video_timer_panel = CreateLabelFrameWithIcon(parent=self.preferences_frm, header="VIDEO TIMER", icon_name='frame', padx=5, pady=5)
+        video_timer_panel.grid(row=3, column=0, sticky="NW")
+        self.video_timer_dropdown = SimBADropDown(parent=video_timer_panel, dropdown_options=['TRUE', 'FALSE'], label="SHOW VIDEO TIMER: ", label_width=20, value='TRUE' if self.show_video_timer else 'FALSE', dropdown_width=10, img='timer')
+        self.video_timer_dropdown.grid(row=0, column=0, sticky="NW")
+
         pref_save_btn = SimbaButton(parent=self.preferences_frm, txt="SAVE", img='save_large', font=Formats.FONT_REGULAR.value, cmd=self.set_settings)
-        pref_save_btn.grid(row=1, column=0, sticky="NW")
+        pref_save_btn.grid(row=4, column=0, sticky="NW")
 
     def set_settings(self):
         max_width, max_height = int(self.max_width_scaler.get_value()) / 100, int(self.max_height_scaler.get_value()) / 100
         scaled_w, scaled_h, _, _ = get_img_resize_info(img_size=(self.video_meta_data['width'], self.video_meta_data['height']), display_resolution=None, max_width_ratio=max_width, max_height_ratio=max_height)
         self.img_display_size = (scaled_w, scaled_h)
-        self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=self.img_idx, display_size=self.img_display_size)
-
+        self.font_size, self.space_x, self.spacing_scale = PlottingMixin().get_optimal_font_scales(text='999999', accepted_px_width=int(self.img_display_size[0] / 8), accepted_px_height=int(self.img_display_size[1] / 8))
+        self.img_greyscale = str_2_bool(input_str=self.img_grey_dropdown.get_value())
+        self.save_verbosity = str_2_bool(input_str=self.verbosity_dropdown.get_value())
+        self.show_video_timer = str_2_bool(input_str=self.video_timer_dropdown.get_value())
+        self.set_img(img_lbl=self.img_lbl, video_path=self.cap, img_idx=self.img_idx, display_size=self.img_display_size, show_timer=self.show_video_timer)
         pass
 
 # test = LabellingInterface(config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini",

{simba_uw_tf_dev-5.3.9 → simba_uw_tf_dev-5.4.1}/simba/mixins/circular_statistics.py

@@ -62,7 +62,7 @@ class CircularStatisticsMixin(object):
         Jitted compute of the mean resultant vector length of a single sample. Captures the overall "pull" or "tendency" of the
         data points towards a central direction on the circle with a range between 0 and 1.
 
-        .. image:: _static/img/mean_resultant_vector.png
+        .. image:: _static/img/mean_resultant_vector.webp
            :width: 400
            :align: center
 
@@ -100,8 +100,7 @@ class CircularStatisticsMixin(object):
         data points towards a central direction on the circle with a range between 0 and 1.
 
         .. attention::
-           The returned values represents resultant vector length in the time-window ``[(current_frame-time_window)->current_frame]``.
-           `-1` is returned where ``current_frame-time_window`` is less than 0.
+           The returned values represents resultant vector length in the time-window ``[(current_frame-time_window)->current_frame]``. `-1` is returned where ``current_frame-time_window`` is less than 0.
 
         .. image:: _static/img/sliding_mean_resultant_length.png
            :width: 600
@@ -590,6 +589,9 @@ class CircularStatisticsMixin(object):
         .. note::
            Adapted from ``pingouin.circular.circ_rayleigh`` and ``pycircstat.tests.rayleigh``.
 
+        .. image:: _static/img/rayleigh.webp
+           :width: 600
+           :align: center
 
         The Rayleigh Z score is calculated as follows:
 
@@ -598,10 +600,10 @@ class CircularStatisticsMixin(object):
 
         where :math:`n` is the sample size and :math:`R` is the mean resultant length.
 
-        The associated p-value is calculated as follows:
+        The associated p-value is calculated as follows (note this uses the resultant length :math:`nR`, not the mean resultant length :math:`R`):
 
         .. math::
-           p = \\exp\\left(\\sqrt{1 + 4n + 4(n^2 - R^2)} - (1 + 2n)\\right)
+           p = \\exp\\left(\\sqrt{1 + 4n + 4(n^2 - (nR)^2)} - (1 + 2n)\\right)
 
         .. seealso::
            :func:`simba.data_processors.cuda.circular_statistics.sliding_rayleigh_z`,
@@ -613,16 +615,15 @@ class CircularStatisticsMixin(object):
 
         >>> data = np.array([350, 360, 365, 360, 100, 109, 232, 123, 42, 3,4, 145]).astype(np.float32)
         >>> CircularStatisticsMixin().rayleigh(data=data)
-        >>> (2.3845645695246467, 0.9842236169985417)
+        >>> (2.3845645695246467, 0.09027923051217743)
         """
 
         data = np.deg2rad(data)
-        R = np.sqrt(np.sum(np.cos(data)) ** 2 + np.sum(np.sin(data)) ** 2) / len(data)
-        p = np.exp(
-            np.sqrt(1 + 4 * len(data) + 4 * (len(data) ** 2 - R**2))
-            - (1 + 2 * len(data))
-        )
-        return len(data) * R**2, p
+        n = len(data)
+        R = np.sqrt(np.sum(np.cos(data)) ** 2 + np.sum(np.sin(data)) ** 2) / n
+        R_len = n * R   # resultant length (0..n); the p-value approximation requires this, not the mean resultant length
+        p = np.exp(np.sqrt(1 + 4 * n + 4 * (n ** 2 - R_len ** 2)) - (1 + 2 * n))
+        return n * R**2, p
 
     @staticmethod
     @njit("(float32[:], float64[:], float64)", parallel=True)
@@ -654,9 +655,11 @@ class CircularStatisticsMixin(object):
             win_size = int(time_windows[i] * fps)
             for j in prange(win_size, len(data) + 1):
                 data_win = data[j - win_size : j]
-                R = np.sqrt(np.sum(np.cos(data_win)) ** 2 + np.sum(np.sin(data_win)) ** 2) / len(data_win)
-                Z_results[j - 1][i] = len(data_win) * R**2
-                P_results[j - 1][i] = np.exp(np.sqrt(1 + 4 * len(data_win) + 4 * (len(data_win) ** 2 - R**2)) - (1 + 2 * len(data_win)))
+                n_win = len(data_win)
+                R = np.sqrt(np.sum(np.cos(data_win)) ** 2 + np.sum(np.sin(data_win)) ** 2) / n_win
+                R_len = n_win * R   # resultant length (0..n); required by the p-value approximation
+                Z_results[j - 1][i] = n_win * R**2
+                P_results[j - 1][i] = np.exp(np.sqrt(1 + 4 * n_win + 4 * (n_win ** 2 - R_len ** 2)) - (1 + 2 * n_win))
         return Z_results, P_results
 
     @staticmethod
@@ -866,8 +869,12 @@ class CircularStatisticsMixin(object):
         """
         Jitted compute of Rao's spacing for angular data.
 
-        Computes the uniformity of a circular dataset in degrees. Low output values represent concentrated angularity,
-        while high values represent dispersed angularity.
+        Computes the uniformity of a circular dataset in degrees. High output values represent concentrated (clustered)
+        angularity with uneven gaps between observations, while low values (near 0) represent evenly-spaced, uniform angularity.
+
+        .. image:: _static/img/rao_spacing.webp
+           :width: 600
+           :align: center
 
         The Rao's Spacing (:math:`U`) is calculated as follows:
 
@@ -895,7 +902,7 @@ class CircularStatisticsMixin(object):
 
         data = np.sort(data)
         Ti, TiL = np.full((data.shape[0]), np.nan), np.full((data.shape[0]), np.nan)
-        l = np.int8(360 / len(data))
+        l = 360 / len(data)
         Ti[-1] = np.rad2deg(np.pi - np.abs(np.pi - np.abs(np.deg2rad(data[0]) - np.deg2rad(data[-1])))
         )
         for j in range(data.shape[0] - 1, -1, -1):
@@ -952,7 +959,7 @@ class CircularStatisticsMixin(object):
             for i in range(window_size, data.shape[0]):
                 w_data = np.sort(data[i - window_size : i])
                 Ti, TiL = np.full((w_data.shape[0]), np.nan), np.full((w_data.shape[0]), np.nan)
-                l = np.int16(360 / len(w_data))
+                l = 360 / len(w_data)
                 Ti[-1] = np.rad2deg(np.pi - np.abs(np.pi - np.abs(np.deg2rad(w_data[0]) - np.deg2rad(w_data[-1]))))
                 for j in range(w_data.shape[0] - 1, -1, -1):
                     Ti[j] = np.rad2deg(np.pi - np.abs(np.pi - np.abs(np.deg2rad(w_data[j]) - np.deg2rad(w_data[j - 1]))))
@@ -971,6 +978,10 @@ class CircularStatisticsMixin(object):
 
         Kuiper's two-sample test is a non-parametric test used to determine if two samples are drawn from the same circular distribution. It is particularly useful for circular data, such as angles or directions.
 
+        .. image:: _static/img/kuipers_two_sample_test.webp
+           :width: 600
+           :align: center
+
         The Kuiper test statistic is calculated as the sum of the maximum positive and negative deviations between the cumulative distribution functions of the two samples:
 
         .. math::
@@ -1031,11 +1042,9 @@ class CircularStatisticsMixin(object):
         for time_window_cnt in prange(time_windows.shape[0]):
             win_size = int(time_windows[time_window_cnt] * fps)
             for i in range(win_size, sample_1.shape[0]):
-                sample_1_win, sample_2_win = (
-                    sample_1[i - win_size : i],
-                    sample_2[i - win_size : i],
-                )
-                cdfv1 = np.searchsorted(sample_2, sample_1_win) / float(
+                sample_1_win = np.sort(sample_1[i - win_size : i])
+                sample_2_win = np.sort(sample_2[i - win_size : i])
+                cdfv1 = np.searchsorted(sample_2_win, sample_1_win) / float(
                     len(sample_2_win)
                 )
                 cdfv2 = np.searchsorted(sample_1_win, sample_2_win) / float(
@@ -1466,6 +1475,10 @@ class CircularStatisticsMixin(object):
         """
         Determines the preferred turning direction from a 1D array of circular directional data.
 
+        .. image:: _static/img/preferred_turning_direction.webp
+           :width: 600
+           :align: center
+
         .. note::
            The input ``x`` can be created using any of the following methods:
            - :func:`simba.mixins.circular_statistics.CircularStatisticsMixin.direction_two_bps`