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

simba/assets/.recent_projects.txt

@@ -1,2 +1,3 @@
+E:/troubleshooting/mitra_emergence/project_folder/project_config.ini
 C:/troubleshooting/meberled/project_folder/project_config.ini
 C:/troubleshooting/mitra/project_folder/project_config.ini

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

@@ -11,12 +11,13 @@ from simba.mixins.feature_extraction_mixin import FeatureExtractionMixin
 from simba.mixins.timeseries_features_mixin import TimeseriesFeatureMixin
 from simba.utils.checks import (
     check_all_file_names_are_represented_in_video_log, check_if_dir_exists,
-    check_int, check_str, check_valid_dataframe)
+    check_str, check_valid_dataframe)
 from simba.utils.data import detect_bouts, plug_holes_shortest_bout
 from simba.utils.enums import Formats
 from simba.utils.printing import stdout_success
 from simba.utils.read_write import (find_files_of_filetypes_in_directory,
-                                    get_fn_ext, read_df, read_video_info)
+                                    get_current_time, get_fn_ext, read_df,
+                                    read_video_info)
 
 CIRCLING = 'CIRCLING'
 
@@ -58,30 +59,34 @@ class CirclingDetector(ConfigReader):
     """
 
     def __init__(self,
-                 data_dir: Union[str, os.PathLike],
                  config_path: Union[str, os.PathLike],
                  nose_name: Optional[str] = 'nose',
+                 data_dir: Optional[Union[str, os.PathLike]] = None,
                  left_ear_name: Optional[str] = 'left_ear',
                  right_ear_name: Optional[str] = 'right_ear',
                  tail_base_name: Optional[str] = 'tail_base',
                  center_name: Optional[str] = 'center',
-                 time_threshold: Optional[int] = 10,
-                 circular_range_threshold: Optional[int] = 320,
+                 time_threshold: Optional[int] = 7,
+                 circular_range_threshold: Optional[int] = 350,
+                 shortest_bout: int = 100,
                  movement_threshold: Optional[int] = 60,
                  save_dir: Optional[Union[str, os.PathLike]] = None):
 
-        check_if_dir_exists(in_dir=data_dir)
         for bp_name in [nose_name, left_ear_name, right_ear_name, tail_base_name]: check_str(name='body part name', value=bp_name, allow_blank=False)
-        self.data_paths = find_files_of_filetypes_in_directory(directory=data_dir, extensions=['.csv'])
         ConfigReader.__init__(self, config_path=config_path, read_video_info=True, create_logger=False)
+        if data_dir is not None:
+            check_if_dir_exists(in_dir=data_dir)
+        else:
+            data_dir = self.outlier_corrected_dir
+        self.data_paths = find_files_of_filetypes_in_directory(directory=data_dir, extensions=['.csv'])
         self.nose_heads = [f'{nose_name}_x'.lower(), f'{nose_name}_y'.lower()]
         self.left_ear_heads = [f'{left_ear_name}_x'.lower(), f'{left_ear_name}_y'.lower()]
         self.right_ear_heads = [f'{right_ear_name}_x'.lower(), f'{right_ear_name}_y'.lower()]
         self.center_heads = [f'{center_name}_x'.lower(), f'{center_name}_y'.lower()]
         self.required_field = self.nose_heads + self.left_ear_heads + self.right_ear_heads
-        self.save_dir = save_dir
+        self.save_dir, self.shortest_bout = save_dir, shortest_bout
         if self.save_dir is None:
-            self.save_dir = os.path.join(self.logs_path, f'circling_data_{self.datetime}')
+            self.save_dir = os.path.join(self.logs_path, f'circling_data_{time_threshold}s_{circular_range_threshold}d_{movement_threshold}mm_{self.datetime}')
             os.makedirs(self.save_dir)
         else:
             check_if_dir_exists(in_dir=self.save_dir)
@@ -93,7 +98,7 @@ class CirclingDetector(ConfigReader):
         check_all_file_names_are_represented_in_video_log(video_info_df=self.video_info_df, data_paths=self.data_paths)
         for file_cnt, file_path in enumerate(self.data_paths):
             video_name = get_fn_ext(filepath=file_path)[1]
-            print(f'Analyzing {video_name} ({file_cnt+1}/{len(self.data_paths)})...')
+            print(f'[{get_current_time()}] Analyzing circling {video_name}... (video {file_cnt+1}/{len(self.data_paths)})')
             save_file_path = os.path.join(self.save_dir, f'{video_name}.csv')
             df = read_df(file_path=file_path, file_type='csv').reset_index(drop=True)
             _, px_per_mm, fps = read_video_info(video_info_df=self.video_info_df, video_name=video_name)
@@ -115,11 +120,24 @@ class CirclingDetector(ConfigReader):
             circling_idx = np.argwhere(sliding_circular_range >= self.circular_range_threshold).astype(np.int32).flatten()
             movement_idx = np.argwhere(movement_sum >= self.movement_threshold).astype(np.int32).flatten()
             circling_idx = [x for x in movement_idx if x in circling_idx]
+            df[f'Probability_{CIRCLING}'] = 0
             df[CIRCLING] = 0
             df.loc[circling_idx, CIRCLING] = 1
+            df.loc[circling_idx, f'Probability_{CIRCLING}'] = 1
+            df = plug_holes_shortest_bout(data_df=df, clf_name=CIRCLING, fps=fps, shortest_bout=self.shortest_bout)
             bouts = detect_bouts(data_df=df, target_lst=[CIRCLING], fps=fps)
-            df = plug_holes_shortest_bout(data_df=df, clf_name=CIRCLING, fps=fps, shortest_bout=100)
+            if len(bouts) > 0:
+                df[CIRCLING] = 0
+                circling_idx = list(bouts.apply(lambda x: list(range(int(x["Start_frame"]), int(x["End_frame"]) + 1)), 1))
+                circling_idx = [x for xs in circling_idx for x in xs]
+                df.loc[circling_idx, CIRCLING] = 1
+                df.loc[circling_idx, f'Probability_{CIRCLING}'] = 1
+            else:
+                df[CIRCLING] = 0
+                circling_idx = []
+
             df.to_csv(save_file_path)
+            #print(video_name, len(circling_idx), round(len(circling_idx) / fps, 4), df[CIRCLING].sum())
             agg_results.loc[len(agg_results)] = [video_name, len(circling_idx), round(len(circling_idx) / fps, 4), len(bouts), round((len(circling_idx) / len(df)) * 100, 4), len(df), round(len(df)/fps, 2) ]
 
         agg_results.to_csv(agg_results_path)
@@ -127,7 +145,6 @@ class CirclingDetector(ConfigReader):
 
 #
 #
-# detector = CirclingDetector(data_dir=r'C:\troubleshooting\mitra\project_folder\csv\outlier_corrected_movement_location',
-#                             config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini")
+# detector = CirclingDetector(config_path=r"E:\troubleshooting\mitra_emergence\project_folder\project_config.ini")
 # detector.run()
 

simba/data_processors/cuda/image.py

@@ -331,10 +331,22 @@ 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,
+                         batch_size: int = 2500) -> 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.
+
+    .. csv-table::
+       :header: EXPECTED RUNTIMES
+       :file: ../../../docs/tables/img_stack_brightness_gpu.csv
+       :widths: 10, 45, 45
+       :align: center
+       :class: simba-table
+       :header-rows: 1
+
 
     - **Photometric Method**: The brightness is calculated using the formula:
 
@@ -346,7 +358,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,27 +375,42 @@ 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)
+    check_int(name=f'{img_stack_brightness.__name__} batch_size', value=batch_size, allow_zero=False, allow_negative=False, raise_error=True)
+    x, timer = np.ascontiguousarray(x).astype(np.uint8), SimbaTimer(start=True)
+    results = []
     if x.ndim == 4:
-        grid_x = (x.shape[1] + 16 - 1) // 16
-        grid_y = (x.shape[2] + 16 - 1) // 16
-        grid_z = x.shape[0]
-        threads_per_block = (16, 16, 1)
-        blocks_per_grid = (grid_y, grid_x, grid_z)
-        x_dev = cuda.to_device(x)
-        results = cuda.device_array((x.shape[0], x.shape[1], x.shape[2]), dtype=np.uint8)
-        if method == PHOTOMETRIC:
-            _photometric[blocks_per_grid, threads_per_block](x_dev, results)
+        batch_results_dev = cuda.device_array((batch_size, x.shape[1], x.shape[2]), dtype=np.uint8)
+    for batch_cnt, l in enumerate(range(0, x.shape[0], batch_size)):
+        r = l + batch_size
+        batch_x = x[l:r]
+        if batch_x.ndim == 4:
+            grid_x = (batch_x.shape[1] + 16 - 1) // 16
+            grid_y = (batch_x.shape[2] + 16 - 1) // 16
+            grid_z = batch_x.shape[0]
+            threads_per_block = (16, 16, 1)
+            blocks_per_grid = (grid_y, grid_x, grid_z)
+            x_dev = cuda.to_device(batch_x)
+            if method == PHOTOMETRIC:
+                _photometric[blocks_per_grid, threads_per_block](x_dev, batch_results_dev)
+            else:
+                _digital[blocks_per_grid, threads_per_block](x_dev, batch_results_dev)
+            batch_results_host = batch_results_dev.copy_to_host()[:batch_x.shape[0]]
+            batch_results_cp = cp.asarray(batch_results_host)
+            if ignore_black:
+                mask = batch_results_cp != 0
+                batch_results_cp = cp.where(mask, batch_results_cp, cp.nan)
+                batch_results = cp.nanmean(batch_results_cp, axis=(1, 2))
+                batch_results = cp.where(cp.isnan(batch_results), 0, batch_results)
+                batch_results = batch_results.get()
+            else:
+                batch_results = cp.mean(batch_results_cp, axis=(1, 2)).get()
         else:
-            _digital[blocks_per_grid, threads_per_block](x_dev, results)
-        results = results.copy_to_host()
-        if ignore_black:
-            masked_array = np.ma.masked_equal(results, 0)
-            results = np.mean(masked_array, axis=(1, 2)).filled(0)
-    else:
-        results = deepcopy(x)
-        results = np.mean(results, axis=(1, 2))
-
+            batch_results = deepcopy(x)
+            batch_results = np.mean(batch_results, axis=(1, 2))
+        results.append(batch_results)
+    timer.stop_timer()
+    results = np.concatenate(results) if len(results) > 0 else np.array([])
+    if verbose: print(f'Brightness computed in {results.shape[0]} images (elapsed time {timer.elapsed_time_str}s)')
     return results
 
 
@@ -1602,10 +1629,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
 
@@ -21,14 +21,17 @@ 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
@@ -40,8 +43,8 @@ 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)
+from simba.utils.checks import (check_float, check_int, check_str,
+                                check_valid_array, check_valid_tuple)
 from simba.utils.data import bucket_data
 from simba.utils.enums import Formats
 
@@ -381,9 +384,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 +418,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 +444,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 +553,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 +810,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 +845,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 +868,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/data_processors/freezing_detector.py

@@ -1,10 +1,8 @@
 import os
 from typing import Optional, Union
-
 import numpy as np
 import pandas as pd
 from numba import typed
-
 from simba.mixins.config_reader import ConfigReader
 from simba.mixins.feature_extraction_mixin import FeatureExtractionMixin
 from simba.mixins.timeseries_features_mixin import TimeseriesFeatureMixin
@@ -14,65 +12,73 @@ from simba.utils.checks import (
 from simba.utils.data import detect_bouts, plug_holes_shortest_bout
 from simba.utils.enums import Formats
 from simba.utils.printing import stdout_success
-from simba.utils.read_write import (find_files_of_filetypes_in_directory,
-                                    get_fn_ext, read_df, read_video_info)
+from simba.utils.read_write import (find_files_of_filetypes_in_directory, get_fn_ext, read_df, read_video_info, get_current_time)
 
 NAPE_X, NAPE_Y = 'nape_x', 'nape_y'
 FREEZING = 'FREEZING'
 
 class FreezingDetector(ConfigReader):
-
     """
