simba-uw-tf-dev 4.6.4__py3-none-any.whl → 4.6.7__py3-none-any.whl

simba/data_processors/cuda/statistics.py

@@ -3,7 +3,9 @@ __author__ = "Simon Nilsson; sronilsson@gmail.com"
 
 import math
 from itertools import combinations
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Union
+
+from simba.utils.printing import SimbaTimer
 
 try:
     from typing import Literal
@@ -17,16 +19,20 @@ from scipy.spatial import ConvexHull
 from simba.utils.read_write import get_unique_values_in_iterable, read_df
 from simba.utils.warnings import GPUToolsWarning
 
+
 try:
     import cupy as cp
-    from cuml.metrics import kl_divergence as kl_divergence_gpu
-    from cuml.metrics.cluster.adjusted_rand_index import adjusted_rand_score
-    from cuml.metrics.cluster.silhouette_score import cython_silhouette_score
     from cupyx.scipy.spatial.distance import cdist
-except:
-    GPUToolsWarning(msg='GPU tools not detected, reverting to CPU')
+except Exception as e:
+    GPUToolsWarning(msg=f'GPU tools not detected, reverting to CPU: {e.args}')
     import numpy as cp
     from scipy.spatial.distance import cdist
+try:
+    from cuml.metrics import kl_divergence as kl_divergence_gpu
+    from cuml.metrics.cluster.adjusted_rand_index import adjusted_rand_score
+    from cuml.metrics.cluster.silhouette_score import cython_silhouette_score
+except Exception as e:
+    GPUToolsWarning(msg=f'GPU tools not detected, reverting to CPU: {e.args}')
     from scipy.stats import entropy as kl_divergence_gpu
     from sklearn.metrics import adjusted_rand_score
     from sklearn.metrics import silhouette_score as cython_silhouette_score
@@ -39,7 +45,7 @@ except:
 from simba.data_processors.cuda.utils import _cuda_are_rows_equal
 from simba.mixins.statistics_mixin import Statistics
 from simba.utils.checks import (check_int, check_str, check_valid_array,
-                                check_valid_tuple)
+                                check_valid_tuple, check_float)
 from simba.utils.data import bucket_data
 from simba.utils.enums import Formats
 
@@ -227,7 +233,6 @@ def get_euclidean_distance_cupy(x: np.ndarray,
     using CuPy for GPU acceleration. The computation is performed in batches to handle large
     datasets efficiently.
 
-
     .. seealso::
        For CPU function see :func:`~simba.mixins.feature_extraction_mixin.FeatureExtractionMixin.framewise_euclidean_distance`.
        For CUDA JIT function see :func:`~simba.data_processors.cuda.statistics.get_euclidean_distance_cuda`.
@@ -380,9 +385,10 @@ def sliding_min(x: np.ndarray, time_window: float, sample_rate: int) -> np.ndarr
 
 def sliding_spearmans_rank(x: np.ndarray,
                            y: np.ndarray,
-                           time_window: float,
-                           sample_rate: int,
-                           batch_size: Optional[int] = int(1.6e+7)) -> np.ndarray:
+                           time_window: Union[float, int],
+                           sample_rate: Union[float, int],
+                           batch_size: Optional[int] = int(1.6e+7),
+                           verbose: bool = False) -> np.ndarray:
     """
     Computes the Spearman's rank correlation coefficient between two 1D arrays `x` and `y`
     over sliding windows of size `time_window * sample_rate`. The computation is performed
@@ -413,7 +419,13 @@ def sliding_spearmans_rank(x: np.ndarray,
     >>> sliding_spearmans_rank(x, y, time_window=0.5, sample_rate=2)
     """
 
