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

simba/data_processors/blob_location_computer.py

@@ -51,7 +51,7 @@ class BlobLocationComputer(object):
     :param Optional[bool] multiprocessing: If True, video background subtraction will be done using  multiprocessing. Default is False.
 
     :example:
-    >>> x = BlobLocationComputer(data_path=r"C:\troubleshooting\RAT_NOR\project_folder\videos\2022-06-20_NOB_DOT_4_downsampled_bg_subtracted.mp4", multiprocessing=True, gpu=True, batch_size=2000, save_dir=r"C:\blob_positions")
+    >>> x = BlobLocationComputer(data_path=r"C:/troubleshooting/RAT_NOR/project_folder/videos/2022-06-20_NOB_DOT_4_downsampled_bg_subtracted.mp4", multiprocessing=True, gpu=True, batch_size=2000, save_dir=r"C:/blob_positions")
     >>> x.run()
     """
     def __init__(self,

simba/data_processors/cuda/image.py

@@ -331,10 +331,12 @@ def _digital(data, results):
 
 def img_stack_brightness(x: np.ndarray,
                          method: Optional[Literal['photometric', 'digital']] = 'digital',
-                         ignore_black: Optional[bool] = True) -> np.ndarray:
+                         ignore_black: bool = True,
+                         verbose: bool = False) -> np.ndarray:
     """
     Calculate the average brightness of a stack of images using a specified method.
 
+    Useful for analyzing light cues or brightness changes over time. For example, compute brightness in images containing a light cue ROI, then perform clustering (e.g., k-means) on brightness values to identify frames when the light cue is on vs off.
 
     - **Photometric Method**: The brightness is calculated using the formula:
 