-    Detect freezing behavior using heuristic rules.
-
+    Detect freezing behavior using heuristic rules based on movement velocity thresholds.
+    Analyzes pose-estimation data to detect freezing episodes by computing the mean velocity
+    of key body parts (nape, nose, and tail-base) and identifying periods where movement falls below
+    a specified threshold for a minimum duration.
     .. important::
-
         Freezing is detected as `present` when **the velocity (computed from the mean movement of the nape, nose, and tail-base body-parts) falls below
-        the movement threshold for the duration (and longer) of the specied time-window**.
-
+        the movement threshold for the duration (and longer) of the specified time-window**.
         Freezing is detected as `absent` when not present.
-
     .. note::
-
-       We pass the names of the left and right ears, as the method will use body-parts to compute the `nape` location of the animal.
-
-    :param Union[str, os.PathLike] data_dir: Path to directory containing pose-estimated body-part data in CSV format.
-    :param Union[str, os.PathLike] config_path: Path to SimBA project config file.
-    :param Optional[str] nose_name: The name of the pose-estimated nose body-part. Defaults to 'nose'.
-    :param Optional[str] left_ear_name: The name of the pose-estimated left ear body-part. Defaults to 'left_ear'.
-    :param Optional[str] right_ear_name: The name of the pose-estimated right ear body-part. Defaults to 'right_ear'.
-    :param Optional[str] tail_base_name: The name of the pose-estimated tail base body-part. Defaults to 'tail_base'.
-    :param Optional[int] time_window: The time window in preceding seconds in which to evaluate freezing. Default: 3.
-    :param Optional[int] movement_threshold: A movement threshold in millimeters per second. Defaults to 5.
-    :param Optional[Union[str, os.PathLike]] save_dir: Directory where to store the results. If None, then results are stored in the ``logs`` directory of the SimBA project.
-
+       The method uses the left and right ear body-parts to compute the `nape` location of the animal
+       as the midpoint between the ears. The nape, nose, and tail-base movements are averaged to compute
+       overall animal movement velocity.
+    :param Union[str, os.PathLike] data_dir: Path to directory containing pose-estimated body-part data in CSV format. Each CSV file should contain pose estimation data for one video.
+    :param Union[str, os.PathLike] config_path: Path to SimBA project config file (`.ini` format) containing project settings and video information.
+    :param Optional[str] nose_name: The name of the pose-estimated nose body-part column (without _x/_y suffix). Defaults to 'nose'.
+    :param Optional[str] left_ear_name: The name of the pose-estimated left ear body-part column (without _x/_y suffix). Defaults to 'Left_ear'.
+    :param Optional[str] right_ear_name: The name of the pose-estimated right ear body-part column (without _x/_y suffix). Defaults to 'right_ear'.
+    :param Optional[str] tail_base_name: The name of the pose-estimated tail base body-part column (without _x/_y suffix). Defaults to 'tail_base'.
+    :param Optional[int] time_window: The minimum time window in seconds that movement must be below the threshold to be considered freezing. Only freezing bouts lasting at least this duration are retained. Defaults to 3.
+    :param Optional[int] movement_threshold: Movement threshold in millimeters per second. Frames with mean velocity below this threshold are considered potential freezing. Defaults to 5.
+    :param Optional[int] shortest_bout: Minimum duration in milliseconds for a freezing bout to be considered valid. Shorter bouts are filtered out. Defaults to 100.
+    :param Optional[Union[str, os.PathLike]] save_dir: Directory where to store the results. If None, then results are stored in a timestamped subdirectory within the ``logs`` directory of the SimBA project.
+    :returns: None. Results are saved to CSV files in the specified save directory:
+        - Individual video results: One CSV file per video with freezing annotations added as a 'FREEZING' column (1 = freezing, 0 = not freezing)
+        - Aggregate results: `aggregate_freezing_results.csv` containing summary statistics for all videos
     :example:
