autogaita 0.0.5__tar.gz → 0.0.6__tar.gz

{autogaita-0.0.5 → autogaita-0.0.6}/PKG-INFO

@@ -1,8 +1,10 @@
 Metadata-Version: 2.1
 Name: autogaita
-Version: 0.0.5
+Version: 0.0.6
 Summary: Automatic Gait Analysis in Python
 Home-page: https://github.com/mahan-hosseini/AutoGaitA/
 Author: Mahan Hosseini
 License: GPLv3
+Requires-Python: >=3.10
+Provides-Extra: dev
 License-File: LICENSE

{autogaita-0.0.5 → autogaita-0.0.6}/README.md

@@ -1,5 +1,7 @@
 ![AutoGaitA](https://github.com/mahan-hosseini/AutoGaitA/blob/main/res/autogaita_logo.png?raw=true)
-![Python](https://img.shields.io/badge/python-v3.6+-blue.svg)
+[![PyPI version](https://badge.fury.io/py/autogaita.svg)](https://badge.fury.io/py/autogaita)
+[![Test AutoGaitA](https://github.com/mahan-hosseini/AutoGaitA/actions/workflows/auto_test_gaita.yml/badge.svg)](https://github.com/mahan-hosseini/AutoGaitA/actions/workflows/auto_test_gaita.yml)
+![Python](https://img.shields.io/badge/python-v3.10+-blue.svg)
 ![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)
 ![Black](https://img.shields.io/badge/code%20style-black-000000.svg)
 # Automated Gait Analysis in Python 🐸
@@ -13,17 +15,18 @@
 
 ***Note!** Our documentation provides step-by-step walkthroughs of how to install autogaita for **[Windows](https://docs.google.com/document/d/1Y4wrrsjs0ybLDKPzE2LAatqPDq9jtwjIuk4M0jRZ3wE/edit#heading=h.28j6wu2vamre)** and **[Mac](https://docs.google.com/document/d/1Y4wrrsjs0ybLDKPzE2LAatqPDq9jtwjIuk4M0jRZ3wE/edit)***
 
-It is strongly recommended that a separate virtual environment for AutoGaitA is created via
+It is strongly recommended that a separate virtual environment for AutoGaitA is created (note that the approach below creates the virtual environment to your current directory):
 
-`python -m venv env_gaita`
+- Create the virtual environment
+    - `python -m venv env_gaita`
 
-After creating and activating the virtual environment, AutoGaitA can be installed via pip
+- After creation, activate the virtual environment via:
+    - *Windows:* `env_gaita\Scripts\activate`
+    - *Mac:* `source env_gaita/bin/activate`
 
-`pip install autogaita`
+- Once activated, install AutoGaitA in the virtual environment via pip: `pip install autogaita`.
 
-The main user interface can then be accessed via
-
-`python -m autogaita`
+- Access the main user interface via `python -m autogaita`.
 
 ## Tutorials and Examples
 
@@ -54,9 +57,13 @@ By default, *AutoGaitA DLC* and *AutoGaitA Simi* implement standard values for m
 - [Documentation - AutoGaitA DLC](https://docs.google.com/document/d/1Y4wrrsjs0ybLDKPzE2LAatqPDq9jtwjIuk4M0jRZ3wE/edit#heading=h.20bg7b7ymt0b)
 - [Documentation - AutoGaitA Simi](https://docs.google.com/document/d/1Y4wrrsjs0ybLDKPzE2LAatqPDq9jtwjIuk4M0jRZ3wE/edit#heading=h.uz61bpmua7qz)
 
+## Reference
+If you use this code or data please [cite our preprint](https://www.biorxiv.org/content/10.1101/2024.04.14.589409v1).
+
 ## License
+AutoGaitA is licensed under [GPL v3.0](https://github.com/mahan-hosseini/AutoGaitA/blob/main/LICENSE) and Forschungszentrum Jülich GmbH holds all copyrights. 
 
-AutoGaitA is licensed under [GPL v3.0](https://github.com/mahan-hosseini/AutoGaitA/blob/main/LICENSE) and Forschungszentrum Jülich GmbH holds all copyrights.
+The AutoGaitA software is provided without warranty of any kind, express or implied, including, but not limited to, the implied warranty of fitness for a particular purpose.
 
 ## Authors
 Mahan Hosseini

autogaita-0.0.6/autogaita/__init__.py

@@ -0,0 +1,20 @@
+# main gui
+from .autogaita import gui  # autogaita.gui()
+
+# 3 sub-guis
+from .autogaita_dlc_gui import dlc_gui  # autogaita.dlc_gui()
+from .autogaita_simi_gui import simi_gui  # autogaita.simi_gui()
+from .autogaita_group_gui import group_gui  # autogaita.group_gui()
+
+# 3 main functions
+from .autogaita_dlc import dlc  # autogaita.dlc(info, folderinfo, cfg)
+from .autogaita_simi import simi  # autogaita.simi(info, folderinfo, cfg)
+from .autogaita_group import group  # autogaita.group(folderinfo, cfg)
+
+# 6 batchrun functions - call via e.g. autogaita.dlc_singlerun()
+from .batchrun_scripts.autogaita_dlc_singlerun import dlc_singlerun
+from .batchrun_scripts.autogaita_dlc_multirun import dlc_multirun
+from .batchrun_scripts.autogaita_simi_singlerun import simi_singlerun
+from .batchrun_scripts.autogaita_simi_multirun import simi_multirun
+from .batchrun_scripts.autogaita_group_dlcrun import group_dlcrun
+from .batchrun_scripts.autogaita_group_simirun import group_simirun

{autogaita-0.0.5 → autogaita-0.0.6}/autogaita/autogaita.py

@@ -124,7 +124,7 @@ def configure_the_icon(root):
         try:
             from Cocoa import NSApplication, NSImage
         except ImportError:
-            print('Unable to import pyobjc modules')
+            print("Unable to import pyobjc modules")
         else:
             with resources.path("autogaita", "autogaita_icon.icns") as icon_path:
                 ns_application = NSApplication.sharedApplication()

{autogaita-0.0.5 → autogaita-0.0.6}/autogaita/autogaita_dlc.py

@@ -1,9 +1,9 @@
 # %% imports
 import os
 import sys
-import pdb
 import shutil
 import json
+import warnings
 import pandas as pd
 import numpy as np
 import math
@@ -17,8 +17,17 @@ TIME_COL = "Time"
 ISSUES_TXT_FILENAME = "Issues.txt"  # filename to which we write issues-info
 CONFIG_JSON_FILENAME = "config.json"  # filename to which we write cfg-infos
 SCXLS_MOUSECOLS = [
-    "Mouse", "mouse", "Fly", "fly", "Animal", "animal", "Subject", "subject", "ID", "id"
-    ]  # SC XLS info
+    "Mouse",
+    "mouse",
+    "Fly",
+    "fly",
+    "Animal",
+    "animal",
+    "Subject",
+    "subject",
+    "ID",
+    "id",
+]  # SC XLS info
 SCXLS_RUNCOLS = ["Run", "run", "Runs", "runs", "Trial", "trial", "Trials", "trials"]
 SCXLS_SCCOLS = ["SC Number", "SC number", "sc number", "SC Num", "sc num", "SC num"]
 SWINGSTART_COL = "Swing (ti)"
@@ -235,7 +244,7 @@ def some_prep(info, folderinfo, cfg):
     # if wanted: fix that deeplabcut inverses y
     if invert_y_axis:
         for col in data.columns:
-            if col.endswith("y"):
+            if col.endswith(" y"):
                 data[col] = data[col] * -1
     # if we don't have a beam to subtract, normalise y to global y minimum being 0
     if not subtract_beam:
@@ -259,16 +268,18 @@ def some_prep(info, folderinfo, cfg):
     #    pushing it towards zero.
     # => using list(set()) to ensure that we don't have duplicate values (if users
     #    should have provided them in both cfg vars by misstake)
+    # => beam_col_left and right is provided by users
     if subtract_beam:
+        # note beam_col_left/right are always lists in cfg!
+        beam_col_left = cfg["beam_col_left"][0]
+        beam_col_right = cfg["beam_col_right"][0]
         for joint in list(set(hind_joints + beam_hind_jointadd)):
-            data[joint + "y"] = data[joint + "y"] - data["BeamLeft y"]
+            data[joint + "y"] = data[joint + "y"] - data[beam_col_left + "y"]
         for joint in list(set(fore_joints + beam_fore_jointadd)):
-            data[joint + "y"] = data[joint + "y"] - data["BeamRight y"]
-        dropcols = [c for c in data.columns if "Beam" in c]
-        data.drop(columns=dropcols, inplace=True)  # beamcols not needed anymore
+            data[joint + "y"] = data[joint + "y"] - data[beam_col_right + "y"]
+        data.drop(columns=list(beamdf.columns), inplace=True)  # beam not needed anymore
     # add Time and round based on sampling rate
     data[TIME_COL] = data.index * (1 / sampling_rate)
-    pdb.set_trace()
     if sampling_rate <= 100:
         data[TIME_COL] = round(data[TIME_COL], 2)
     elif 100 < sampling_rate <= 1000:
@@ -343,13 +354,16 @@ def test_and_expand_cfg(data, cfg, info):
     Check that all features are present in the dataset
     Add plot_joints & direction_joint
     Make sure to set dont_show_plots to True if Python is not in interactive mode
+    If users subtract a beam, set normalise @ sc level to False
     """
 
-    # run the 3 tests first
+    # run the tests first
     for cfg_key in [
         "angles",
         "hind_joints",
         "fore_joints",
+        "beam_col_left",  # note beamcols are lists even though len=1 bc. of
+        "beam_col_right",  # check function's procedure
         "beam_hind_jointadd",
         "beam_fore_jointadd",
     ]:
@@ -373,19 +387,42 @@ def test_and_expand_cfg(data, cfg, info):
     else:
         cfg["plot_joints"] = hind_joints[: cfg["plot_joint_number"]]
 
-    # add direction_joint - used to determine gait direction
+    # check hindlimb joints & add direction_joint - used to determine gait direction
     if not hind_joints:  # no valid string after above cleaning
         no_hind_joint_message = (
             "\n******************\n! CRITICAL ERROR !\n******************\n"
             + "After testing your hind limb joint names, no valid joint was left to "
             + "perform gait direction checks on.\nPlease make sure that at least one "
             + "hind limb joint is provided & try again!"
-            )
+        )
         write_issues_to_textfile(no_hind_joint_message, info)
         print(no_hind_joint_message)
         return
     cfg["direction_joint"] = hind_joints[0]
 
+    # if subtracting beam, check that its colnames were valid.
+    if cfg["subtract_beam"]:
+        beam_col_error_message = (
+            "\n******************\n! CRITICAL ERROR !\n******************\n"
+            + "It seems like you want to normalise heights to a baseline (beam)."
+            + "\nUnfortunately we were unable to find the y-columns you listed in "
+            + "your beam's csv-file.\nPlease try again.\nInvalid beam side(s) was/were:"
+        )
+        beam_error = False  # check 3 possible cases
+        if (cfg["beam_col_left"]) and (not cfg["beam_col_right"]):
+            beam_error = True
+            beam_col_error_message += "\n right beam!"
+        elif (not cfg["beam_col_left"]) and (cfg["beam_col_right"]):
+            beam_error = True
+            beam_col_error_message += "\n left beam!"
+        elif (not cfg["beam_col_left"]) and (not cfg["beam_col_right"]):
+            beam_error = True
+            beam_col_error_message += "\n both beams!"
+        if beam_error:  # if any case was True, stop everything
+            write_issues_to_textfile(beam_col_error_message, info)
+            print(beam_col_error_message)
+            return
+
     # dont show plots
     # !!! If users should complain that they dont get figures but they should, it might
     #     be because these lines wrongly determine user to be in non-interactive mode
@@ -394,6 +431,10 @@ def test_and_expand_cfg(data, cfg, info):
         cfg["dont_show_plots"] = True
         matplotlib.use("agg")
 
+    # never normalise @ SC level if user subtracted a beam
+    if cfg["subtract_beam"]:
+        cfg["normalise_height_at_SC_level"] = False
+
     return cfg
 
 
@@ -438,7 +479,7 @@ def check_and_fix_cfg_strings(data, cfg, cfg_key, info):
                 clean_strings_message += "\n" + string
             clean_strings_message += (
                 "\n\nNote that capitalisation matters."
-                + "\nIf you are running a group analysis, we'll use this updated cfg "
+                + "\nIf you are running a batch analysis, we'll use this updated cfg "
                 + "throughout\nCheck out the config.json file for the full cfg used."
             )
             print(clean_strings_message)
@@ -446,6 +487,23 @@ def check_and_fix_cfg_strings(data, cfg, cfg_key, info):
 
     # things are more involved for angle dicts
     elif type(string_variable) is dict:
+        # 1) test if the lists of all keys are equally long, if not throw out last idxs
+        key_lengths = [len(string_variable[key]) for key in string_variable.keys()]
+        if not all(key_length == key_lengths[0] for key_length in key_lengths):
+            min_length = min(key_lengths)
+            for key in string_variable:  # remove invalid idxs
+                string_variable[key] = string_variable[key][:min_length]
+            key_length_mismatch_message = (  # inform user
+                "\n***********\n! WARNING !\n***********\n"
+                + "\nLength-mismatch in angle configuration!"
+                + "\nCheck angles' name/upper/lower-joint entries."
+                + "\nOnly processing first "
+                + str(min_length)
+                + " entries."
+            )
+            print(key_length_mismatch_message)
+            write_issues_to_textfile(key_length_mismatch_message, info)
+        # 2) check if all strings in the angle dict are valid columns
         invalid_angletrio_message = ""
         invalid_idxs = []  # these idxs hold across the 3 keys of our angles-dict
         for key in string_variable:
@@ -460,7 +518,7 @@ def check_and_fix_cfg_strings(data, cfg, cfg_key, info):
                     invalid_idxs.append(idx)
                     if not this_keys_missing_strings:  # first occurance
                         this_keys_missing_strings += "\nAngle's " + key + " key: "
-                    this_keys_missing_strings += (string + "(#" + str(idx+1) + ") / ")
+                    this_keys_missing_strings += string + "(#" + str(idx + 1) + ") / "
             # string concat outside of idx-forloop above please
             invalid_angletrio_message += this_keys_missing_strings
         # if we have to remove idxs from all keys of our angles dict
@@ -497,7 +555,7 @@ def check_and_fix_cfg_strings(data, cfg, cfg_key, info):
                 )
             clean_angles_message += (
                 "\n\nNote that capitalisation matters."
-                + "\nIf you are running a group analysis, we'll use this updated cfg "
+                + "\nIf you are running a batch analysis, we'll use this updated cfg "
                 + "throughout\nCheck out the config.json file for the full cfg used."
             )
             print(clean_angles_message)
@@ -627,7 +685,7 @@ def extract_stepcycles(data, info, folderinfo, cfg):
             SCdf = pd.read_excel(os.path.join(root_dir, sctable_filename))
         else:
             raise FileNotFoundError(
-                "No SC XLS table found! sctable_filename has to be @ root_dir"
+                "No Annotation Table found! sctable_filename has to be @ root_dir"
             )
     else:
         # in cases below use string-concat (+) - otherwise xls added as path
@@ -637,7 +695,7 @@ def extract_stepcycles(data, info, folderinfo, cfg):
             SCdf = pd.read_excel(os.path.join(root_dir, sctable_filename + ".xlsx"))
         else:
             raise FileNotFoundError(
-                "No SC XLS table found! sctable_filename has to be @ root_dir"
+                "No Annotation Table found! sctable_filename has to be @ root_dir"
             )
     # see if table columns are labelled correctly (try a couple to allow user typos)
     valid_col_flags = [False, False, False]
@@ -770,6 +828,7 @@ def extract_stepcycles(data, info, folderinfo, cfg):
     all_cycles = check_DLC_tracking(data, info, all_cycles, cfg)
     return all_cycles
 
+
 # ..............................  helper functions  ....................................
 def check_cycle_out_of_bounds(all_cycles):
     """Check if user provided SC latencies that were not in video/data bounds"""
@@ -817,7 +876,7 @@ def check_cycle_order(all_cycles, info):
                 this_message = (
                     "\n***********\n! WARNING !\n***********\n"
                     + "SC #"
-                    + str(c+1)
+                    + str(c + 1)
                     + " has a later start than end latency - Skipping!"
                 )
                 print(this_message)
@@ -826,7 +885,7 @@ def check_cycle_order(all_cycles, info):
             this_message = (
                 "\n***********\n! WARNING !\n***********\n"
                 + "SC #"
-                + str(c+1)
+                + str(c + 1)
                 + " has an earlier start than previous SC's end latency - Skipping!"
             )
             print(this_message)
@@ -930,7 +989,7 @@ def handle_issues(condition, info):
 # ----
 # There is quite a lot going on in this function. We:
 # 1) loop through all step cycles for one leg at a time and extract data
-# 2) for each step's data we normalise all y (height) values to the hind paw's minimum
+# 2) for each step's data we normalise all y (height) values to the body's minimum
 #    if wanted
 # 3) we compute and add features (angles, velocities, accelerations)
 #    ==> see norm_y_and_add_features_to_one_step & helper functions a
@@ -958,7 +1017,7 @@ def analyse_and_export_stepcycles(data, all_cycles, info, folderinfo, cfg):
         normalised_steps_data = normalise_one_steps_data(all_steps_data, bin_num)
     # 2 or more steps - build dataframe
     elif len(all_cycles) > 1:
-        # first step is added manually
+        # first- step is added manually
         first_step = data_copy.loc[all_cycles[0][0] : all_cycles[0][1]]
         first_step = norm_y_and_add_features_to_one_step(first_step, cfg)
         all_steps_data = first_step
@@ -966,12 +1025,18 @@ def analyse_and_export_stepcycles(data, all_cycles, info, folderinfo, cfg):
         # some prep for addition of further steps
         sc_num = len(all_cycles)
         nanvector = data_copy.loc[[1]]
-        nanvector[:] = np.nan
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            nanvector[:] = np.nan
         # ..............................  step-loop  ...................................
         for s in range(1, sc_num, 1):
             # get step separators
             numvector = data_copy.loc[[1]]
-            numvector[:] = s + 1
+            # we are ignoring this because we wont work with the incompatible dtypes ourselves much anymore (just export as xlsx and plot) - so its fine
+            # https://docs.python.org/3/library/warnings.html#temporarily-suppressing-warnings
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                numvector[:] = s + 1
             all_steps_data = add_step_separators(all_steps_data, nanvector, numvector)
             # this_step
             this_step = data_copy.loc[all_cycles[s][0] : all_cycles[s][1]]
@@ -1273,7 +1338,7 @@ def plot_results(info, results, folderinfo, cfg):
     angular_acceleration = cfg["angular_acceleration"]
     dont_show_plots = cfg["dont_show_plots"]
     if dont_show_plots:
-        plt.switch_backend('Agg')
+        plt.switch_backend("Agg")
 
     # ....................0 - extract SCs from all_steps_data...........................
     sc_idxs = extract_sc_idxs(all_steps_data)
@@ -1397,9 +1462,19 @@ def plot_joint_y_by_x(all_steps_data, sc_idxs, info, cfg):
             else:
                 float_precision = 4
             this_label = (
-                str(round(all_steps_data.iloc[sc_idxs[s][0], time_col_idx], float_precision))
+                str(
+                    round(
+                        all_steps_data.iloc[sc_idxs[s][0], time_col_idx],
+                        float_precision,
+                    )
+                )
                 + "-"
-                + str(round(all_steps_data.iloc[sc_idxs[s][-1], time_col_idx], float_precision))
+                + str(
+                    round(
+                        all_steps_data.iloc[sc_idxs[s][-1], time_col_idx],
+                        float_precision,
+                    )
+                )
                 + "s"
             )
             ax[j].plot(this_x, this_y, label=this_label)
@@ -1412,7 +1487,9 @@ def plot_joint_y_by_x(all_steps_data, sc_idxs, info, cfg):
             figure_file_string = " - Foot y by x coordinates"
         else:
             figure_file_string = " - " + joint + "y by x coordinates"
-        f[j].savefig(results_dir + name + figure_file_string + ".png", bbox_inches="tight")
+        f[j].savefig(
+            results_dir + name + figure_file_string + ".png", bbox_inches="tight"
+        )
         save_as_svg(f[j], results_dir, name, figure_file_string)
         if dont_show_plots:
             plt.close(f[j])
@@ -1448,7 +1525,9 @@ def plot_angles_by_time(all_steps_data, sc_idxs, info, cfg):
             this_y = all_steps_data.iloc[sc_idxs[s], y_col_idx]
             ax[a].plot(this_x, this_y)
         figure_file_string = " - " + angle + " Angle by Time"
-        f[a].savefig(results_dir + name + figure_file_string + ".png", bbox_inches="tight")
+        f[a].savefig(
+            results_dir + name + figure_file_string + ".png", bbox_inches="tight"
+        )
         save_as_svg(f[a], results_dir, name, figure_file_string)
         if dont_show_plots:
             plt.close(f[a])
@@ -1481,9 +1560,15 @@ def plot_hindlimb_stickdiagram(all_steps_data, sc_idxs, info, cfg):
         else:
             float_precision = 4
         this_label = (
-            str(round(all_steps_data.iloc[sc_idxs[s][0], time_col_idx], float_precision))
+            str(
+                round(all_steps_data.iloc[sc_idxs[s][0], time_col_idx], float_precision)
+            )
             + "-"
-            + str(round(all_steps_data.iloc[sc_idxs[s][-1], time_col_idx], float_precision))
+            + str(
+                round(
+                    all_steps_data.iloc[sc_idxs[s][-1], time_col_idx], float_precision
+                )
+            )
             + "s"
         )
         for i in sc_idxs[s]:  # loop over timepoints of current SC
@@ -1537,9 +1622,15 @@ def plot_forelimb_stickdiagram(all_steps_data, sc_idxs, info, cfg):
         else:
             float_precision = 4
         this_label = (
-            str(round(all_steps_data.iloc[sc_idxs[s][0], time_col_idx], float_precision))
+            str(
+                round(all_steps_data.iloc[sc_idxs[s][0], time_col_idx], float_precision)
+            )
             + "-"
-            + str(round(all_steps_data.iloc[sc_idxs[s][-1], time_col_idx], float_precision))
+            + str(
+                round(
+                    all_steps_data.iloc[sc_idxs[s][-1], time_col_idx], float_precision
+                )
+            )
             + "s"
         )
         for i in sc_idxs[s]:
@@ -1827,7 +1918,9 @@ def save_as_svg(figure, results_dir, name, figure_file_string):
     svg_dir = os.path.join(results_dir, "SVG Figures")
     if not os.path.exists(svg_dir):
         os.makedirs(svg_dir)
-    figure.savefig(svg_dir + "/" + name + figure_file_string + ".svg", bbox_inches="tight")
+    figure.savefig(
+        svg_dir + "/" + name + figure_file_string + ".svg", bbox_inches="tight"
+    )
 
 
 def tickconvert_mm_to_cm(axis, whichlabel):
@@ -1872,5 +1965,5 @@ if __name__ == "__main__":
         + "possible.\nIf you prefer a non-GUI approach, please either: "
         + "\n1. Call this as a function, i.e. autogaita.dlc(info, folderinfo, cfg)"
         + "\n2. Use the single or multirun scripts in the batchrun_scripts folder"
-        )
+    )
     print(dlc_info_message)