simba-uw-tf-dev 4.5.8__py3-none-any.whl → 4.7.1__py3-none-any.whl

simba/data_processors/kleinberg_calculator.py

@@ -13,10 +13,14 @@ from simba.data_processors.pybursts_calculator import kleinberg_burst_detection
 from simba.mixins.config_reader import ConfigReader
 from simba.utils.checks import (check_float, check_if_dir_exists,
                                 check_if_filepath_list_is_empty, check_int,
-                                check_that_column_exist, check_valid_lst)
+                                check_that_column_exist, check_valid_boolean,
+                                check_valid_lst)
 from simba.utils.enums import Paths, TagNames
 from simba.utils.printing import SimbaTimer, log_event, stdout_success
-from simba.utils.read_write import get_fn_ext, read_df, write_df
+from simba.utils.read_write import (copy_files_to_directory,
+                                    find_files_of_filetypes_in_directory,
+                                    get_current_time, get_fn_ext, read_df,
+                                    remove_a_folder, write_df)
 from simba.utils.warnings import KleinbergWarning
 
 
@@ -38,12 +42,13 @@ class KleinbergCalculator(ConfigReader):
 
     :param str config_path: path to SimBA project config file in Configparser format
     :param List[str] classifier_names: Classifier names to apply Kleinberg smoothing to.
-    :param float sigma: Burst detection sigma value. Higher sigma values and fewer, longer, behavioural bursts will be recognised. Default: 2.
-    :param float gamma: Burst detection gamma value. Higher gamma values and fewer behavioural bursts will be recognised. Default: 0.3.
-    :param int hierarchy: Burst detection hierarchy level. Higher hierarchy values and fewer behavioural bursts will to be recognised. Default: 1.
-    :param bool hierarchical_search: See `Tutorial <https://github.com/sgoldenlab/simba/blob/master/docs/kleinberg_filter.md#hierarchical-search-example>`_ Default: False.
+    :param float sigma: State transition cost for moving to higher burst levels. Higher values (e.g., 2-3) produce fewer but longer bursts; lower values (e.g., 1.1-1.5) detect more frequent, shorter bursts. Must be > 1.01. Default: 2.
+    :param float gamma: State transition cost for moving to lower burst levels. Higher values (e.g., 0.5-1.0) reduce total burst count by making downward transitions costly; lower values (e.g., 0.1-0.3) allow more flexible state changes. Must be >= 0. Default: 0.3.
+    :param int hierarchy: Hierarchy level to extract bursts from (0=lowest, higher=more selective). Level 0 captures all bursts; level 1-2 typically filters noise; level 3+ selects only the most prominent, sustained bursts. Higher levels yield fewer but more confident detections. Must be >= 0. Default: 1.
+    :param bool hierarchical_search: If True, searches for target hierarchy level within detected burst periods, falling back to lower levels if target not found. If False, extracts only bursts at the exact specified hierarchy level. Recommended when target hierarchy may be sparse. Default: False.
     :param Optional[Union[str, os.PathLike]] input_dir: The directory with files to perform kleinberg smoothing on. If None, defaults to `project_folder/csv/machine_results`
     :param Optional[Union[str, os.PathLike]] output_dir: Location to save smoothened data in. If None, defaults to `project_folder/csv/machine_results`
