Merge remote-tracking branch 'origin/master'

docs/spontaneous_alternation.md

@@ -1,7 +1,7 @@
 # <p align="center"> Spontaneous Alternation in SimBA </p>
 
 <p align="center">
-<img src="https://github.com/sgoldenlab/simba/blob/master/docs/_static/img/spontaneous_alternations.png" />
+  <img src="https://github.com/sgoldenlab/simba/blob/master/docs/_static/img/spontaneous_alternations.png" style="width: 400px;" />
 </p>
 
 The SimBA spontaneous alternation interface allows users to compute detailed alternations data from pose-estimation data and user-defined ROIs. 
@@ -18,15 +18,15 @@ encompasses the center of the maze, and three or more arms that defines the arms
 and the center of the maze:
 
 <p align="center">
-<img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_1.png" />
+  <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_1.png" style="width: 1000px;" />
 </p>
 
 # Analyzing Spontaneous Alternation in SimBA
 
 Onces the ROIs have been defined, click on the `SPONTANEOUS ALTERNATION` button in the ROI tab, and you should see the following pop-up:
 
 <p align="center">
-<img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_2.png" />
+  <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_2.png" style="width: 500px;" />
 </p>
 
 1) In the `ARM DEFINITIONS` frame, use the `MAZE ARM 1-3:` dropdown menus select the names of your ROIs that represents your three maze arms. 
