diff --git a/docs/spontaneous_alternation.md b/docs/spontaneous_alternation.md index a895a54c8..e950f33f6 100644 --- a/docs/spontaneous_alternation.md +++ b/docs/spontaneous_alternation.md @@ -1,7 +1,7 @@ #

Spontaneous Alternation in SimBA

- +

The SimBA spontaneous alternation interface allows users to compute detailed alternations data from pose-estimation data and user-defined ROIs. @@ -18,7 +18,7 @@ encompasses the center of the maze, and three or more arms that defines the arms and the center of the maze:

- +

# Analyzing Spontaneous Alternation in SimBA @@ -26,7 +26,7 @@ and the center of the maze: Onces the ROIs have been defined, click on the `SPONTANEOUS ALTERNATION` button in the ROI tab, and you should see the following pop-up:

- +

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,17 +40,19 @@ 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. -

+

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: -

+ +

+ - `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: -

+

- `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`. @@ -58,7 +60,7 @@ Onces the ROIs have been defined, click on the `SPONTANEOUS ALTERNATION` button 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.