roi metric sizes

docs/ROI_tutorial_new.md

@@ -306,6 +306,57 @@ Somtimes we may want to delete all ROI definitions in a SimBA project and start
 2. Click `Yes` to delete all ROI definitions in a SimBA project. 
 
 
+
+## DRAW SHAPES OF USER-DEFINED METRIC SIZES
+
+First, open the `File (ROI)` drop-down menu at the head of the `Region of interest` window and click the `Draw ROIs of pre-defined sizes` option.
+
+![predefined_sizes_1](https://github.com/user-attachments/assets/d57d09ee-a909-4ad4-a025-6e54ab00c35a)
+
+Once clicked, you should see the following pop-up opening allowing you to draw a range of different shapes with specified sizes. If you need a shape-type that is missing, consider letting us know through [Gitter](https://app.gitter.im/#/room/#SimBA-Resource_community:gitter.im) or by opening en issue on [GithHub](https://github.com/sgoldenlab/simba/issues/new?assignees=&labels=&projects=&template=feature_request.md&title=).
+
+![predefined_sizes_2](https://github.com/user-attachments/assets/c76037f3-f15c-430f-b552-fd945c15862b)
+
+In the `SETTINGS` frame, fill in the name of your ROI, and choose its color, thickness, and ear tag size. 
+
+#### DRAW A RECTANGLE OF SET SIZE
+
+To draw a RECTANGLE of set size, fill in its metric width and height in millimeter and click ``ADD RECTANGLE`` as in the video below:
+
+[predefined_sizes_rectangle.webm](https://github.com/user-attachments/assets/f669e54a-c8d7-4e2c-b2a9-bb39dd483b3f)
+
+#### DRAW A CIRCLE OF A SPECIFIC RADIUS
+
+To draw a CIRCLE with a specific radius, fill in its metric radius in millimeter and click ``ADD CIRCLE`` as in the video below:
+
+[predefined_sizes_circle.webm](https://github.com/user-attachments/assets/9c745aa3-20bf-49fb-8e65-90144ac7e3c7)
+
+#### DRAW A HEXAGON SPECIFIC RADIUS
+
+To draw a HEXAGON with a specific radius, fill in its metric radius in millimeter and click ``ADD HEXAGON`` as in the video below:
+
+[predefined_sizes_hexagon.webm](https://github.com/user-attachments/assets/eda60da0-693f-414e-95c5-51a7fc5a033c)
+
+#### DRAW A HALF CIRCLE POINTING NORTH
+
+To draw a HALF CIRCLE with a specific radius with its chunky part pointing UP, fill in its metric radius in millimeter, choose `NORTH` in the `direction drop-down menu`, and click ``ADD HALF CIRCLE`` as in the video below:
+
+[predefined_sizes_half_circle_north.webm](https://github.com/user-attachments/assets/d0323574-f163-4038-bfcd-b8f2e4595d0c)
+
+#### DRAW A HALF CIRCLE POINTING WEST
+
+To draw a HALF CIRCLE with a specific radius with its chunky part pointing LEFT, fill in its metric radius in millimeter, choose `WEST` in the `direction drop-down menu`, and click ``ADD HALF CIRCLE`` as in the video below:
+
+[predefined_sizes_half_circle_west.webm](https://github.com/user-attachments/assets/3127e41f-ca83-4617-8ed8-7d9b6ece4079)
+
+
+
+
+
+
+
+
+
 ## Next steps
 Once your ROI definitions are all defined, close the `ROI table`, `Regions of Interest Settings` and `Define Shape` windows and head back to the [ROI] tab in the load project menu. 
 

docs/predefined_roi_sizes_gui.md

@@ -0,0 +1,41 @@
+### DRAW SHAPES OF USER-DEFINED METRIC SIZES
+
+First, open the `File (ROI)` drop-down menu at the head of the `Region of interest` window and click the `Draw ROIs of pre-defined sizes` option.
+
+![predefined_sizes_1](https://github.com/user-attachments/assets/d57d09ee-a909-4ad4-a025-6e54ab00c35a)
+
+Once clicked, you should see the following pop-up opening allowing you to draw a range of different shapes with specified sizes. If you need a shape-type that is missing, consider letting us know through [Gitter](https://app.gitter.im/#/room/#SimBA-Resource_community:gitter.im) or by opening en issue on [GithHub](https://github.com/sgoldenlab/simba/issues/new?assignees=&labels=&projects=&template=feature_request.md&title=).
+
+![predefined_sizes_2](https://github.com/user-attachments/assets/c76037f3-f15c-430f-b552-fd945c15862b)
+
+In the `SETTINGS` frame, fill in the name of your ROI, and choose its color, thickness, and ear tag size. 
+
+#### DRAW A RECTANGLE OF SET SIZE
+
+To draw a RECTANGLE of set size, fill in its metric width and height in millimeter and click ``ADD RECTANGLE`` as in the video below:
+
+[predefined_sizes_rectangle.webm](https://github.com/user-attachments/assets/f669e54a-c8d7-4e2c-b2a9-bb39dd483b3f)
+
+#### DRAW A CIRCLE OF A SPECIFIC RADIUS
+
+To draw a CIRCLE with a specific radius, fill in its metric radius in millimeter and click ``ADD CIRCLE`` as in the video below:
+
+[predefined_sizes_circle.webm](https://github.com/user-attachments/assets/9c745aa3-20bf-49fb-8e65-90144ac7e3c7)
+
+#### DRAW A HEXAGON SPECIFIC RADIUS
+
+To draw a HEXAGON with a specific radius, fill in its metric radius in millimeter and click ``ADD HEXAGON`` as in the video below:
+
+[predefined_sizes_hexagon.webm](https://github.com/user-attachments/assets/eda60da0-693f-414e-95c5-51a7fc5a033c)
+
+#### DRAW A HALF CIRCLE POINTING NORTH
+
+To draw a HALF CIRCLE with a specific radius with its chunky part pointing UP, fill in its metric radius in millimeter, choose `NORTH` in the `direction drop-down menu`, and click ``ADD HALF CIRCLE`` as in the video below:
+
+[predefined_sizes_half_circle_north.webm](https://github.com/user-attachments/assets/d0323574-f163-4038-bfcd-b8f2e4595d0c)
+
+#### DRAW A HALF CIRCLE POINTING WEST
+
+To draw a HALF CIRCLE with a specific radius with its chunky part pointing LEFT, fill in its metric radius in millimeter, choose `WEST` in the `direction drop-down menu`, and click ``ADD HALF CIRCLE`` as in the video below:
+
+[predefined_sizes_half_circle_west.webm](https://github.com/user-attachments/assets/3127e41f-ca83-4617-8ed8-7d9b6ece4079)

setup.py

@@ -24,7 +24,7 @@
 # Setup configuration
 setuptools.setup(
     name="Simba-UW-tf-dev",
-    version="2.1.3",
+    version="2.1.4",
     author="Simon Nilsson, Jia Jie Choong, Sophia Hwang",
     author_email="[email protected]",
     description="Toolkit for computer classification and analysis of behaviors in experimental animals",

simba/data_processors/cuda/image.py

@@ -390,11 +390,10 @@ def stack_sliding_mse(x: np.ndarray,
     where the reference image is determined by a sliding window approach with a specified stride.
     The function is optimized for large image stacks by processing them in batches.
 
-    .. seelalso::
+    .. seealso::
        For CPU function see :func:`~simba.mixins.image_mixin.ImageMixin.img_stack_mse` and
        :func:`~simba.mixins.image_mixin.ImageMixin.img_sliding_mse`.
 
-
     :param np.ndarray x: Input array of images, where the first dimension corresponds to the stack of images. The array should be either 3D (height, width, channels) or 4D (batch, height, width, channels).
     :param Optional[int] stride: The stride or step size for the sliding window that determines the reference image. Defaults to 1, meaning the previous image in the stack is used as the reference.
     :param Optional[int] batch_size: The number of images to process in a single batch. Larger batch sizes may improve performance but require more GPU memory.  Defaults to 1000.

simba/mixins/circular_statistics.py

@@ -106,7 +106,8 @@ def sliding_mean_resultant_vector_length(data: np.ndarray, fps: float, time_wind
         :parameter np.ndarray data: 1D array of size len(data) representing degrees.
         :parameter np.ndarray time_window: Rolling time-window as float in seconds.
         :parameter int fps: fps of the recorded video
-        :returns np.ndarray: Size len(data) x len(time_windows) representing resultant vector length in the prior ``time_window``.
+        :returns: Size len(data) x len(time_windows) representing resultant vector length in the prior ``time_window``.
+        :rtype: np.ndarray
 
         :example:
         >>> data_1, data_2 = np.random.normal(loc=45, scale=1, size=100), np.random.normal(loc=90, scale=45, size=100)
@@ -163,12 +164,6 @@ def sliding_circular_mean(data: np.ndarray, time_windows: np.ndarray, fps: int)
         """
         Compute the circular mean in degrees within sliding temporal windows.
 
-        :parameter np.ndarray data: 1d array with feature values in degrees.
-        :parameter np.ndarray time_windows: Rolling time-windows as floats in seconds. E.g., [0.2, 0.4, 0.6]
-        :parameter int fps: fps of the recorded video
-        :returns: Size data.shape[0] x time_windows.shape[0] array
-        :rtype: np.ndarray
-
         .. image:: _static/img/mean_rolling_timeseries_angle.png
            :width: 600
            :align: center
@@ -182,6 +177,12 @@ def sliding_circular_mean(data: np.ndarray, time_windows: np.ndarray, fps: int)
            :func:`simba.mixins.circular_statistics.CircularStatisticsMixin.circular_mean`
 
 
+        :parameter np.ndarray data: 1d array with feature values in degrees.
+        :parameter np.ndarray time_windows: Rolling time-windows as floats in seconds. E.g., [0.2, 0.4, 0.6]
+        :parameter int fps: fps of the recorded video
+        :returns: Size data.shape[0] x time_windows.shape[0] array
+        :rtype: np.ndarray
+
         :example:
         >>> data = np.random.normal(loc=45, scale=1, size=20).astype(np.float32)
         >>> CircularStatisticsMixin().sliding_circular_mean(data=data,time_windows=np.array([0.5, 1.0]), fps=10)
@@ -204,10 +205,6 @@ def circular_std(data: np.ndarray) -> float:
         """
         Jitted compute of the circular standard deviation from a single distribution of angles in degrees.
 
-        :parameter ndarray data: 1D array of size len(frames) with angles in degrees
-        :returns: The standard deviation of the data sample in degrees.
-        :rtype: float
-
         .. image:: _static/img/circular_std.png
            :width: 600
            :align: center
@@ -222,6 +219,11 @@ def circular_std(data: np.ndarray) -> float:
 
         where \\(\\theta\\) represents the angles in radians
 
+
+        :parameter ndarray data: 1D array of size len(frames) with angles in degrees
+        :returns: The standard deviation of the data sample in degrees.
+        :rtype: float
+
         :example:
         >>> data = np.array([180, 221, 32, 42, 212, 101, 139, 41, 69, 171, 149, 200]).astype(np.float32)
         >>> CircularStatisticsMixin().circular_std(data=data)