autogaita 1.2.0__tar.gz → 1.3.1__tar.gz

{autogaita-1.2.0 → autogaita-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: autogaita
-Version: 1.2.0
+Version: 1.3.1
 Summary: Automatic Gait Analysis in Python. A toolbox to streamline and standardise the analysis of kinematics across species after ML-based body posture tracking. Despite being optimised for gait analyses, AutoGaitA has the potential to be used for any kind of kinematic analysis.
 Home-page: https://github.com/mahan-hosseini/AutoGaitA/
 Author: Mahan Hosseini

{autogaita-1.2.0 → autogaita-1.3.1}/autogaita/common2D/common2D_1_preparation.py

@@ -45,6 +45,8 @@ def some_prep(tracking_software, info, folderinfo, cfg):
     subtract_beam = cfg["subtract_beam"]
     convert_to_mm = cfg["convert_to_mm"]
     pixel_to_mm_ratio = cfg["pixel_to_mm_ratio"]
+    x_sc_broken_threshold = cfg["x_sc_broken_threshold"]
+    y_sc_broken_threshold = cfg["y_sc_broken_threshold"]
     standardise_y_at_SC_level = cfg["standardise_y_at_SC_level"]
     invert_y_axis = cfg["invert_y_axis"]
     flip_gait_direction = cfg["flip_gait_direction"]
@@ -196,7 +198,11 @@ def some_prep(tracking_software, info, folderinfo, cfg):
     config_vars_to_json = {
         "sampling_rate": sampling_rate,
         "convert_to_mm": convert_to_mm,
+        "pixel_to_mm_ratio": pixel_to_mm_ratio,
+        "x_sc_broken_threshold": x_sc_broken_threshold,
+        "y_sc_broken_threshold": y_sc_broken_threshold,
         "standardise_y_at_SC_level": standardise_y_at_SC_level,
+        "flip_gait_direction": flip_gait_direction,
         "analyse_average_x": analyse_average_x,
         "standardise_x_coordinates": standardise_x_coordinates,
         "x_standardisation_joint": x_standardisation_joint,
@@ -402,11 +408,20 @@ def check_this_filename_configuration(
     prerun_string = folderinfo["prerun_string"]
     whichvideo = ""  # initialise
     found_it = False
+    # handle leading zeros that we identified previously - if none convert nums to str
+    if "leading_mouse_num_zeros" in info.keys():
+        mouse_num = info["leading_mouse_num_zeros"] + str(mouse_num)
+    else:
+        mouse_num = str(mouse_num)
+    if "leading_run_num_zeros" in info.keys():
+        run_num = info["leading_run_num_zeros"] + str(run_num)
+    else:
+        run_num = str(run_num)
     for filename in os.listdir(root_dir):
         # the following condition is True for data & beam csv
         if (
-            (premouse_string + str(mouse_num) + postmouse_string in filename)
-            and (prerun_string + str(run_num) + postrun_string in filename)
+            (premouse_string + mouse_num + postmouse_string in filename)
+            and (prerun_string + run_num + postrun_string in filename)
             and (filename.endswith(file_type_string))
         ):
             found_it = True

{autogaita-1.2.0 → autogaita-1.3.1}/autogaita/common2D/common2D_2_sc_extraction.py

@@ -4,6 +4,7 @@ from autogaita.common2D.common2D_utils import (
     check_cycle_out_of_bounds,
     check_cycle_duplicates,
     check_cycle_order,
+    check_differing_angle_joint_coords,
     check_tracking_xy_thresholds,
     check_tracking_SLEAP_nans,
     handle_issues,
@@ -208,14 +209,25 @@ def extract_stepcycles(tracking_software, data, info, folderinfo, cfg):
     # ............................  clean all_cycles  ..................................
     # check if we skipped latencies because they were out of data-bounds
     all_cycles = check_cycle_out_of_bounds(all_cycles)
-    if all_cycles:  # can be None if all SCs were out of bounds
-        # check if there are any duplicates (e.g., SC2's start-lat == SC1's end-lat)
-        all_cycles = check_cycle_duplicates(all_cycles)
-        # check if user input progressively later latencies
-        all_cycles = check_cycle_order(all_cycles, info)
-        # check if tracking broke for any SCs using user-provided x and y thresholds
-        all_cycles = check_tracking_xy_thresholds(data, info, all_cycles, cfg)
-        # for SLEAP - check if there were any NaNs in any joints/angle-joints in SCs
-        if tracking_software == "SLEAP":
-            all_cycles = check_tracking_SLEAP_nans(data, info, all_cycles, cfg)
+    if not all_cycles:  # returns None if no clean cycles found
+        return None
+    # check if there are any duplicates (e.g., SC2's start-lat == SC1's end-lat)
+    all_cycles = check_cycle_duplicates(all_cycles)  # doesnt return None!
+    # check if user input progressively later latencies
+    all_cycles = check_cycle_order(all_cycles, info)
+    if not all_cycles:  # returns empty list if no clean cycles found
+        return None
+    # check that joints used in angle computations have different coords at all tps
+    all_cycles = check_differing_angle_joint_coords(all_cycles, data, info, cfg)
+    if not all_cycles:
+        return None
+    # check if tracking broke for any SCs using user-provided x and y thresholds
+    all_cycles = check_tracking_xy_thresholds(all_cycles, data, info, cfg)
+    if not all_cycles:
+        return None
+    # for SLEAP - check if there were any NaNs in any joints/angle-joints in SCs
+    if tracking_software == "SLEAP":
+        all_cycles = check_tracking_SLEAP_nans(all_cycles, data, info, cfg)
+        if not all_cycles:
+            return None
     return all_cycles

{autogaita-1.2.0 → autogaita-1.3.1}/autogaita/common2D/common2D_3_analysis.py

@@ -1,10 +1,13 @@
 # %% imports
-from autogaita.resources.utils import bin_num_to_percentages
+from autogaita.resources.utils import (
+    bin_num_to_percentages,
+    compute_angle,
+    write_angle_warning,
+)
 import os
 import warnings
 import pandas as pd
 import numpy as np
-import math
 
 # %% constants
 from autogaita.resources.constants import TIME_COL, SC_PERCENTAGE_COL
@@ -50,14 +53,14 @@ def analyse_and_export_stepcycles(data, all_cycles, info, cfg):
         this_step = data_copy.loc[all_cycles[0][0] : all_cycles[0][1]]
         if standardise_x_coordinates:
             all_steps_data, x_standardised_steps_data = (
-                standardise_x_y_and_add_features_to_one_step(this_step, cfg)
+                standardise_x_y_and_add_features_to_one_step(this_step, info, cfg)
             )
             normalised_steps_data = normalise_one_steps_data(
                 x_standardised_steps_data, bin_num
             )
         else:
             all_steps_data = standardise_x_y_and_add_features_to_one_step(
-                this_step, cfg
+                this_step, info, cfg
             )
             normalised_steps_data = normalise_one_steps_data(all_steps_data, bin_num)
     # 2 or more steps - build dataframe
@@ -69,14 +72,14 @@ def analyse_and_export_stepcycles(data, all_cycles, info, cfg):
         first_step = data_copy.loc[all_cycles[0][0] : all_cycles[0][1]]
         if standardise_x_coordinates:
             all_steps_data, x_standardised_steps_data = (
-                standardise_x_y_and_add_features_to_one_step(first_step, cfg)
+                standardise_x_y_and_add_features_to_one_step(first_step, info, cfg)
             )
             normalised_steps_data = normalise_one_steps_data(
                 x_standardised_steps_data, bin_num
             )
         else:
             all_steps_data = standardise_x_y_and_add_features_to_one_step(
-                first_step, cfg
+                first_step, info, cfg
             )
             normalised_steps_data = normalise_one_steps_data(all_steps_data, bin_num)
         # some prep for addition of further steps
@@ -98,13 +101,15 @@ def analyse_and_export_stepcycles(data, all_cycles, info, cfg):
             this_step = data_copy.loc[all_cycles[s][0] : all_cycles[s][1]]
             if standardise_x_coordinates:
                 this_step, this_x_standardised_step = (
-                    standardise_x_y_and_add_features_to_one_step(this_step, cfg)
+                    standardise_x_y_and_add_features_to_one_step(this_step, info, cfg)
                 )
                 this_normalised_step = normalise_one_steps_data(
                     this_x_standardised_step, bin_num
                 )
             else:
-                this_step = standardise_x_y_and_add_features_to_one_step(this_step, cfg)
+                this_step = standardise_x_y_and_add_features_to_one_step(
+                    this_step, info, cfg
+                )
                 this_normalised_step = normalise_one_steps_data(this_step, bin_num)
             # step separators & step-to-rest-concatenation
             # => note that normalised_step is already based on x-stand if required
@@ -170,7 +175,7 @@ def analyse_and_export_stepcycles(data, all_cycles, info, cfg):
 # ......................................................................................
 
 
-def standardise_x_y_and_add_features_to_one_step(step, cfg):
+def standardise_x_y_and_add_features_to_one_step(step, info, cfg):
     """For a single step cycle's data, standardise x & y if wanted and add features"""
     # if user wanted this, standardise y (height) at step-cycle level
     step_copy = step.copy()
@@ -184,11 +189,11 @@ def standardise_x_y_and_add_features_to_one_step(step, cfg):
         step_copy[y_cols] -= this_y_min
     # if no x-standardisation, just add features & return non-(x-)normalised step
     if cfg["standardise_x_coordinates"] is False:
-        non_stand_step = add_features(step_copy, cfg)
+        non_stand_step = add_features(step_copy, info, cfg)
         return non_stand_step
         # else standardise x (horizontal dimension) at step-cycle level too
     else:
-        non_stand_step = add_features(step_copy, cfg)
+        non_stand_step = add_features(step_copy, info, cfg)
         x_stand_step = step_copy.copy()
         x_cols = [col for col in x_stand_step.columns if col.endswith("x")]
         # note the [0] here is important because it's still a list of len=1!!
@@ -196,11 +201,11 @@ def standardise_x_y_and_add_features_to_one_step(step, cfg):
             cfg["x_standardisation_joint"][0] + "x"
         ].min()
         x_stand_step[x_cols] -= min_x_standardisation_joint
-        x_stand_step = add_features(x_stand_step, cfg)
+        x_stand_step = add_features(x_stand_step, info, cfg)
         return non_stand_step, x_stand_step
 
 
-def add_features(step, cfg):
+def add_features(step, info, cfg):
     """Add Features, i.e. Angles & Velocities"""
     # unpack
     hind_joints = cfg["hind_joints"]
@@ -208,12 +213,12 @@ def add_features(step, cfg):
     if hind_joints:
         step = add_x_velocities(step, cfg)
     if angles["name"]:  # if there is at least 1 string in the list
-        step = add_angles(step, cfg)
+        step = add_angles(step, info, cfg)
         step = add_angular_velocities(step, cfg)
     return step
 
 
-def add_angles(step, cfg):
+def add_angles(step, info, cfg):
     """Feature #1: Joint Angles"""
     # unpack
     angles = cfg["angles"]
@@ -234,26 +239,20 @@ def add_angles(step, cfg):
         joint3[:, 1] = step[upper_joint + "y"]
         # initialise the angle vector and assign looping over timepoints
         this_angle = np.zeros(len(joint_angle))
+        broken_angle_idxs = []  # initialise broken idxs-list for each angle anew
         for t in range(len(joint_angle)):
-            this_angle[t] = compute_angle(joint_angle[t, :], joint2[t, :], joint3[t, :])
+            this_angle[t], broken = compute_angle(
+                joint_angle[t, :], joint2[t, :], joint3[t, :]
+            )
+            if broken:
+                broken_angle_idxs.append(t)
+        if broken_angle_idxs:
+            write_angle_warning(step, a, angles, broken_angle_idxs, info)
         this_colname = angle + "Angle"
         step[this_colname] = this_angle
     return step
 
 
-def compute_angle(joint_angle, joint2, joint3):
-    """Compute a given angle at a joint & a given timepoint"""
-    # Get vectors between the joints
-    v1 = (joint_angle[0] - joint2[0], joint_angle[1] - joint2[1])
-    v2 = (joint_angle[0] - joint3[0], joint_angle[1] - joint3[1])
-    # dot product, magnitude of vectors, angle in radians & convert 2 degrees
-    dot_product = v1[0] * v2[0] + v1[1] * v2[1]
-    mag_v1 = math.sqrt(v1[0] ** 2 + v1[1] ** 2)
-    mag_v2 = math.sqrt(v2[0] ** 2 + v2[1] ** 2)
-    angle = math.acos(dot_product / (mag_v1 * mag_v2))
-    return math.degrees(angle)
-
-
 def add_x_velocities(step, cfg):
     """Feature #2: Joint x Velocities & Accelerations"""
     # unpack

{autogaita-1.2.0 → autogaita-1.3.1}/autogaita/common2D/common2D_utils.py

@@ -6,6 +6,9 @@ import copy
 import numpy as np
 import tkinter as tk
 
+# %% constants
+from autogaita.resources.constants import TIME_COL
+
 
 def run_singlerun_in_multirun(tracking_software, idx, info, folderinfo, cfg):
     """When performing a multirun, either via Batch Analysis in GUI or batchrun scripts, run the analysis for a given dataset"""
@@ -61,7 +64,7 @@ def extract_info(tracking_software, folderinfo, in_GUI=False):
             for string_addition in FILE_ID_STRING_ADDITIONS:
                 try:
                     candidate_postmouse_string = string_addition + postmouse_string
-                    this_mouse_num = find_number(
+                    this_mouse_num, leading_mouse_num_zeros = find_number(
                         filename,
                         premouse_string,
                         candidate_postmouse_string,
@@ -84,7 +87,7 @@ def extract_info(tracking_software, folderinfo, in_GUI=False):
             for string_addition in FILE_ID_STRING_ADDITIONS:
                 try:
                     candidate_postrun_string = string_addition + postrun_string
-                    this_run_num = find_number(
+                    this_run_num, leading_run_num_zeros = find_number(
                         filename, prerun_string, candidate_postrun_string
                     )
                 except:
@@ -106,6 +109,14 @@ def extract_info(tracking_software, folderinfo, in_GUI=False):
                     info["name"].append(this_name)
                     info["mouse_num"].append(this_mouse_num)
                     info["run_num"].append(this_run_num)
+    # if we had to fix leading zeros, make sure to save them so we can use them in
+    # move_data_to_folders function later
+    # => make sure it's lists of strings because this is needed by the
+    #    run_singlerun_in_multiruns function later
+    if leading_mouse_num_zeros:
+        info["leading_mouse_num_zeros"] = [leading_mouse_num_zeros]
+    if leading_run_num_zeros:
+        info["leading_run_num_zeros"] = [leading_run_num_zeros]
     # this might happen if user entered wrong identifiers or folder
     if len(info["name"]) < 1:
         no_files_message = (
@@ -143,7 +154,12 @@ def find_number(fullstring, prestring, poststring):
     """Find (mouse/run) number based on user-defined strings in filenames"""
     start_idx = fullstring.find(prestring) + len(prestring)
     end_idx = fullstring.find(poststring)
-    return int(fullstring[start_idx:end_idx])
+    # handle leading zeros
+    leading_zeros = ""
+    while fullstring[start_idx] == "0" and start_idx < end_idx - 1:
+        start_idx += 1
+        leading_zeros += "0"
+    return int(fullstring[start_idx:end_idx]), leading_zeros
 
 
 # ...........................  SC extraction helpers  ..................................
@@ -210,7 +226,81 @@ def check_cycle_order(all_cycles, info):
     return clean_cycles
 
 
-def check_tracking_xy_thresholds(data, info, all_cycles, cfg):
+def check_differing_angle_joint_coords(all_cycles, data, info, cfg):
+    """Check if none of the joints used for angle computations later have equal values (since this would lead to math.domain errors due to floating point precision)"""
+
+    # Note
+    # ----
+    # In theory, I could fix this programatically in the add_angle function, but I feel
+    # like joint-coords should not often be exactly equal like this in a meaningful way
+    # We can still change it in the future.
+
+    # unpack
+    angles = cfg["angles"]
+
+    clean_cycles = None
+    for c, cycle in enumerate(all_cycles):  # for each SC
+        cycle = check_a_single_cycle_for_joint_coords(cycle, angles, data, c, info)
+        if cycle:  # if cycle was not valid (equal-joint-coords) this returns None
+            if clean_cycles == None:
+                clean_cycles = [cycle]  # also makes a 2xscs list of lists
+            else:
+                clean_cycles.append(cycle)
+    return clean_cycles
+
+
+def check_a_single_cycle_for_joint_coords(cycle, angles, data, c, info):
+    for a in range(len(angles["name"])):  # for each angle configuration
+        # prepare a dict that has only the data of this angle config's joints
+        this_angle_data = {"name": [], "lower_joint": [], "upper_joint": []}
+        for key in this_angle_data.keys():
+            this_joint = angles[key][a]
+            this_angle_data[key] = np.array(
+                [data[this_joint + "x"], data[this_joint + "y"]]
+            )
+        # now check if any of the joints have the same coord at any idx
+        for idx in range(cycle[0], cycle[1]):
+            if (
+                np.array_equal(
+                    this_angle_data["name"][:, idx],
+                    this_angle_data["lower_joint"][:, idx],
+                )
+                or np.array_equal(
+                    this_angle_data["name"][:, idx],
+                    this_angle_data["upper_joint"][:, idx],
+                )
+                or np.array_equal(
+                    this_angle_data["lower_joint"][:, idx],
+                    this_angle_data["upper_joint"][:, idx],
+                )
+            ):
+                this_message = (
+                    "\n***********\n! WARNING !\n***********\n"
+                    + f"SC #{c + 1} has equal joint coordinates at "
+                    + f"{round(data[TIME_COL][idx],4)}s:"
+                    + "\n\nAngle - [x y]:\n"
+                    + angles["name"][a]
+                    + " - "
+                    + str(this_angle_data["name"][:, idx])
+                    + "\nLower joint: "
+                    + angles["lower_joint"][a]
+                    + " - "
+                    + str(this_angle_data["lower_joint"][:, idx])
+                    + "\nUpper joint: "
+                    + angles["upper_joint"][a]
+                    + " - "
+                    + str(this_angle_data["upper_joint"][:, idx])
+                    + "\nRemoving the SC from "
+                    + f"{round(data[TIME_COL][cycle[0]], 4)}-"
+                    + f"{round(data[TIME_COL][cycle[1]], 4)}s"
+                )
+                print(this_message)
+                write_issues_to_textfile(this_message, info)
+                return None  # removes this SC
+    return cycle  # if we never returned None, this SC is valid
+
+
+def check_tracking_xy_thresholds(all_cycles, data, info, cfg):
     """Check if any x/y column of any joint has broken datapoints"""
     # unpack
     convert_to_mm = cfg["convert_to_mm"]
@@ -255,7 +345,7 @@ def check_tracking_xy_thresholds(data, info, all_cycles, cfg):
     return clean_cycles
 
 
-def check_tracking_SLEAP_nans(data, info, all_cycles, cfg):
+def check_tracking_SLEAP_nans(all_cycles, data, info, cfg):
     """In SLEAP if tracking fails it generates NaNs - make sure we don't have those in any SC in any joint or angle-joint"""
     # unpack
     hind_joints = cfg["hind_joints"]