+    :param Optional[bool] save_originals: If True, saves the original data in sub-directory of the ouput directory.`
 
     :example I:
     >>> kleinberg_calculator = KleinbergCalculator(config_path='MySimBAConfigPath', classifier_names=['Attack'], sigma=2, gamma=0.3, hierarchy=2, hierarchical_search=False)
@@ -68,10 +73,12 @@ class KleinbergCalculator(ConfigReader):
 
     def __init__(self,
                  config_path: Union[str, os.PathLike],
-                 classifier_names: List[str],
-                 sigma: Optional[int] = 2,
-                 gamma: Optional[float] = 0.3,
+                 classifier_names: Optional[List[str]] = None,
+                 sigma: float = 2,
+                 gamma: float = 0.3,
                  hierarchy: Optional[int] = 1,
+                 verbose: bool = True,
+                 save_originals: bool = True,
                  hierarchical_search: Optional[bool] = False,
                  input_dir: Optional[Union[str, os.PathLike]] = None,
                  output_dir: Optional[Union[str, os.PathLike]] = None):
@@ -81,25 +88,31 @@ class KleinbergCalculator(ConfigReader):
         check_float(value=sigma, name=f'{self.__class__.__name__} sigma', min_value=1.01)
         check_float(value=gamma, name=f'{self.__class__.__name__} gamma', min_value=0)
         check_int(value=hierarchy, name=f'{self.__class__.__name__} hierarchy', min_value=0)
-        check_valid_lst(data=classifier_names, source=f'{self.__class__.__name__} classifier_names', valid_dtypes=(str,), min_len=1)
+        if isinstance(classifier_names, list):
+            check_valid_lst(data=classifier_names, source=f'{self.__class__.__name__} classifier_names', valid_dtypes=(str,), min_len=1)
+        else:
+            classifier_names = deepcopy(self.clf_names)
+        check_valid_boolean(value=verbose, source=f'{self.__class__.__name__} verbose', raise_error=True)
+        check_valid_boolean(value=save_originals, source=f'{self.__class__.__name__} save_originals', raise_error=True)
         self.hierarchical_search, sigma, gamma, hierarchy, self.output_dir = (hierarchical_search, float(sigma), float(gamma), int(hierarchy), output_dir)
-        self.sigma, self.gamma, self.hierarchy, self.clfs = ( float(sigma), float(gamma), float(hierarchy), classifier_names)
+        self.sigma, self.gamma, self.hierarchy, self.clfs = ( float(sigma), float(gamma), int(hierarchy), classifier_names)
+        self.verbose, self.save_originals = verbose, save_originals
         if input_dir is None:
-            self.data_paths, self.output_dir = self.machine_results_paths, self.machine_results_dir
-            check_if_filepath_list_is_empty(filepaths=self.machine_results_paths, error_msg=f"SIMBA ERROR: No data files found in {self.machine_results_dir}. Cannot perform Kleinberg smoothing")
-            original_data_files_folder = os.path.join(self.project_path, Paths.MACHINE_RESULTS_DIR.value, f"Pre_Kleinberg_{self.datetime}")
-            if not os.path.exists(original_data_files_folder):
-                os.makedirs(original_data_files_folder)
-            for file_path in self.machine_results_paths:
-                _, file_name, ext = get_fn_ext(file_path)
-                shutil.copyfile(file_path, os.path.join(original_data_files_folder, file_name + ext))
+            self.input_dir = os.path.join(self.project_path, Paths.MACHINE_RESULTS_DIR.value)
         else:
             check_if_dir_exists(in_dir=input_dir)
-            self.data_paths = glob.glob(input_dir + f"/*.{self.file_type}")
-            check_if_filepath_list_is_empty(filepaths=self.data_paths, error_msg=f"SIMBA ERROR: No data files found in {input_dir}. Cannot perform Kleinberg smoothing")
-            if not os.path.isdir(output_dir):
-                os.makedirs(output_dir)
-        print(f"Processing Kleinberg burst detection for {len(self.data_paths)} file(s) and {len(classifier_names)} classifier(s)...")
+            self.input_dir = deepcopy(input_dir)
+        self.data_paths = find_files_of_filetypes_in_directory(directory=self.input_dir, extensions=[f'.{self.file_type}'], sort_alphabetically=True, raise_error=True)
+        if output_dir is None:
+            self.output_dir = deepcopy(self.input_dir)
+        else:
+            check_if_dir_exists(in_dir=output_dir)
+            self.output_dir = deepcopy(output_dir)
+        self.original_data_files_folder = os.path.join(self.output_dir, f"Pre_Kleinberg_{self.datetime}")
+        remove_a_folder(folder_dir=self.original_data_files_folder, ignore_errors=True)
+        os.makedirs(self.original_data_files_folder)
+        copy_files_to_directory(file_paths=self.data_paths, dir=self.original_data_files_folder, verbose=False, integer_save_names=False)
+        if self.verbose: print(f"Processing Kleinberg burst detection for {len(self.data_paths)} file(s) and {len(classifier_names)} classifier(s)...")
 
     def hierarchical_searcher(self):
         if (len(self.kleinberg_bouts["Hierarchy"]) == 1) and (int(self.kleinberg_bouts.at[0, "Hierarchy"]) == 0):
@@ -135,7 +148,7 @@ class KleinbergCalculator(ConfigReader):
         for file_cnt, file_path in enumerate(self.data_paths):
             _, video_name, _ = get_fn_ext(file_path)
             video_timer = SimbaTimer(start=True)
-            print(f"Performing Kleinberg burst detection for video {video_name}  (Video {file_cnt+1}/{len(self.data_paths)})...")
+            if self.verbose: print(f"[{get_current_time()}] Performing Kleinberg burst detection for video {video_name} (Video {file_cnt+1}/{len(self.data_paths)})...")
             data_df = read_df(file_path, self.file_type).reset_index(drop=True)
             video_out_df = deepcopy(data_df)
             check_that_column_exist(df=data_df, column_name=self.clfs, file_name=video_name)
@@ -150,7 +163,7 @@ class KleinbergCalculator(ConfigReader):
                     self.kleinberg_bouts.insert(loc=0, column="Video", value=video_name)
                     detailed_df_lst.append(self.kleinberg_bouts)
                     if self.hierarchical_search:
-                        print(f"Applying hierarchical search for video {video_name}...")
+                        if self.verbose: print(f"[{get_current_time()}] Applying hierarchical search for video {video_name}...")
                         self.hierarchical_searcher()
                     else:
                         self.clf_bouts_in_hierarchy = self.kleinberg_bouts[self.kleinberg_bouts["Hierarchy"] == self.hierarchy]
@@ -160,19 +173,38 @@ class KleinbergCalculator(ConfigReader):
                     video_out_df.loc[hierarchy_idx, clf] = 1
             write_df(video_out_df, self.file_type, save_path)
             video_timer.stop_timer()
-            print(f'Kleinberg analysis complete for video {video_name} (saved at {save_path}), elapsed time: {video_timer.elapsed_time_str}s.')
+            if self.verbose: print(f'[{get_current_time()}] Kleinberg analysis complete for video {video_name} (saved at {save_path}), elapsed time: {video_timer.elapsed_time_str}s.')
 
         self.timer.stop_timer()
+        if not self.save_originals:
+            remove_a_folder(folder_dir=self.original_data_files_folder, ignore_errors=False)
+        else:
+            if self.verbose: stdout_success(msg=f"Original, un-smoothened data, saved in {self.original_data_files_folder} directory", elapsed_time=self.timer.elapsed_time_str, source=self.__class__.__name__)
         if len(detailed_df_lst) > 0:
             self.detailed_df = pd.concat(detailed_df_lst, axis=0)
             detailed_save_path = os.path.join(self.logs_path, f"Kleinberg_detailed_log_{self.datetime}.csv")
             self.detailed_df.to_csv(detailed_save_path)
-            stdout_success(msg=f"Kleinberg analysis complete. See {detailed_save_path} for details of detected bouts of all classifiers in all hierarchies", elapsed_time=self.timer.elapsed_time_str, source=self.__class__.__name__)
+            if self.verbose:  stdout_success(msg=f"Kleinberg analysis complete for {len(self.data_paths)} files. Results stored in {self.output_dir} directory. See {detailed_save_path} for details of detected bouts of all classifiers in all hierarchies", elapsed_time=self.timer.elapsed_time_str, source=self.__class__.__name__)
         else:
-            print("Kleinberg analysis complete.")
+            if self.verbose: print(f"[{get_current_time()}] Kleinberg analysis complete for {len(self.data_paths)} files. Results stored in {self.output_dir} directory.")
             KleinbergWarning(msg="All behavior bouts removed following kleinberg smoothing", source=self.__class__.__name__)
 
 
+
+
+# test = KleinbergCalculator(config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini",
+#                            classifier_names=['straub_tail'],
+#                            sigma=1.1,
+#                            gamma=0.1,
+#                            hierarchy=1,
+#                            save_originals=False,
+#                            hierarchical_search=False)
+#
+# test.run()
+#
+
+
+
 # test = KleinbergCalculator(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/levi/project_folder/project_config.ini',
 #                            classifier_names=['No_Seizure_(0)'],
 #                            sigma=1.1,

simba/feature_extractors/feature_subsets.py

@@ -83,12 +83,12 @@ class FeatureSubsetsCalculator(ConfigReader, TrainModelMixin):
        :align: center
 
     :example:
-    >>> test = FeatureSubsetsCalculator(config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini",
+    >>> test = FeatureSubsetsCalculator(config_path=r"C:/troubleshooting/mitra/project_folder/project_config.ini",
     >>>                               feature_families=[FRAME_BP_MOVEMENT, WITHIN_ANIMAL_THREE_POINT_ANGLES],
     >>>                               append_to_features_extracted=False,
     >>>                               file_checks=False,
     >>>                               append_to_targets_inserted=False,
-    >>>                               save_dir=r"C:\troubleshooting\mitra\project_folder\csv\new_features")
+    >>>                               save_dir=r"C:/troubleshooting/mitra/project_folder/csv/new_features")
     >>> test.run()
     """
 
@@ -154,11 +154,11 @@ class FeatureSubsetsCalculator(ConfigReader, TrainModelMixin):
             self.within_animal_four_point_combs[animal] = np.array(list(combinations(animal_bps, 4)))
 
     def _get_two_point_bp_distances(self):
-        for c in self.two_point_combs:
+        for cnt, c in enumerate(self.two_point_combs):
             x1, y1, x2, y2 = list(sum([(f"{x}_x", f"{y}_y") for (x, y) in zip(c, c)], ()))
             bp1 = self.data_df[[x1, y1]].values
             bp2 = self.data_df[[x2, y2]].values
-            self.results[f"Distance (mm) {c[0]}-{c[1]}"] = FeatureExtractionMixin.framewise_euclidean_distance(location_1=bp1.astype(np.float64), location_2=bp2.astype(np.float64), px_per_mm=np.float64(self.px_per_mm), centimeter=False)
+            self.results[f"Distance (mm) {c[0]}-{c[1]}"] = FeatureExtractionMixin.bodypart_distance(bp1_coords=bp1.astype(np.int32), bp2_coords=bp2.astype(np.int32), px_per_mm=np.float64(self.px_per_mm), in_centimeters=False)
 
     def __get_three_point_angles(self):
         for animal, points in self.within_animal_three_point_combs.items():
@@ -342,13 +342,20 @@ class FeatureSubsetsCalculator(ConfigReader, TrainModelMixin):
 
 
 
+# test = FeatureSubsetsCalculator(config_path=r"C:\troubleshooting\srami0619\project_folder\project_config.ini",
+#                                 feature_families=[TWO_POINT_BP_DISTANCES],
+#                                 append_to_features_extracted=False,
+#                                 file_checks=True,
+#                                 append_to_targets_inserted=False)
+# test.run()
+
+
 
 # test = FeatureSubsetsCalculator(config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini",
-#                                 feature_families=[ARENA_EDGE],
+#                                 feature_families=[TWO_POINT_BP_DISTANCES],
 #                                 append_to_features_extracted=False,
 #                                 file_checks=True,
-#                                 append_to_targets_inserted=False,
-#                                 save_dir=r"C:\troubleshooting\mitra\project_folder\csv\feature_subset")
+#                                 append_to_targets_inserted=False)
 # test.run()
 
 #

simba/feature_extractors/mitra_feature_extractor.py

@@ -28,7 +28,7 @@ RIGHT_EAR = 'right_ear'
 CENTER = 'center'
 TAIL_BASE = 'tail_base'
 TAIL_CENTER = 'tail_center'
-TAIL_TIP = 'tail_tip'
+TAIL_TIP = 'tail_end'
 
 TIME_WINDOWS = np.array([0.25, 0.5, 1.0, 2.0])
 
@@ -207,7 +207,7 @@ class MitraFeatureExtractor(ConfigReader,
 
 
 
-# feature_extractor = MitraFeatureExtractor(config_path=r"D:\troubleshooting\mitra\project_folder\project_config.ini")
+# feature_extractor = MitraFeatureExtractor(config_path=r"E:\troubleshooting\mitra_emergence\project_folder\project_config.ini")
 # feature_extractor.run()
 
 

simba/feature_extractors/straub_tail_analyzer.py

@@ -9,8 +9,6 @@ try:
 except:
     from typing_extensions import Literal
 
-import functools
-import multiprocessing
 from copy import deepcopy
 
 import numpy as np
@@ -46,10 +44,10 @@ class StraubTailAnalyzer(ConfigReader):
     .. [1] Lazaro et al., Brainwide Genetic Capture for Conscious State Transitions, `biorxiv`, doi: https://doi.org/10.1101/2025.03.28.646066
 
     :example:
-    >>> runner = StraubTailAnalyzer(config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini",
-    >>>                            data_dir=r'C:\troubleshooting\mitra\project_folder\videos\additional\bg_removed\rotated',
-    >>>                            video_dir=r'C:\troubleshooting\mitra\project_folder\videos\additional\bg_removed\rotated',
-    >>>                            save_dir=r'C:\troubleshooting\mitra\project_folder\videos\additional\bg_removed\rotated\tail_features_additional',
+    >>> runner = StraubTailAnalyzer(config_path=r"C:/troubleshooting/mitra/project_folder/project_config.ini",
+    >>>                            data_dir=r'C:/troubleshooting/mitra/project_folder/videos/additional/bg_removed/rotated',
+    >>>                            video_dir=r'C:/troubleshooting/mitra/project_folder/videos/additional/bg_removed/rotated',
+    >>>                            save_dir=r'C:/troubleshooting/mitra/project_folder/videos/additional/bg_removed/rotated/tail_features_additional',
     >>>                            anchor_points=('tail_base', 'tail_center', 'tail_tip'),
     >>>                            body_parts=('nose', 'left_ear', 'right_ear', 'right_side', 'left_side', 'tail_base'))
     >>> runner.run()

simba/labelling/standard_labeller.py

@@ -64,7 +64,7 @@ class LabellingInterface(ConfigReader):
     :param bool continuing: Set True to resume annotations from an existing targets file. Defaults to False.
 
     :example:
-    >>> _ = LabellingInterface(config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini", file_path=r"C:\troubleshooting\mitra\project_folder\videos\501_MA142_Gi_CNO_0521.mp4", thresholds=None, continuing=False)
+    >>> _ = LabellingInterface(config_path=r"C:/troubleshooting/mitra/project_folder/project_config.ini", file_path=r"C:/troubleshooting/mitra/project_folder/videos/501_MA142_Gi_CNO_0521.mp4", thresholds=None, continuing=False)
     """
 
     def __init__(self,

simba/mixins/config_reader.py

@@ -41,8 +41,8 @@ from simba.utils.read_write import (find_core_cnt, get_all_clf_names,
                                     get_fn_ext, read_config_file, read_df,
                                     read_project_path_and_file_type, write_df)
 from simba.utils.warnings import (BodypartColumnNotFoundWarning,
-                                  InvalidValueWarning, NoDataFoundWarning,
-                                  NoFileFoundWarning)
+                                  DuplicateNamesWarning, InvalidValueWarning,
+                                  NoDataFoundWarning, NoFileFoundWarning)
 
 
 class ConfigReader(object):
@@ -610,11 +610,14 @@ class ConfigReader(object):
         >>> config_reader.get_bp_headers()
         """
 
+        duplicates = list({x for x in self.body_parts_lst if self.body_parts_lst.count(x) > 1})
+        if len(duplicates) > 0: DuplicateNamesWarning(msg=f'The pose configuration file at {self.body_parts_path} contains duplicate entries: {duplicates}', source=self.__class__.__name__)
         self.bp_headers = []
         for bp in self.body_parts_lst:
             c1, c2, c3 = (f"{bp}_x", f"{bp}_y", f"{bp}_p")
             self.bp_headers.extend((c1, c2, c3))
 
+
     def read_config_entry(
         self,
         config: ConfigParser,

simba/mixins/geometry_mixin.py

@@ -1339,8 +1339,7 @@ class GeometryMixin(object):
             )
             for cnt, result in enumerate(pool.imap(constants, data, chunksize=1)):
                 results.append(result)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         if data_ndim == 2:
             return [i for s in results for i in s]
         else:
@@ -1370,8 +1369,7 @@ class GeometryMixin(object):
                                           cap_style=cap_style)
             for cnt, mp_return in enumerate(pool.imap(constants, geomety_lst, chunksize=1)):
                 results.append(mp_return)
-            pool.join()
-            pool.terminate()
+            terminate_cpu_pool(pool=pool, force=False)
         return [l for ll in results for l in ll]
 
     def multiframe_bodyparts_to_circle(self,
@@ -1524,8 +1522,7 @@ class GeometryMixin(object):
             )
             for cnt, result in enumerate(pool.imap(constants, data, chunksize=1)):
                 results.append(result)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     def multiframe_compute_pct_shape_overlap(self,
@@ -1559,7 +1556,7 @@ class GeometryMixin(object):
         :rtype: List[float]
 
         :example:
-        >>> df = read_df(file_path=r"C:\troubleshooting\two_black_animals_14bp\project_folder\csv\outlier_corrected_movement_location\Together_2.csv", file_type='csv').astype(int)
+        >>> df = read_df(file_path=r"C:/troubleshooting/two_black_animals_14bp/project_folder/csv/outlier_corrected_movement_location/Together_2.csv", file_type='csv').astype(int)
         >>> animal_1_cols = [x for x in df.columns if '_1_' in x and not '_p' in x]
         >>> animal_2_cols = [x for x in df.columns if '_2_' in x and not '_p' in x]
         >>> animal_1_arr = df[animal_1_cols].values.reshape(len(df), int(len(animal_1_cols)/ 2), 2)
@@ -1625,7 +1622,7 @@ class GeometryMixin(object):
         :return List[float]: List of overlap between corresponding Polygons. If overlap 1, else 0.
 
         :example:
-        >>> df = read_df(file_path=r"C:\troubleshooting\two_black_animals_14bp\project_folder\csv\outlier_corrected_movement_location\Together_2.csv", file_type='csv').astype(int)
+        >>> df = read_df(file_path=r"C:/troubleshooting/two_black_animals_14bp/project_folder/csv/outlier_corrected_movement_location/Together_2.csv", file_type='csv').astype(int)
         >>> animal_1_cols = [x for x in df.columns if '_1_' in x and not '_p' in x]
         >>> animal_2_cols = [x for x in df.columns if '_2_' in x and not '_p' in x]
         >>> animal_1_arr = df[animal_1_cols].values.reshape(len(df), int(len(animal_1_cols)/ 2), 2)
@@ -1696,7 +1693,7 @@ class GeometryMixin(object):
         :rtype: List[float]
 
         :example:
-        >>> df = read_df(file_path=r"C:\troubleshooting\two_black_animals_14bp\project_folder\csv\outlier_corrected_movement_location\Together_2.csv", file_type='csv').astype(int)
+        >>> df = read_df(file_path=r"C:/troubleshooting/two_black_animals_14bp/project_folder/csv/outlier_corrected_movement_location/Together_2.csv", file_type='csv').astype(int)
         >>> animal_1_cols = [x for x in df.columns if '_1_' in x and not '_p' in x]
         >>> animal_2_cols = [x for x in df.columns if '_2_' in x and not '_p' in x]
         >>> animal_1_arr = df[animal_1_cols].values.reshape(len(df), int(len(animal_1_cols)/ 2), 2)
@@ -1766,7 +1763,7 @@ class GeometryMixin(object):
         :rtype: List[Polygon]
 
         :example:
-        >>> df = read_df(file_path=r"C:\troubleshooting\two_black_animals_14bp\project_folder\csv\outlier_corrected_movement_location\Together_2.csv", file_type='csv').astype(int)
+        >>> df = read_df(file_path=r"C:/troubleshooting/two_black_animals_14bp/project_folder/csv/outlier_corrected_movement_location/Together_2.csv", file_type='csv').astype(int)
         >>> animal_1_cols = [x for x in df.columns if '_1_' in x and not '_p' in x]
         >>> animal_1_arr = df[animal_1_cols].values.reshape(len(df), int(len(animal_1_cols)/ 2), 2)
         >>> animal_1_geo = GeometryMixin.bodyparts_to_polygon(data=animal_1_arr)
@@ -1798,8 +1795,7 @@ class GeometryMixin(object):
         timer.stop_timer()
         if verbose:
             stdout_success(msg="Rotated rectangles complete.", elapsed_time=timer.elapsed_time_str)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     @staticmethod
@@ -2003,8 +1999,7 @@ class GeometryMixin(object):
             )
             for cnt, result in enumerate(pool.imap(constants, shapes, chunksize=1)):
                 results.append(result)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     def multiframe_union(self, shapes: Iterable[Union[LineString, MultiLineString, Polygon]], core_cnt: int = -1) -> \
@@ -2043,8 +2038,7 @@ class GeometryMixin(object):
         with multiprocessing.Pool(core_cnt, maxtasksperchild=Defaults.LARGE_MAX_TASK_PER_CHILD.value) as pool:
             for cnt, result in enumerate(pool.imap(GeometryMixin().union, shapes, chunksize=1)):
                 results.append(result)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     def multiframe_symmetric_difference(self, shapes: Iterable[Union[LineString, MultiLineString, Polygon]],
@@ -2084,8 +2078,7 @@ class GeometryMixin(object):
                     pool.imap(GeometryMixin().symmetric_difference, shapes, chunksize=1)
             ):
                 results.append(result)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     def multiframe_delaunay_triangulate_keypoints(self, data: np.ndarray, core_cnt: int = -1) -> List[List[Polygon]]:
@@ -2132,8 +2125,7 @@ class GeometryMixin(object):
             ):
                 results.append(result)
 
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     def multiframe_difference(
@@ -2221,8 +2213,7 @@ class GeometryMixin(object):
             msg="Multi-frame difference compute complete",
             elapsed_time=timer.elapsed_time_str,
         )
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     def multiframe_area(self,
@@ -2276,8 +2267,7 @@ class GeometryMixin(object):
 
         timer.stop_timer()
         stdout_success(msg="Multi-frame area compute complete", elapsed_time=timer.elapsed_time_str)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     def multiframe_bodyparts_to_multistring_skeleton(
@@ -2619,8 +2609,7 @@ class GeometryMixin(object):
                     pool.imap(GeometryMixin.is_shape_covered, shapes, chunksize=1)
             ):
                 results.append(mp_return)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     @staticmethod
@@ -3321,8 +3310,7 @@ class GeometryMixin(object):
             for cnt, result in enumerate(pool.imap(constants, data, chunksize=1)):
                 if result[1] != -1:
                     img_arr[result[0], result[2] - 1, result[1] - 1] = 1
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         timer.stop_timer()
         stdout_success(
             msg="Cumulative coordinates in geometries complete",
@@ -3415,8 +3403,7 @@ class GeometryMixin(object):
             for cnt, result in enumerate(pool.imap(constants, data, chunksize=1)):
                 if result[1] != -1:
                     img_arr[result[0], result[2] - 1, result[1] - 1] = 1
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         if fps is None:
             return np.cumsum(img_arr, axis=0)
         else:
@@ -3538,10 +3525,10 @@ class GeometryMixin(object):
         :rtype: Tuple[Dict[Tuple[int, int], Dict[Tuple[int, int], float]], Dict[Tuple[int, int], Dict[Tuple[int, int], int]]]
 
         :example:
-        >>> video_meta_data = get_video_meta_data(video_path=r"C:\troubleshooting\mitra\project_folder\videos\708_MA149_Gq_CNO_0515.mp4")
+        >>> video_meta_data = get_video_meta_data(video_path=r"C:/troubleshooting/mitra/project_folder/videos/708_MA149_Gq_CNO_0515.mp4")
         >>> w, h = video_meta_data['width'], video_meta_data['height']
         >>> grid = GeometryMixin().bucket_img_into_grid_square(bucket_grid_size=(5, 5), bucket_grid_size_mm=None, img_size=(h, w), verbose=False)[0]
-        >>> data = read_df(file_path=r'C:\troubleshooting\mitra\project_folder\csv\outlier_corrected_movement_location\708_MA149_Gq_CNO_0515.csv', file_type='csv')[['Nose_x', 'Nose_y']].values
+        >>> data = read_df(file_path=r'C:/troubleshooting/mitra/project_folder/csv/outlier_corrected_movement_location/708_MA149_Gq_CNO_0515.csv', file_type='csv')[['Nose_x', 'Nose_y']].values
         >>> transition_probabilities, _ = geometry_transition_probabilities(data=data, grid=grid)
         """
 
@@ -3559,8 +3546,7 @@ class GeometryMixin(object):
             constants = functools.partial(GeometryMixin._compute_framewise_geometry_idx, grid=grid, verbose=verbose)
             for cnt, result in enumerate(pool.imap(constants, data, chunksize=1)):
                 results.append(result)
-        pool.join();
-        pool.terminate();
+        terminate_cpu_pool(pool=pool, force=False)
         del data
 
         results = np.vstack(results)[:, 1:].astype(np.int32)
@@ -4004,7 +3990,7 @@ class GeometryMixin(object):
         :rtype: np.ndarray
 
         :example:
-        >>> data_path = r"C:\troubleshooting\mitra\project_folder\csv\outlier_corrected_movement_location\FRR_gq_Saline_0624.csv"
+        >>> data_path = r"C:/troubleshooting/mitra/project_folder/csv/outlier_corrected_movement_location/FRR_gq_Saline_0624.csv"
         >>> animal_data = read_df(file_path=data_path, file_type='csv', usecols=['Nose_x', 'Nose_y', 'Tail_base_x', 'Tail_base_y', 'Left_side_x', 'Left_side_y', 'Right_side_x', 'Right_side_y']).values.reshape(-1, 4, 2)[0:20].astype(np.int32)
         >>> animal_polygons = GeometryMixin().bodyparts_to_polygon(data=animal_data)
         >>> GeometryMixin.geometries_to_exterior_keypoints(geometries=animal_polygons)
@@ -4174,7 +4160,7 @@ class GeometryMixin(object):
          :rtype: Union[None, Dict[Any, dict]]
 
          :example I:
-             >>> results = GeometryMixin.sleap_csv_to_geometries(data=r"C:\troubleshooting\ants\pose_data\ant.csv")
+             >>> results = GeometryMixin.sleap_csv_to_geometries(data=r"C:/troubleshooting/ants/pose_data/ant.csv")
              >>> # Results structure: {track_id: {frame_idx: Polygon, ...}, ...}
 
         :example II

simba/mixins/image_mixin.py

@@ -18,7 +18,7 @@ from collections import ChainMap
 import cv2
 import pandas as pd
 from numba import float64, int64, jit, njit, prange, uint8
-from shapely.geometry import MultiPolygon, Polygon
+from shapely.geometry import Polygon
 from skimage.metrics import structural_similarity
 
 from simba.utils.checks import (check_file_exist_and_readable, check_float,
@@ -27,16 +27,14 @@ from simba.utils.checks import (check_file_exist_and_readable, check_float,
                                 check_int, check_str, check_valid_array,
                                 check_valid_boolean, check_valid_lst,
                                 check_valid_tuple, is_img_bw, is_img_greyscale)
+from simba.utils.data import terminate_cpu_pool
 from simba.utils.enums import Defaults, Formats, GeometryEnum, Options
-from simba.utils.errors import (ArrayError, FFMPEGCodecGPUError,
-                                FrameRangeError, InvalidInputError,
-                                NotDirectoryError)
+from simba.utils.errors import ArrayError, FrameRangeError, InvalidInputError
 from simba.utils.printing import SimbaTimer, stdout_success
 from simba.utils.read_write import (find_core_cnt,
                                     find_files_of_filetypes_in_directory,
                                     get_fn_ext, get_video_meta_data,
-                                    read_frm_of_video,
-                                    read_img_batch_from_video_gpu, write_df)
+                                    read_frm_of_video)
 
 
 class ImageMixin(object):
@@ -59,17 +57,16 @@ class ImageMixin(object):
         pass
 
     @staticmethod
-    def brightness_intensity(imgs: List[np.ndarray], ignore_black: Optional[bool] = True) -> List[float]:
+    def brightness_intensity(imgs: Union[List[np.ndarray], np.ndarray], ignore_black: bool = True, verbose: bool = False) -> np.ndarray:
         """
         Compute the average brightness intensity within each image within a list.
 
         For example, (i) create a list of images containing a light cue ROI, (ii) compute brightness in each image, (iii) perform kmeans on brightness, and get the frames when the light cue is on vs off.
 
         .. seealso::
-           For GPU acceleration, see :func:`simba.data_processors.cuda.image.img_stack_brightness`.
-           For geometry based brightness, see :func:`simba.mixins.geometry_mixin.GeometryMixin.get_geometry_brightness_intensity`
+           For GPU acceleration, see :func:`simba.data_processors.cuda.image.img_stack_brightness`. For geometry based brightness, see :func:`simba.mixins.geometry_mixin.GeometryMixin.get_geometry_brightness_intensity`
 
-        :param List[np.ndarray] imgs: List of images as arrays to calculate average brightness intensity within.
+        :param Union[List[np.ndarray], np.ndarray] imgs: List of images as arrays or 3/4d array of images to calculate average brightness intensity within.
         :param Optional[bool] ignore_black: If True, ignores black pixels. If the images are sliced non-rectangular geometric shapes created by ``slice_shapes_in_img``, then pixels that don't belong to the shape has been masked in black.
         :returns: List of floats of size len(imgs) with brightness intensities.
         :rtype: List[float]
@@ -79,14 +76,12 @@ class ImageMixin(object):
         >>> ImageMixin.brightness_intensity(imgs=[img], ignore_black=False)
         >>> [159.0]
         """
-        results = []
-        check_instance(source=f"{ImageMixin().brightness_intensity.__name__} imgs", instance=imgs, accepted_types=list)
-        for cnt, img in enumerate(imgs):
-            check_instance(
-                source=f"{ImageMixin().brightness_intensity.__name__} img {cnt}",
-                instance=img,
-                accepted_types=np.ndarray,
-            )
+        results, timer = [], SimbaTimer(start=True)
+        check_instance(source=f"{ImageMixin().brightness_intensity.__name__} imgs", instance=imgs, accepted_types=(list, np.ndarray,))
+        if isinstance(imgs, np.ndarray): imgs = np.array(imgs)
+        for img_cnt in range(imgs.shape[0]):
+            img = imgs[img_cnt]
+            check_instance(source=f"{ImageMixin().brightness_intensity.__name__} img {img_cnt}", instance=img, accepted_types=np.ndarray)
             if len(img) == 0:
                 results.append(0)
             else:
@@ -94,7 +89,10 @@ class ImageMixin(object):
                     results.append(np.ceil(np.average(img[img != 0])))
                 else:
                     results.append(np.ceil(np.average(img)))
-        return results
+        b = np.array(results).astype(np.float32)
+        timer.stop_timer()
+        if verbose: print(f'Brightness computed in {b.shape[0]} images (elapsed time {timer.elapsed_time_str}s)')
+
 
     @staticmethod
     def gaussian_blur(img: np.ndarray, kernel_size: Optional[Tuple] = (9, 9)) -> np.ndarray:
@@ -546,8 +544,8 @@ class ImageMixin(object):
                 pool.imap(constants, split_frm_idx, chunksize=1)
             ):
                 results.append(result)
-        pool.terminate()
-        pool.join()
+
+        terminate_cpu_pool(pool=pool, force=False)
         results = dict(ChainMap(*results))
 
         max_value, max_frm = -np.inf, None
@@ -876,8 +874,7 @@ class ImageMixin(object):
                 pool.imap(ImageMixin()._image_reader_helper, file_paths, chunksize=1)
             ):
                 imgs.update(result)
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return imgs
 
     @staticmethod
@@ -1027,8 +1024,7 @@ class ImageMixin(object):
             for cnt, result in enumerate(pool.imap(constants, frm_lst, chunksize=1)):
                 results.update(result)
 
-        pool.join()
-        pool.terminate()
+        terminate_cpu_pool(pool=pool, force=False)
         return results
 
     @staticmethod
@@ -1509,8 +1505,8 @@ class ImageMixin(object):
                 for cnt, result in enumerate(pool.imap(constants, shapes, chunksize=1)):
                     results.append(result)
                 results = dict(ChainMap(*results))
-        pool.join()
-        pool.terminate()
+
+        terminate_cpu_pool(pool=pool, force=False)
         results = dict(sorted(results.items(), key=lambda item: int(item[0])))
         timer.stop_timer()
         stdout_success(msg="Geometry image slicing complete.", elapsed_time=timer.elapsed_time_str, source=self.__class__.__name__)
@@ -1902,7 +1898,7 @@ class ImageMixin(object):
         :rtype: np.ndarray
 
         :example:
-        >>> VIDEO_PATH = r"D:\EPM_2\EPM_1.mp4"
+        >>> VIDEO_PATH = r"D:/EPM_2/EPM_1.mp4"
         >>> img = read_img_batch_from_video(video_path=VIDEO_PATH, greyscale=True, start_frm=0, end_frm=15, core_cnt=1)
         >>> imgs = np.stack(list(img.values()))
         >>> resized_img = resize_img_stack(imgs=imgs)