simba-uw-tf-dev 4.6.2__py3-none-any.whl → 4.7.1__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
@@ -19,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:
-    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
@@ -38,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
 
@@ -227,7 +232,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 +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
@@ -413,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)
 
@@ -433,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
+
 
 
 
@@ -538,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.
@@ -789,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`
 
@@ -806,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]
@@ -830,12 +868,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 +889,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 +901,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/cue_light_analyzer.py

@@ -1,13 +1,9 @@
 __author__ = "Simon Nilsson; sronilsson@gmail.com"
 
 import functools
-import glob
-import itertools
 import multiprocessing
 import os
-import platform
-import time
-from typing import Dict, List, Optional, Union
+from typing import Dict, List, Union
 
 import cv2
 import numpy as np
@@ -17,9 +13,9 @@ from simba.mixins.config_reader import ConfigReader
 from simba.mixins.statistics_mixin import Statistics
 from simba.utils.checks import (
     check_all_file_names_are_represented_in_video_log, check_if_dir_exists,
-    check_if_valid_img, check_int, check_nvidea_gpu_available,
-    check_valid_boolean, check_valid_lst)
-from simba.utils.data import detect_bouts, slice_roi_dict_from_attribute
+    check_if_valid_img, check_int, check_valid_boolean, check_valid_lst)
+from simba.utils.data import (detect_bouts, slice_roi_dict_from_attribute,
+                              terminate_cpu_pool)
 from simba.utils.enums import Defaults, Keys
 from simba.utils.errors import NoROIDataError
 from simba.utils.printing import SimbaTimer, stdout_success
@@ -220,7 +216,7 @@ class CueLightAnalyzer(ConfigReader):
                         else: self.intensities[key] = subdict
                         if self.verbose:
                             print(f'Batch {int(np.ceil(cnt + 1 / self.core_cnt))} complete...')
-            pool.terminate(); pool.join()
+            terminate_cpu_pool(pool=pool, force=False)
             kmeans = self._get_kmeans(intensities=self.intensities)
             self.data_df = self._append_light_data(data_df=self.data_df, kmeans_data=kmeans)
             self.data_df = self._remove_outlier_events(data_df=self.data_df)

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

@@ -15,64 +15,74 @@ 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)
 
 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 +92,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 +126,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)