-    >>> FreezingDetector(data_dir=r'D:\troubleshooting\mitra\project_folder\csv\outlier_corrected_movement_location', config_path=r"D:\troubleshooting\mitra\project_folder\project_config.ini")
-
+    >>> FreezingDetector(
+    ...     data_dir=r'D:\\troubleshooting\\mitra\\project_folder\\csv\\outlier_corrected_movement_location',
+    ...     config_path=r"D:\\troubleshooting\\mitra\\project_folder\\project_config.ini",
+    ...     time_window=3,
+    ...     movement_threshold=5,
+    ...     shortest_bout=100
+    ... ).run()
     References
     ----------
+    ..
     .. [1] Sabnis et al., Visual detection of seizures in mice using supervised machine learning, `biorxiv`, doi: https://doi.org/10.1101/2024.05.29.596520.
     .. [2] Lopez et al., Region-specific Nucleus Accumbens Dopamine Signals Encode Distinct Aspects of Avoidance Learning, `biorxiv`, doi: https://doi.org/10.1101/2024.08.28.610149
-    .. [3] Lopez, Gabriela C., Louis D. Van Camp, Ryan F. Kovaleski, et al. “Region-Specific Nucleus Accumbens Dopamine Signals Encode Distinct Aspects of Avoidance Learning.” `Cell Biology`, Volume 35, Issue 10p2433-2443.e5May 19, 2025. DOI: 10.1016/j.cub.2025.04.006
+    .. [3] Lopez, Gabriela C., Louis D. Van Camp, Ryan F. Kovaleski, et al. "Region-Specific Nucleus Accumbens Dopamine Signals Encode Distinct Aspects of Avoidance Learning." `Cell Biology`, Volume 35, Issue 10p2433-2443.e5May 19, 2025. DOI: 10.1016/j.cub.2025.04.006
     .. [4] Lazaro et al., Brainwide Genetic Capture for Conscious State Transitions, `biorxiv`, doi: https://doi.org/10.1101/2025.03.28.646066