@@ -346,7 +348,7 @@ def img_stack_brightness(x: np.ndarray,
     .. math::
        \text{brightness} = 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
 
-    .. selalso::
+    .. seealso::
        For CPU function see :func:`~simba.mixins.image_mixin.ImageMixin.brightness_intensity`.
 
     :param np.ndarray x: A 4D array of images with dimensions (N, H, W, C), where N is the number of images, H and W are the height and width, and C is the number of channels (RGB).
@@ -363,7 +365,7 @@ def img_stack_brightness(x: np.ndarray,
 
     check_instance(source=img_stack_brightness.__name__, instance=x, accepted_types=(np.ndarray,))
     check_if_valid_img(data=x[0], source=img_stack_brightness.__name__)
-    x = np.ascontiguousarray(x).astype(np.uint8)
+    x, timer = np.ascontiguousarray(x).astype(np.uint8), SimbaTimer(start=True)
     if x.ndim == 4:
         grid_x = (x.shape[1] + 16 - 1) // 16
         grid_y = (x.shape[2] + 16 - 1) // 16
@@ -383,7 +385,8 @@ def img_stack_brightness(x: np.ndarray,
     else:
         results = deepcopy(x)
         results = np.mean(results, axis=(1, 2))
-
+    timer.stop_timer()
+    if verbose: print(f'Brightness computed in {results.shape[0]} images (elapsed time {timer.elapsed_time_str}s)')
     return results
 
 
@@ -1602,10 +1605,11 @@ def pose_plotter(data: Union[str, os.PathLike, np.ndarray],
 # SAVE_PATH = "/mnt/c/troubleshooting/mitra/project_folder/frames/output/pose_ex/test.mp4"
 #
 #
-DATA_PATH = "/mnt/d/troubleshooting/mitra/project_folder/csv/outlier_corrected_movement_location/592_MA147_CNO1_0515.csv"
-VIDEO_PATH = "/mnt/d/troubleshooting/mitra/project_folder/videos/592_MA147_CNO1_0515.mp4"
-SAVE_PATH = "/mnt/d/troubleshooting/mitra/project_folder/videos/test_cuda.mp4"
-pose_plotter(data=DATA_PATH, video_path=VIDEO_PATH, save_path=SAVE_PATH, circle_size=10, batch_size=100)
+if __name__ == "__main__":
+    DATA_PATH = "/mnt/d/troubleshooting/mitra/project_folder/csv/outlier_corrected_movement_location/592_MA147_CNO1_0515.csv"
+    VIDEO_PATH = "/mnt/d/troubleshooting/mitra/project_folder/videos/592_MA147_CNO1_0515.mp4"
+    SAVE_PATH = "/mnt/d/troubleshooting/mitra/project_folder/videos/test_cuda.mp4"
+    pose_plotter(data=DATA_PATH, video_path=VIDEO_PATH, save_path=SAVE_PATH, circle_size=10, batch_size=100)
 
 
 

simba/data_processors/cuda/statistics.py

@@ -3,7 +3,7 @@ __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
 
@@ -19,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 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
@@ -41,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
 
@@ -381,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
@@ -414,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)
 
@@ -434,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
+
 
 
 
@@ -539,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.
@@ -790,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`
 
@@ -807,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]
@@ -831,10 +869,11 @@ 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,

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

@@ -52,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()
     """
 

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

simba/feature_extractors/straub_tail_analyzer.py

@@ -44,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)

simba/mixins/statistics_mixin.py

@@ -3278,10 +3278,34 @@ class Statistics(FeatureExtractionMixin):
 
         Youden's J statistic is a measure of the overall performance of a binary classification test, taking into account both sensitivity (true positive rate) and specificity (true negative rate).
 
-        :param sample_1: The first binary array.
-        :param sample_2: The second binary array.
-        :return: Youden's J statistic.
+        The Youden's J statistic is calculated as:
+
+        .. math::
+            J = \text{sensitivity} + \text{specificity} - 1
+
+        where:
+
+        - :math:`\text{sensitivity} = \frac{TP}{TP + FN}` is the true positive rate
+        - :math:`\text{specificity} = \frac{TN}{TN + FP}` is the true negative rate
+
+        The statistic ranges from -1 to 1, where:
+        - :math:`J = 1` indicates perfect classification
+        - :math:`J = 0` indicates the test performs no better than random
+        - :math:`J < 0` indicates the test performs worse than random
+
+        :param sample_1: The first binary array (ground truth or reference).
+        :param sample_2: The second binary array (predictions or test results).
+        :return: Youden's J statistic. Returns NaN if either sensitivity or specificity cannot be calculated (division by zero).
         :rtype: float
+
+        :references:
+            .. [1] Youden, W. J. (1950). Index for rating diagnostic tests. Cancer, 3(1), 32-35.
+                   https://acsjournals.onlinelibrary.wiley.com/doi/abs/10.1002/1097-0142(1950)3:1%3C32::AID-CNCR2820030106%3E3.0.CO;2-3
+
+        :example:
+        >>> y_true = np.array([1, 1, 0, 0, 1, 0, 1, 1, 0, 0])
+        >>> y_pred = np.array([1, 1, 0, 1, 1, 0, 1, 0, 0, 0])
+        >>> j = Statistics.youden_j(sample_1=y_true, sample_2=y_pred)
         """
 
         check_valid_array(data=sample_1, source=f'{Statistics.youden_j.__name__} sample_1', accepted_ndims=(1,), accepted_values=[0, 1])
@@ -4257,7 +4281,7 @@ class Statistics(FeatureExtractionMixin):
         return separation_trace / compactness
 
     @staticmethod
-    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.
@@ -4282,9 +4306,10 @@ class Statistics(FeatureExtractionMixin):
         >>> X, y = make_blobs(n_samples=5000, centers=20, n_features=3, random_state=0, cluster_std=0.1)
         >>> Statistics.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=Statistics.i_index.__name__, min=2)
+        cluster_cnt = get_unique_values_in_iterable(data=y, name=Statistics.i_index.__name__, min=2)
         unique_y = np.unique(y)
         n_y = unique_y.shape[0]
         global_centroid = np.mean(x, axis=0)
@@ -4296,7 +4321,12 @@ class Statistics(FeatureExtractionMixin):
             cluster_centroid = np.mean(cluster_obs, axis=0)
             swc += np.sum(np.linalg.norm(cluster_obs - cluster_centroid, axis=1) ** 2)
 
-        return sst / (n_y * swc)
+
+        i_index = np.float32(sst / (n_y * swc))
+        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_index
+
 
     @staticmethod
     def sd_index(x: np.ndarray, y: np.ndarray) -> float:
@@ -5298,7 +5328,7 @@ class Statistics(FeatureExtractionMixin):
         """
         Compute one-way ANOVAs comparing each column (axis 1) on two arrays.
 
-        .. notes::
+        .. note::
            Use for computing and presenting aggregate statistics. Not suitable for featurization.
 
         .. seealso::
@@ -5336,7 +5366,7 @@ class Statistics(FeatureExtractionMixin):
         """
         Compute Kruskal-Wallis comparing each column (axis 1) on two arrays.
 
-        .. notes::
+        .. note::
            Use for computing and presenting aggregate statistics. Not suitable for featurization.
 
         .. seealso::
@@ -5373,7 +5403,7 @@ class Statistics(FeatureExtractionMixin):
         """
         Compute pairwise grouped Tukey-HSD tests.
 
-        .. notes::
+        .. note::
            Use for computing and presenting aggregate statistics. Not suitable for featurization.
 
         :param np.ndarray data: 2D array  with observations rowwise (axis 0) and features columnwise (axis 1)

simba/mixins/timeseries_features_mixin.py

@@ -2198,7 +2198,7 @@ class TimeseriesFeatureMixin(object):
         :example:
         >>> x = np.random.randint(0, 100, (400, 2))
         >>> results_1 = TimeseriesFeatureMixin.sliding_entropy_of_directional_changes(x=x, bins=16, window_size=5.0, sample_rate=30)
-        >>> x = pd.read_csv(r"C:\troubleshooting\two_black_animals_14bp\project_folder\csv\input_csv\Together_1.csv")[['Ear_left_1_x', 'Ear_left_1_y']].values
+        >>> x = pd.read_csv(r"C:/troubleshooting/two_black_animals_14bp/project_folder/csv/input_csv/Together_1.csv")[['Ear_left_1_x', 'Ear_left_1_y']].values
         >>> results_2 = TimeseriesFeatureMixin.sliding_entropy_of_directional_changes(x=x, bins=16, window_size=5.0, sample_rate=30)
         """