-    window_size = int(np.ceil(time_window * sample_rate))
+    timer = SimbaTimer(start=True)
+    check_valid_array(data=x, source=f'{sliding_spearmans_rank.__name__} x', accepted_ndims=(1,), accepted_dtypes=Formats.NUMERIC_DTYPES.value)
+    check_valid_array(data=y, source=f'{sliding_spearmans_rank.__name__} y', accepted_ndims=(1,), accepted_axis_0_shape=(x.shape[0],), accepted_dtypes=Formats.NUMERIC_DTYPES.value)
+    check_float(name=f'{sliding_spearmans_rank.__name__} time_window', value=time_window, allow_zero=False, allow_negative=False, raise_error=True)
+    check_float(name=f'{sliding_spearmans_rank.__name__} sample_rate', value=sample_rate, allow_zero=False, allow_negative=False, raise_error=True)
+    check_int(name=f'{sliding_spearmans_rank.__name__} batch_size', value=batch_size, allow_zero=False, allow_negative=False, raise_error=True)
+    window_size = np.int32(np.ceil(time_window * sample_rate))
     n = x.shape[0]
     results = cp.full(n, -1, dtype=cp.float32)
 
@@ -433,7 +445,11 @@ def sliding_spearmans_rank(x: np.ndarray,
 
         results[left + window_size - 1:right] = s
 
-    return cp.asnumpy(results)
+    r = cp.asnumpy(results)
+    timer.stop_timer()
+    if verbose: print(f'Sliding Spearmans rank for {x.shape[0]} observations computed (elapsed time: {timer.elapsed_time_str}s)')
+    return r
+
 
 
 
@@ -538,6 +554,12 @@ def euclidean_distance_to_static_point(data: np.ndarray,
     """
     Computes the Euclidean distance between each point in a given 2D array `data` and a static point using GPU acceleration.
 
+    .. seealso::
+       For CPU-based distance to static point (ROI center), see :func:`simba.mixins.feature_extraction_mixin.FeatureExtractionMixin.framewise_euclidean_distance_roi`
+       For CPU-based framewise Euclidean distance, see :func:`simba.mixins.feature_extraction_mixin.FeatureExtractionMixin.framewise_euclidean_distance`
+       For GPU CuPy solution for distance between two sets of points, see :func:`simba.data_processors.cuda.statistics.get_euclidean_distance_cupy`
+       For GPU numba CUDA solution for distance between two sets of points, see :func:`simba.data_processors.cuda.statistics.get_euclidean_distance_cuda`
+
     :param data: A 2D array of shape (N, 2), where N is the number of points, and each point is represented by its (x, y) coordinates. The array can represent pixel coordinates.
     :param point: A tuple of two integers representing the static point (x, y) in the same space as `data`.
     :param pixels_per_millimeter: A scaling factor that indicates how many pixels correspond to one millimeter. Defaults to 1 if no scaling is necessary.
@@ -789,13 +811,31 @@ def xie_beni(x: np.ndarray, y: np.ndarray) -> float:
     return xb
 
 
-def i_index(x: np.ndarray, y: np.ndarray):
+def i_index(x: np.ndarray, y: np.ndarray, verbose: bool = False) -> float:
     """
     Calculate the I-Index for evaluating clustering quality.
 
     The I-Index is a metric that measures the compactness and separation of clusters.
     A higher I-Index indicates better clustering with compact and well-separated clusters.
 
+    .. csv-table::
+       :header: EXPECTED RUNTIMES
+       :file: ../../../docs/tables/i_index_cuda.csv
+       :widths: 10, 45, 45
+       :align: center
+       :header-rows: 1
+
+    The I-Index is calculated as:
+
+    .. math::
+        I = \frac{SST}{k \times SWC}
+
+    where:
+
+    - :math:`SST = \sum_{i=1}^{n} \|x_i - \mu\|^2` is the total sum of squares (sum of squared distances from all points to the global centroid)
+    - :math:`k` is the number of clusters
+    - :math:`SWC = \sum_{c=1}^{k} \sum_{i \in c} \|x_i - \mu_c\|^2` is the within-cluster sum of squares (sum of squared distances from points to their cluster centroids)
+
     .. seealso::
        To compute Xie-Beni on the CPU, use :func:`~simba.mixins.statistics_mixin.Statistics.i_index`
 
@@ -806,17 +846,16 @@ def i_index(x: np.ndarray, y: np.ndarray):
 
     :references:
         .. [1] Zhao, Q., Xu, M., Fränti, P. (2009). Sum-of-Squares Based Cluster Validity Index and Significance Analysis.
-               In: Kolehmainen, M., Toivanen, P., Beliczynski, B. (eds) Adaptive and Natural Computing Algorithms. ICANNGA 2009.
-                Lecture Notes in Computer Science, vol 5495. Springer, Berlin, Heidelberg. https://doi.org/10.1007/978-3-642-04921-7_32
+               In: Kolehmainen, M., Toivanen, P., Beliczynski, B. (eds) Adaptive and Natural Computing Algorithms. ICANNGA 2009. Lecture Notes in Computer Science, vol 5495. Springer, Berlin, Heidelberg. https://doi.org/10.1007/978-3-642-04921-7_32
 
     :example:
     >>> X, y = make_blobs(n_samples=5000, centers=20, n_features=3, random_state=0, cluster_std=0.1)
     >>> i_index(x=X, y=y)
     """
+    timer = SimbaTimer(start=True)
     check_valid_array(data=x, accepted_ndims=(2,), accepted_dtypes=Formats.NUMERIC_DTYPES.value)
-    check_valid_array(data=y, accepted_ndims=(1,), accepted_dtypes=Formats.NUMERIC_DTYPES.value,
-                      accepted_axis_0_shape=[x.shape[0], ])
-    _ = get_unique_values_in_iterable(data=y, name=i_index.__name__, min=2)
+    check_valid_array(data=y, accepted_ndims=(1,), accepted_dtypes=Formats.NUMERIC_DTYPES.value, accepted_axis_0_shape=[x.shape[0], ])
+    cluster_cnt = get_unique_values_in_iterable(data=y, name=i_index.__name__, min=2)
     x, y = cp.array(x), cp.array(y)
     unique_y = cp.unique(y)
     n_y = unique_y.shape[0]
@@ -830,12 +869,16 @@ def i_index(x: np.ndarray, y: np.ndarray):
         swc += cp.sum(cp.linalg.norm(cluster_obs - cluster_centroid, axis=1) ** 2)
 
     i_idx = sst / (n_y * swc)
-
+    i_idx = np.float32(i_idx.get()) if hasattr(i_idx, 'get') else np.float32(i_idx)
+    timer.stop_timer()
+    if verbose: print(f'I-index for {x.shape[0]} observations in {cluster_cnt} clusters computed (elapsed time: {timer.elapsed_time_str}s)')
     return i_idx
 
-
-def kullback_leibler_divergence_gpu(x: np.ndarray, y: np.ndarray, fill_value: int = 1, bucket_method: Literal[
-    "fd", "doane", "auto", "scott", "stone", "rice", "sturges", "sqrt"] = "scott") -> float:
+def kullback_leibler_divergence_gpu(x: np.ndarray,
+                                    y: np.ndarray,
+                                    fill_value: int = 1,
+                                    bucket_method: Literal["fd", "doane", "auto", "scott", "stone", "rice", "sturges", "sqrt"] = "scott",
+                                    verbose: bool = False) -> float:
     """
     Compute Kullback-Leibler divergence between two distributions.
 
@@ -847,7 +890,6 @@ def kullback_leibler_divergence_gpu(x: np.ndarray, y: np.ndarray, fill_value: in
     .. seealso::
        For CPU implementation, see :func:`simba.mixins.statistics_mixin.Statistics.kullback_leibler_divergence`.
 
-
     :param ndarray x: First 1d array representing feature values.
     :param ndarray y: Second 1d array representing feature values.
     :param Optional[int] fill_value: Optional pseudo-value to use to fill empty buckets in ``y`` histogram
@@ -860,13 +902,18 @@ def kullback_leibler_divergence_gpu(x: np.ndarray, y: np.ndarray, fill_value: in
     >>> kl = kullback_leibler_divergence_gpu(x=x, y=y)
     """
 
+    timer = SimbaTimer(start=True)
+
     bin_width, bin_count = bucket_data(data=x, method=bucket_method)
     r = np.array([np.min(x), np.max(x)])
     x_hist = Statistics._hist_1d(data=x, bin_count=bin_count, range=r)
     y_hist = Statistics._hist_1d(data=y, bin_count=bin_count, range=r)
     y_hist[y_hist == 0] = fill_value
     x_hist, y_hist = x_hist / np.sum(x_hist), y_hist / np.sum(y_hist)
-    return kl_divergence_gpu(P=x_hist.astype(np.float32), Q=y_hist.astype(np.float32), convert_dtype=False)
+    r =  kl_divergence_gpu(P=x_hist.astype(np.float32), Q=y_hist.astype(np.float32), convert_dtype=False)
+    timer.stop_timer()
+    if verbose: print(f'KL divergence performed on {x.shape[0]} observations (elapsed time: {timer.elapsed_time_str}s)')
+    return r
 
 
 @cuda.jit()

simba/data_processors/cuda/timeseries.py

@@ -307,7 +307,7 @@ def sliding_hjort_parameters_gpu(data: np.ndarray, window_sizes: np.ndarray, sam
     """
     Compute Hjorth parameters over sliding windows on the GPU.
 
-    .. seelalso::
+    .. seealso::
        For CPU implementation, see :`simba.mixins.timeseries_features_mixin.TimeseriesFeatureMixin.hjort_parameters`
 
     :param np.ndarray data: 1D numeric array of signal data.

simba/data_processors/egocentric_aligner.py

@@ -7,7 +7,8 @@ import pandas as pd
 from simba.utils.checks import (check_if_dir_exists, check_if_valid_rgb_tuple,
                                 check_int, check_str, check_valid_boolean,
                                 check_valid_dataframe, check_valid_tuple)
-from simba.utils.data import egocentrically_align_pose_numba
+from simba.utils.data import (egocentrically_align_pose_numba, get_cpu_pool,
+                              terminate_cpu_pool)
 from simba.utils.enums import Formats, Options
 from simba.utils.errors import InvalidInputError
 from simba.utils.printing import SimbaTimer, stdout_success
@@ -51,7 +52,7 @@ class EgocentricalAligner():
     :param Optional[int] core_cnt: Number of CPU cores to use for video rotation; `-1` uses all available cores.
 
     :example:
-     >>> aligner = EgocentricalAligner(rotate_video=True, anchor_1='tail_base', anchor_2='nose', data_dir=r"/data_dir", videos_dir=r'/videos_dir', save_dir=r"/save_dir", video_info=r"C:\troubleshooting\mitra\project_folder\logs\video_info.csv", direction=0, anchor_location=(250, 250), fill_clr=(0, 0, 0))
+     >>> aligner = EgocentricalAligner(rotate_video=True, anchor_1='tail_base', anchor_2='nose', data_dir=r"/data_dir", videos_dir=r'/videos_dir', save_dir=r"/save_dir", video_info=r"C:/troubleshooting/mitra/project_folder/logs/video_info.csv", direction=0, anchor_location=(250, 250), fill_clr=(0, 0, 0))
      >>> aligner.run()
     """
 
@@ -73,7 +74,7 @@ class EgocentricalAligner():
         check_str(name=f'{self.__class__.__name__} anchor_1', value=anchor_1, allow_blank=False)
         check_str(name=f'{self.__class__.__name__} anchor_2', value=anchor_2, allow_blank=False)
         check_int(name=f'{self.__class__.__name__} core_cnt', value=core_cnt, min_value=-1, max_value=find_core_cnt()[0], unaccepted_vals=[0])
-        if core_cnt == -1: self.core_cnt = find_core_cnt()[0]
+        self.core_cnt = find_core_cnt()[0] if core_cnt == -1 or core_cnt > find_core_cnt()[0] else core_cnt
         check_int(name=f'{self.__class__.__name__} direction', value=direction, min_value=0, max_value=360)
         if isinstance(anchor_location, tuple):
             check_valid_tuple(x=anchor_location, source=f'{self.__class__.__name__} anchor_location', accepted_lengths=(2,), valid_dtypes=(int,))
@@ -98,6 +99,7 @@ class EgocentricalAligner():
 
     def run(self):
         timer = SimbaTimer(start=True)
+        self.pool = None if not self.rotate_video else get_cpu_pool(core_cnt=self.core_cnt, source=self.__class__.__name__)
         for file_cnt, file_path in enumerate(self.data_paths):
             video_timer = SimbaTimer(start=True)
             _, self.video_name, _ = get_fn_ext(filepath=file_path)
@@ -127,8 +129,7 @@ class EgocentricalAligner():
             if self.verbose:
                 print(f'{self.video_name} complete, saved at {save_path} (elapsed time: {video_timer.elapsed_time_str}s)')
             if self.rotate_video:
-                if self.verbose:
-                    print(f'Rotating video {self.video_name}...')
+                if self.verbose: print(f'Rotating video {self.video_name}...')
                 video_path = find_video_of_file(video_dir=self.videos_dir, filename=self.video_name, raise_error=False)
                 save_path = os.path.join(self.save_dir, f'{self.video_name}.mp4')
                 video_rotator = EgocentricVideoRotator(video_path=video_path,
@@ -139,11 +140,13 @@ class EgocentricalAligner():
                                                        gpu=self.gpu,
                                                        fill_clr=self.fill_clr,
                                                        core_cnt=self.core_cnt,
-                                                       save_path=save_path)
+                                                       save_path=save_path,
+                                                       pool=self.pool)
                 video_rotator.run()
             if self.verbose:
                 print(f'Rotated data for video {self.video_name} ({file_cnt+1}/{len(self.data_paths)}) saved in {self.save_dir}.')
         timer.stop_timer()
+        terminate_cpu_pool(pool=self.pool, source=self.__class__.__name__)
         stdout_success(msg=f'Egocentrically aligned data for {len(self.data_paths)} files saved in {self.save_dir}', elapsed_time=timer.elapsed_time_str)
 
 
@@ -156,9 +159,24 @@ class EgocentricalAligner():
 #                                   direction=0,
 #                                   gpu=True,
 #                                   anchor_location=(600, 300),
-#                                   fill_clr=(128,128,128))
+#                                   fill_clr=(128,128,128),
+#                                   core_cnt=18)
 #     aligner.run()
 
+
+if __name__ == "__main__":
+    aligner = EgocentricalAligner(anchor_1='butt/proximal tail',
+                                  anchor_2='snout',
+                                  data_dir=r'C:\troubleshooting\open_field_below\project_folder\csv\outlier_corrected_movement_location',
+                                  videos_dir=r'C:\troubleshooting\open_field_below\project_folder\videos',
+                                  save_dir=r"C:\troubleshooting\open_field_below\project_folder\videos\rotated",
+                                  direction=0,
+                                  gpu=True,
+                                  anchor_location=(600, 300),
+                                  fill_clr=(128,128,128),
+                                  core_cnt=18)
+    aligner.run()
+
 #     aligner = EgocentricalAligner(anchor_1='tail_base',
 #                                   anchor_2='nose',
 #                                   data_dir=r'C:\Users\sroni\OneDrive\Desktop\rotate_ex\data',

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_valid_boolean)
+                                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, get_current_time, find_files_of_filetypes_in_directory, remove_a_folder, copy_files_to_directory
+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
 
 

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/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/geometry_mixin.py

@@ -1556,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)
@@ -1622,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)
@@ -1693,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)
@@ -1763,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)
@@ -3525,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)
         """
 
@@ -3990,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)
@@ -4160,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

@@ -57,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]
@@ -77,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:
@@ -92,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:
@@ -1898,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)