+    .. [5] Sabnis et al., Visual detection of seizures in mice using supervised machine learning, 2025, Cell Reports Methods 5, 101242 December 15, 2025.
     """
-
     def __init__(self,
-                 data_dir: Union[str, os.PathLike],
                  config_path: Union[str, os.PathLike],
-                 nose_name: Optional[str] = 'nose',
-                 left_ear_name: Optional[str] = 'Left_ear',
-                 right_ear_name: Optional[str] = 'right_ear',
-                 tail_base_name: Optional[str] = 'tail_base',
-                 time_window: Optional[int] = 3,
-                 movement_threshold: Optional[int] = 5,
-                 shortest_bout: Optional[int] = 100,
+                 nose_name: str = 'nose',
+                 left_ear_name: str = 'Left_ear',
+                 right_ear_name: str = 'right_ear',
+                 tail_base_name: str = 'tail_base',
+                 data_dir: Optional[Union[str, os.PathLike]] = None,
+                 time_window: int = 4,
+                 movement_threshold: int = 5,
+                 shortest_bout: int = 100,
                  save_dir: Optional[Union[str, os.PathLike]] = None):
-
-        check_if_dir_exists(in_dir=data_dir)
         for bp_name in [nose_name, left_ear_name, right_ear_name, tail_base_name]: check_str(name='body part name', value=bp_name, allow_blank=False)
-        self.data_paths = find_files_of_filetypes_in_directory(directory=data_dir, extensions=['.csv'])
         ConfigReader.__init__(self, config_path=config_path, read_video_info=True, create_logger=False)
+        if data_dir is not None:
+            check_if_dir_exists(in_dir=data_dir)
+        else:
+            data_dir = self.outlier_corrected_dir
+        self.data_paths = find_files_of_filetypes_in_directory(directory=data_dir, extensions=['.csv'])
         self.nose_heads = [f'{nose_name}_x'.lower(), f'{nose_name}_y'.lower()]
         self.left_ear_heads = [f'{left_ear_name}_x'.lower(), f'{left_ear_name}_y'.lower()]
         self.right_ear_heads = [f'{right_ear_name}_x'.lower(), f'{right_ear_name}_y'.lower()]
@@ -82,21 +88,19 @@ class FreezingDetector(ConfigReader):
         check_int(name='movement_threshold', value=movement_threshold, min_value=1)
         self.save_dir = save_dir
         if self.save_dir is None:
-            self.save_dir = os.path.join(self.logs_path, f'freezing_data_time_{time_window}s_{self.datetime}')
+            self.save_dir = os.path.join(self.logs_path, f'freezing_data_time_{time_window}s_{movement_threshold}mm_{self.datetime}')
             os.makedirs(self.save_dir)
         else:
             check_if_dir_exists(in_dir=self.save_dir)
         self.time_window, self.movement_threshold = time_window, movement_threshold
         self.movement_threshold, self.shortest_bout = movement_threshold, shortest_bout
-        self.run()
-
     def run(self):
         agg_results = pd.DataFrame(columns=['VIDEO', 'FREEZING FRAMES', 'FREEZING TIME (S)', 'FREEZING BOUT COUNTS', 'FREEZING PCT OF SESSION', 'VIDEO TOTAL FRAMES', 'VIDEO TOTAL TIME (S)'])
-        agg_results_path = os.path.join(self.save_dir, 'aggregate_freezing_results.csv')
+        agg_results_path = os.path.join(self.save_dir, f'aggregate_freezing_results_{self.datetime}.csv')
         check_all_file_names_are_represented_in_video_log(video_info_df=self.video_info_df, data_paths=self.data_paths)
         for file_cnt, file_path in enumerate(self.data_paths):
             video_name = get_fn_ext(filepath=file_path)[1]
-            print(f'Analyzing {video_name}...({file_cnt+1}/{len(self.data_paths)})')
+            print(f'[{get_current_time()}] Analyzing freezing {video_name}...(video {file_cnt+1}/{len(self.data_paths)})')
             save_file_path = os.path.join(self.save_dir, f'{video_name}.csv')
             df = read_df(file_path=file_path, file_type='csv').reset_index(drop=True)
             _, px_per_mm, fps = read_video_info(vid_info_df=self.video_info_df, video_name=video_name)
@@ -118,23 +122,23 @@ class FreezingDetector(ConfigReader):
             mean_movement = np.mean(movement, axis=1)
             mm_s = TimeseriesFeatureMixin.sliding_descriptive_statistics(data=mean_movement.astype(np.float32), window_sizes=np.array([1], dtype=np.float64), sample_rate=int(fps), statistics=typed.List(["sum"]))[0].flatten()
             freezing_idx = np.argwhere(mm_s <= self.movement_threshold).astype(np.int32).flatten()
+            df[f'Probability_{FREEZING}'] = 0
             df[FREEZING] = 0
             df.loc[freezing_idx, FREEZING] = 1
             df = plug_holes_shortest_bout(data_df=df, clf_name=FREEZING, fps=fps, shortest_bout=self.shortest_bout)
             bouts = detect_bouts(data_df=df, target_lst=[FREEZING], fps=fps)
             bouts = bouts[bouts['Bout_time'] >= self.time_window]
             if len(bouts) > 0:
+                df[FREEZING] = 0
                 freezing_idx = list(bouts.apply(lambda x: list(range(int(x["Start_frame"]), int(x["End_frame"]) + 1)), 1))
                 freezing_idx = [x for xs in freezing_idx for x in xs]
                 df.loc[freezing_idx, FREEZING] = 1
+                df.loc[freezing_idx, f'Probability_{FREEZING}'] = 1
             else:
+                df[FREEZING] = 0
                 freezing_idx = []
             df.to_csv(save_file_path)
+            print(video_name, len(freezing_idx), round(len(freezing_idx) / fps, 4), df[FREEZING].sum())
             agg_results.loc[len(agg_results)] = [video_name, len(freezing_idx), round(len(freezing_idx) / fps, 4), len(bouts), round((len(freezing_idx) / len(df)) * 100, 4), len(df), round(len(df)/fps, 2) ]
-
         agg_results.to_csv(agg_results_path)
-        stdout_success(msg=f'Results saved in {self.save_dir} directory.')
-
-#
-# FreezingDetector(data_dir=r'C:\troubleshooting\mitra\project_folder\csv\outlier_corrected_movement_location',
-#                  config_path=r"C:\troubleshooting\mitra\project_folder\project_config.ini")
+        self.timer.stop_timer(); stdout_success(msg=f'Results saved in {self.save_dir} directory.', elapsed_time=self.timer.elapsed_time_str)

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