@@ -40,25 +40,27 @@ Onces the ROIs have been defined, click on the `SPONTANEOUS ALTERNATION` button
 
   - `ANIMAL AREA (%)`: When detecting the location of the animal within the maze, SimBA will draw a "convex hull" or polygon around the animal that encapsulates all of the tracked body-parts, similar to how propriatory tools like [AnyMaze](https://www.any-maze.com/applications/y-maze/) compute spontaneous alternations.
 
-    <p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_3.png" /> </p>
+    <p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_3.png" style="width: 200px;" /> </p>
 
     The `ANIMAL AREA (%)` represents the percent of this area that have to enter, or exit, the maze arms or the maze center for it to count as an entry or an exit. Smaller `ANIMAL AREA (%)` values are likely to results in more arm entries and exits being counted.
     The below image may not be the most suited as it doesnt show a 3-arm maze, but it can help to visualize how `ANIMAL AREA (%)` represents a threshold value:
 
-    <p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_4.png" /> </p>
+
+    <p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_4.png" style="width: 500px;" /> </p>
+
 
   - `ANIMAL BUFFER (MM)`: As mentioned above, SimBA will draw a "convex hull" or polygon around the animal that encapsulates all of the tracked body-parts. Sometimes, you may want to extend the
     size if this polygon, and give it a little wriggle room, especially if you don't pose-estimate the outer boundaries of your animals. For example, in this image below, the original detected animal polygon is shown at the top, and the buffered polygon with N % is shown at the bottom:
 
-      <p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_5.png" /> </p>
+    <p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/spontaneous_alternation_5.png" style="width: 200px;" /> </p>
 
   - `SAVE DETAILED DATA`: Beyond the standard metrics (alternation rate, alternation count, same-arm return errors, alternate arm return errors), we may want data for specific arm combinations and exact frame count for when alternations or errors happened towards those arms and combinations. Setting this dropdown to `TRUE` will create one CSV file for each video inside the logs folder of your SimBA project within a subdirectory named something like `detailed_spontaneous_alternation_data_20240327141628`.
 
   - `VERBOSE`: This dropdown is helful for general troubleshooting. Setting thir dropdown to TRUE will print more information within each step of the processing pipeline.
 
 4) Once the above has been selected, click the `RUN ANALYSIS` button. You can follow the progress in the SimBA main window and the operating system terminal window. Every video represented in the `project_folder/csv/outlier_corrected_movement_location` will be analysed. Once complete, a CSV file will be stored in the logs folder of your SimBA project named something like `spontaneous_alternation_20240327145612.csv`. This file will have one row per video and columns representing alternation rate, alternation count, same-arm return error count, alternate arm return errors count. For an example file of expected output file with one analysed video, click [HERE](https://github.com/sgoldenlab/simba/blob/master/misc/spontaneous_alternation_20240327150723.csv).
 
-If you have selected `SAVE DETAILED DATA`, you will also get a further CSV file for each analysed video, documenting the frame counts when different errors and alternation sequences occured. For an example file of expected output of the detailed data, click [HERE](https://github.com/sgoldenlab/simba/blob/master/misc/spontaneous_alternation_detailed_data_ex.csv)
+If you have selected `SAVE DETAILED DATA`, you will also get two further CSV files for each analysed video, documenting the frame counts when different errors and alternation sequences occured. For an example file of expected output of the detailed data, click [HERE](https://github.com/sgoldenlab/simba/blob/master/misc/spontaneous_alternation_detailed_data_ex.csv). You will also get another CSV file for each analyzed video, documenting the sequence of arm entries, together with the frame and time the animal entered the specific arm. For an example of the expected file, click [HERE](https://github.com/sgoldenlab/simba/blob/master/misc/spontaneous_alternation_arm_entry_sequence.csv). 
 
 
 5) We may want to visualize the spontanous alternation for some videos to make sure the alternation counts and errors as counted by SimBa matches up with manual scoring.

simba/data_processors/spontaneous_alternation_calculator.py

@@ -15,13 +15,13 @@
 from simba.mixins.feature_extraction_supplement_mixin import \
     FeatureExtractionSupplemental
 from simba.mixins.geometry_mixin import GeometryMixin
-from simba.utils.checks import (check_float, check_int, check_str,
-                                check_valid_lst, check_video_has_rois, check_all_file_names_are_represented_in_video_log)
+from simba.utils.checks import (
+    check_all_file_names_are_represented_in_video_log, check_float, check_int,
+    check_str, check_valid_lst, check_video_has_rois)
 from simba.utils.errors import (AnimalNumberError, InvalidInputError,
                                 NoFilesFoundError, ROICoordinatesNotFoundError)
 from simba.utils.printing import stdout_success
-from simba.utils.read_write import (get_fn_ext, read_df, read_data_paths)
-
+from simba.utils.read_write import get_fn_ext, read_data_paths, read_df
 from simba.utils.warnings import NoFileFoundWarning
 
 TAIL_END = "tail_end"

simba/plotting/probability_plot_creator.py

@@ -1,19 +1,22 @@
 __author__ = "Simon Nilsson"
 
 import os
-from typing import Dict, List, Union, Optional, Any
+from typing import Any, Dict, List, Optional, Union
+
 import cv2
 import numpy as np
 
 from simba.mixins.config_reader import ConfigReader
 from simba.mixins.plotting_mixin import PlottingMixin
-from simba.utils.checks import (check_that_column_exist, check_file_exist_and_readable, check_valid_lst, check_if_keys_exist_in_dict, check_str, check_all_file_names_are_represented_in_video_log)
+from simba.utils.checks import (
+    check_all_file_names_are_represented_in_video_log,
+    check_file_exist_and_readable, check_if_keys_exist_in_dict, check_str,
+    check_that_column_exist, check_valid_lst)
 from simba.utils.enums import Formats
 from simba.utils.errors import NoSpecifiedOutputError
 from simba.utils.printing import SimbaTimer, stdout_success
 from simba.utils.read_write import get_fn_ext, read_df
 
-
 STYLE_WIDTH = 'width'
 STYLE_HEIGHT = 'height'
 STYLE_FONT_SIZE = 'font size'

simba/plotting/probability_plot_creator_mp.py

@@ -5,7 +5,7 @@
 import os
 import platform
 import shutil
-from typing import Any, Dict, List, Optional, Union, Tuple
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import cv2
 import numpy as np
@@ -14,15 +14,15 @@
 from simba.mixins.config_reader import ConfigReader
 from simba.mixins.plotting_mixin import PlottingMixin
 from simba.utils.checks import (
-    check_all_file_names_are_represented_in_video_log, check_int, check_str,
-    check_that_column_exist, check_valid_lst, check_if_keys_exist_in_dict)
+    check_all_file_names_are_represented_in_video_log,
+    check_if_keys_exist_in_dict, check_int, check_str, check_that_column_exist,
+    check_valid_lst)
 from simba.utils.enums import Formats
 from simba.utils.errors import NoSpecifiedOutputError
 from simba.utils.printing import SimbaTimer, stdout_success
 from simba.utils.read_write import (concatenate_videos_in_folder,
                                     find_core_cnt, get_fn_ext, read_df)
 
-
 STYLE_WIDTH = 'width'
 STYLE_HEIGHT = 'height'
 STYLE_FONT_SIZE = 'font size'

simba/third_party_label_appenders/third_party_appender.py

@@ -2,41 +2,39 @@
 
 import os
 from copy import deepcopy
-from typing import Union, Dict, Optional
+from typing import Dict, Optional, Union
+
 try:
     from typing import Literal
 except:
     from typing_extensions import Literal
 
 import pandas as pd
+
 from simba.mixins.config_reader import ConfigReader
-from simba.third_party_label_appenders.tools import (check_stop_events_prior_to_start_events,
-                                                     fix_uneven_start_stop_count,
-                                                     read_bento_files,
-                                                     read_boris_annotation_files,
-                                                     read_deepethogram_files,
-                                                     read_ethovision_files,
-                                                     read_observer_files,
-                                                     read_solomon_files)
-from simba.utils.checks import (check_if_dir_exists,check_if_filepath_list_is_empty, check_str, check_instance)
+from simba.third_party_label_appenders.tools import (
+    check_stop_events_prior_to_start_events, fix_uneven_start_stop_count,
+    read_bento_files, read_boris_annotation_files, read_deepethogram_files,
+    read_ethovision_files, read_observer_files, read_solomon_files)
+from simba.utils.checks import (check_if_dir_exists,
+                                check_if_filepath_list_is_empty,
+                                check_instance, check_str)
 from simba.utils.enums import Methods
-from simba.utils.errors import (ThirdPartyAnnotationEventCountError,
-                                ThirdPartyAnnotationFileNotFoundError,
-                                ThirdPartyAnnotationOverlapError,
-                                ThirdPartyAnnotationsAdditionalClfError,
-                                ThirdPartyAnnotationsMissingAnnotationsError,
-                                ThirdPartyAnnotationsOutsidePoseEstimationDataError)
+from simba.utils.errors import (
+    ThirdPartyAnnotationEventCountError, ThirdPartyAnnotationFileNotFoundError,
+    ThirdPartyAnnotationOverlapError, ThirdPartyAnnotationsAdditionalClfError,
+    ThirdPartyAnnotationsMissingAnnotationsError,
+    ThirdPartyAnnotationsOutsidePoseEstimationDataError)
 from simba.utils.printing import stdout_success
-from simba.utils.read_write import (get_fn_ext,
-                                    read_df,
-                                    write_df,
-                                    find_files_of_filetypes_in_directory)
-from simba.utils.warnings import (ThirdPartyAnnotationEventCountWarning,
-                                  ThirdPartyAnnotationFileNotFoundWarning,
-                                  ThirdPartyAnnotationOverlapWarning,
-                                  ThirdPartyAnnotationsAdditionalClfWarning,
-                                  ThirdPartyAnnotationsMissingAnnotationsWarning,
-                                  ThirdPartyAnnotationsOutsidePoseEstimationDataWarning)
+from simba.utils.read_write import (find_files_of_filetypes_in_directory,
+                                    get_fn_ext, read_df, write_df)
+from simba.utils.warnings import (
+    ThirdPartyAnnotationEventCountWarning,
+    ThirdPartyAnnotationFileNotFoundWarning,
+    ThirdPartyAnnotationOverlapWarning,
+    ThirdPartyAnnotationsAdditionalClfWarning,
+    ThirdPartyAnnotationsMissingAnnotationsWarning,
+    ThirdPartyAnnotationsOutsidePoseEstimationDataWarning)
 
 BORIS = "BORIS"
 DEEPETHOGRAM = "DEEPETHOGRAM"

simba/ui/pop_ups/clf_probability_plot_pop_up.py

@@ -1,9 +1,9 @@
 __author__ = "Simon Nilsson"
 
 import os
+import threading
 from tkinter import *
 from typing import Union
-import threading
 
 from simba.mixins.config_reader import ConfigReader
 from simba.mixins.pop_up_mixin import PopUpMixin
@@ -15,10 +15,9 @@
                                         Entry_Box)
 from simba.utils.checks import check_int
 from simba.utils.enums import Formats, Keys, Links, Paths
-from simba.utils.read_write import (check_if_filepath_list_is_empty, get_file_name_info_in_directory)
 from simba.utils.lookups import get_color_dict
-
-
+from simba.utils.read_write import (check_if_filepath_list_is_empty,
+                                    get_file_name_info_in_directory)
 
 STYLE_WIDTH = 'width'
 STYLE_HEIGHT = 'height'

simba/ui/pop_ups/third_party_annotator_appender_pop_up.py

@@ -1,14 +1,16 @@
 __author__ = "Simon Nilsson"
 
 import os
+import threading
 from tkinter import *
 from typing import Union
-import threading
 
 from simba.mixins.config_reader import ConfigReader
 from simba.mixins.pop_up_mixin import PopUpMixin
-from simba.third_party_label_appenders.third_party_appender import ThirdPartyLabelAppender
-from simba.ui.tkinter_functions import (CreateLabelFrameWithIcon, DropDownMenu, FolderSelect)
+from simba.third_party_label_appenders.third_party_appender import \
+    ThirdPartyLabelAppender
+from simba.ui.tkinter_functions import (CreateLabelFrameWithIcon, DropDownMenu,
+                                        FolderSelect)
 from simba.utils.checks import check_if_dir_exists
 from simba.utils.enums import Formats, Keys, Links, Options
 from simba.utils.lookups import get_third_party_appender_file_formats