autogaita 0.3.1__tar.gz → 0.4.0__tar.gz

autogaita-0.4.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: autogaita
+Version: 0.4.0
+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
+License: GPLv3
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: customtkinter>=5.2
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: seaborn>=0.13
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: pingouin>=0.5
+Requires-Dist: scipy>=1.11
+Requires-Dist: ffmpeg-python>=0.2
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pillow>=10.3
+Requires-Dist: pyobjc
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"

{autogaita-0.3.1 → autogaita-0.4.0}/autogaita/autogaita_dlc.py

@@ -44,6 +44,7 @@ ORIGINAL_XLS_FILENAME = " - Original Stepcycles"  # filenames of sheet exports
 NORMALISED_XLS_FILENAME = " - Normalised Stepcycles"
 AVERAGE_XLS_FILENAME = " - Average Stepcycle"
 STD_XLS_FILENAME = " - Standard Devs. Stepcycle"
+X_STANDARDISED_XLS_FILENAME = " - X-Standardised Stepcycles"
 SC_LAT_LEGEND_FONTSIZE = 8
 # PLOT GUI COLORS
 FG_COLOR = "#789b73"  # grey green
@@ -60,7 +61,7 @@ def dlc(info, folderinfo, cfg):
     ---------
     1) import & preparation
     2) step cycle extraction
-    3) y-normalisation & feature computation for individual step cycles
+    3) x/y-standardisation & feature computation for individual step cycles
     4) step cycle normalisation, dataframe creation & XLS-exportation
     5) plots
     """
@@ -82,7 +83,7 @@ def dlc(info, folderinfo, cfg):
 
     # .........................  step-cycle extraction  ................................
     all_cycles = extract_stepcycles(data, info, folderinfo, cfg)
-    if not all_cycles:
+    if all_cycles is None:
         handle_issues("scs_invalid", info)
         if cfg["dont_show_plots"] is False:  # otherwise stuck at loading
             plot_panel_instance.destroy_plot_panel()
@@ -105,6 +106,7 @@ def some_prep(info, folderinfo, cfg):
     """Preparation of the data & cfg file for later analyses"""
 
     # ............................  unpack stuff  ......................................
+    # => DON'T unpack (joint) cfg-keys that are tested later by check_and_expand_cfg
     name = info["name"]
     results_dir = info["results_dir"]
     data_string = folderinfo["data_string"]
@@ -113,10 +115,12 @@ def some_prep(info, folderinfo, cfg):
     subtract_beam = cfg["subtract_beam"]
     convert_to_mm = cfg["convert_to_mm"]
     pixel_to_mm_ratio = cfg["pixel_to_mm_ratio"]
-    normalise_height_at_SC_level = cfg["normalise_height_at_SC_level"]
+    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"]
     analyse_average_x = cfg["analyse_average_x"]
+    standardise_x_coordinates = cfg["standardise_x_coordinates"]
+    standardise_y_to_a_joint = cfg["standardise_y_to_a_joint"]
 
     # .............................  move data  ........................................
     # => see if we can delete a previous runs results folder if existant. if not, it's a
@@ -247,11 +251,10 @@ def some_prep(info, folderinfo, cfg):
         data = datadf.copy(deep=True)
 
     # ................  final data checks, conversions & additions  ....................
-    # IMPORTANT
-    # ---------
-    # MAIN TESTS OF USER-INPUT VALIDITY OCCUR HERE!
+    # IMPORTANT - MAIN TESTS OF USER-INPUT VALIDITY OCCUR HERE!
+    # => UNPACK VARS FROM CFG THAT ARE TESTED BY check_and_expand HERE, NOT EARLIER!
     cfg = check_and_expand_cfg(data, cfg, info)
-    if cfg is None:  # hind joints were empty
+    if cfg is None:  # some critical error occured
         return
     hind_joints = cfg["hind_joints"]
     fore_joints = cfg["fore_joints"]
@@ -259,6 +262,9 @@ def some_prep(info, folderinfo, cfg):
     beam_hind_jointadd = cfg["beam_hind_jointadd"]
     beam_fore_jointadd = cfg["beam_fore_jointadd"]
     direction_joint = cfg["direction_joint"]
+    # important to unpack to vars hand not to cfg since cfg is overwritten in multiruns!
+    x_standardisation_joint = cfg["x_standardisation_joint"][0]
+    y_standardisation_joint = cfg["y_standardisation_joint"][0]
     # store config json file @ group path
     # !!! NU - do this @ mouse path!
     group_path = results_dir.split(name)[0]
@@ -266,8 +272,12 @@ def some_prep(info, folderinfo, cfg):
     config_vars_to_json = {
         "sampling_rate": sampling_rate,
         "convert_to_mm": convert_to_mm,
-        "normalise_height_at_SC_level": normalise_height_at_SC_level,
+        "standardise_y_at_SC_level": standardise_y_at_SC_level,
         "analyse_average_x": analyse_average_x,
+        "standardise_x_coordinates": standardise_x_coordinates,
+        "x_standardisation_joint": x_standardisation_joint,
+        "standardise_y_to_a_joint": standardise_y_to_a_joint,
+        "y_standardisation_joint": y_standardisation_joint,
         "hind_joints": hind_joints,
         "fore_joints": fore_joints,
         "angles": angles,
@@ -304,12 +314,15 @@ def some_prep(info, folderinfo, cfg):
         for col in data.columns:
             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 we don't have a beam to subtract, standardise y to a joint's or global ymin = 0
     if not subtract_beam:
-        global_y_min = float("inf")
+        y_min = float("inf")
         y_cols = [col for col in data.columns if col.endswith("y")]
-        global_y_min = min(data[y_cols].min())
-        data[y_cols] -= global_y_min
+        if standardise_y_to_a_joint:
+            y_min = data[y_standardisation_joint + "y"].min()
+        else:
+            y_min = data[y_cols].min().min()
+        data[y_cols] -= y_min
     # convert pixels to millimeters
     if convert_to_mm:
         for column in data.columns:
@@ -319,7 +332,7 @@ def some_prep(info, folderinfo, cfg):
     data = check_gait_direction(data, direction_joint, flip_gait_direction, info)
     if data is None:  # this means DLC file is broken
         return
-    # subtract the beam from the joints to normalise y
+    # subtract the beam from the joints to standardise y
     # => bc. we simulate that all mice run from left to right, we can write:
     #     (note that we also flip beam x columns, but never y-columns!)
     # => & bc. we multiply y values by *-1 earlier, it's a neg_num - - neg_num
@@ -336,14 +349,8 @@ def some_prep(info, folderinfo, cfg):
         for joint in list(set(fore_joints + beam_fore_jointadd)):
             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
+    # add Time
     data[TIME_COL] = data.index * (1 / sampling_rate)
-    if sampling_rate <= 100:
-        data[TIME_COL] = round(data[TIME_COL], 2)
-    elif 100 < sampling_rate <= 1000:
-        data[TIME_COL] = round(data[TIME_COL], 3)
-    else:
-        data[TIME_COL] = round(data[TIME_COL], 4)
     # reorder the columns we added
     cols = [TIME_COL, "Flipped"]
     data = data[cols + [c for c in data.columns if c not in cols]]
@@ -435,17 +442,15 @@ def check_and_expand_cfg(data, cfg, info):
     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
+    String-checks for standardisation joints
     """
 
     # run the tests first
+    # => note that beamcols & standardisation joints are tested separately further down.
     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",
     ]:
         cfg[cfg_key] = check_and_fix_cfg_strings(data, cfg, cfg_key, info)
 
@@ -482,9 +487,18 @@ def check_and_expand_cfg(data, cfg, info):
 
     # if subtracting beam, check identifier-strings & that beam colnames were valid.
     if cfg["subtract_beam"]:
+        # first, let's check the strings
+        # => note beamcols are lists of len=1 bc. of check function
+        for cfg_key in [
+            "beam_col_left",
+            "beam_col_right",
+            "beam_hind_jointadd",
+            "beam_fore_jointadd",
+        ]:
+            cfg[cfg_key] = check_and_fix_cfg_strings(data, cfg, cfg_key, info)
         beam_col_error_message = (
             "\n******************\n! CRITICAL ERROR !\n******************\n"
-            + "It seems like you want to normalise heights to a baseline (beam)."
+            + "It seems like you want to standardise 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:"
         )
@@ -503,9 +517,38 @@ def check_and_expand_cfg(data, cfg, info):
             print(beam_col_error_message)
             return
 
-    # never normalise @ SC level if user subtracted a beam
+    # never standardise @ SC level if user subtracted a beam
     if cfg["subtract_beam"]:
-        cfg["normalise_height_at_SC_level"] = False
+        cfg["standardise_y_at_SC_level"] = False
+
+    # test x/y standardisation joints if needed
+    broken_standardisation_joint = ""
+    if cfg["standardise_x_coordinates"]:
+        cfg["x_standardisation_joint"] = check_and_fix_cfg_strings(
+            data, cfg, "x_standardisation_joint", info
+        )
+        if not cfg["x_standardisation_joint"]:
+            broken_standardisation_joint += "x"
+    if cfg["standardise_y_to_a_joint"]:
+        cfg["y_standardisation_joint"] = check_and_fix_cfg_strings(
+            data, cfg, "y_standardisation_joint", info
+        )
+        if not cfg["y_standardisation_joint"]:
+            if broken_standardisation_joint:
+                broken_standardisation_joint += " & y"
+            else:
+                broken_standardisation_joint += "y"
+    if broken_standardisation_joint:
+        no_standardisation_joint_message = (
+            "\n******************\n! CRITICAL ERROR !\n******************\n"
+            + "After testing your standardisation joints we found an issue with "
+            + broken_standardisation_joint
+            + "-coordinate standardisation joint."
+            + "\n Cancelling AutoGaitA - please try again!"
+        )
+        write_issues_to_textfile(no_standardisation_joint_message, info)
+        print(no_standardisation_joint_message)
+        return
 
     return cfg
 
@@ -513,8 +556,12 @@ def check_and_expand_cfg(data, cfg, info):
 def check_and_fix_cfg_strings(data, cfg, cfg_key, info):
     """Check and fix strings in our joint & angle lists so that:
     1) They don't include empty strings
-    2) All strings end with the space character (since we do string + "y")
+    2) All strings end with the space character
+       => Important note: strings should never have the coordinate in them (since we do
+          string + "y" for example throughout this code)
     3) All strings are valid columns of the DLC dataset
+       => Note that x_standardisation_joint is tested against ending with "x" - rest
+          against "y"
     """
 
     # work on this variable (we return to cfg[key] outside of here)
@@ -526,11 +573,17 @@ def check_and_fix_cfg_strings(data, cfg, cfg_key, info):
         string_variable = [s if s.endswith(" ") else s + " " for s in string_variable]
         clean_string_list = []
         invalid_strings_message = ""
-        for s, string in enumerate(string_variable):
-            if string + "y" in data.columns:
-                clean_string_list.append(string)
-            else:
-                invalid_strings_message += "\n" + string
+        for string in string_variable:
+            if cfg_key == "x_standardisation_joint":
+                if string + "x" in data.columns:
+                    clean_string_list.append(string)
+                else:
+                    invalid_strings_message += "\n" + string
+            else:  # for y_standardisation_joint (& all other cases)!!
+                if string + "y" in data.columns:
+                    clean_string_list.append(string)
+                else:
+                    invalid_strings_message += "\n" + string
         if invalid_strings_message:
             # print and save warning
             strings_warning = (
@@ -862,26 +915,43 @@ def extract_stepcycles(data, info, folderinfo, cfg):
         # extract the SC times
         start_in_s = float(SCdf.iloc[info_row, start_col].values[0])
         end_in_s = float(SCdf.iloc[info_row, end_col].values[0])
-        if sampling_rate <= 100:
-            float_precision = 2  # how many decimals we round to
-        elif 100 < sampling_rate <= 1000:
-            float_precision = 3
+        # see if we are rounding to fix inaccurate user input
+        # => account for python's float precision leading to inaccuracies
+        # => two important steps here (sanity_check_vals only used for these checks)
+        # 1. round to 10th decimal to fix python making
+        #    3211.999999999999999995 out of 3212
+        sanity_check_start = round(start_in_s * sampling_rate, 10)
+        sanity_check_end = round(end_in_s * sampling_rate, 10)
+        # 2. comparing abs(sanity check vals) to 1e-7 just to be 1000% sure
+        if (abs(sanity_check_start % 1) > 1e-7) | (abs(sanity_check_end % 1) > 1e-7):
+            round_message = (
+                "\n***********\n! WARNING !\n***********\n"
+                + "SC latencies of "
+                + str(start_in_s)
+                + "s to "
+                + str(end_in_s)
+                + "s were not provided in units of the frame rate!"
+                + "\nWe thus use the previous possible frame(s)."
+                + "\nDouble check if this worked as expected or fix annotation table!"
+            )
+            print(round_message)
+            write_issues_to_textfile(round_message, info)
+        # assign to all_cycles (note int() rounds down!)
+        all_cycles[s][0] = int(start_in_s * sampling_rate)
+        all_cycles[s][1] = int(end_in_s * sampling_rate)
+        # check if we are in data-bounds
+        if (all_cycles[s][0] in data.index) & (all_cycles[s][1] in data.index):
+            pass
         else:
-            float_precision = 4
-        start_in_s = round(start_in_s, float_precision)
-        end_in_s = round(end_in_s, float_precision)
-        try:
-            all_cycles[s][0] = np.where(data[TIME_COL] == start_in_s)[0][0]
-            all_cycles[s][1] = np.where(data[TIME_COL] == end_in_s)[0][0]
-        except IndexError:
+            all_cycles[s] = [None, None]  # so they can be cleaned later
             this_message = (
                 "\n***********\n! WARNING !\n***********\n"
                 + "SC latencies of: "
                 + str(start_in_s)
                 + "s to "
                 + str(end_in_s)
-                + "s not in data/video range!\n"
-                + "Skipping!"
+                + "s not in data/video range!"
+                + "\nSkipping!"
             )
             print(this_message)
             write_issues_to_textfile(this_message, info)
@@ -889,25 +959,28 @@ def extract_stepcycles(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)
-    # 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 DLC tracking broke for any SCs - if so remove them
-    all_cycles = check_DLC_tracking(data, info, all_cycles, cfg)
+    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 DLC tracking broke for any SCs - if so remove them
+        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"""
-    clean_cycles = []
+    clean_cycles = None
     for cycle in all_cycles:
         # below checks if values are any type of int (just in case this should
         # for some super random reason change...)
         if isinstance(cycle[0], (int, np.integer)) & isinstance(
             cycle[1], (int, np.integer)
         ):
+            if clean_cycles is None:
+                clean_cycles = []
             clean_cycles.append(cycle)
     return clean_cycles
 
@@ -918,7 +991,6 @@ def check_cycle_duplicates(all_cycles):
     all indices of all_cycles have to be unique. If any duplicates found, add one
     datapoint to the start latency.
     """
-
     for c, cycle in enumerate(all_cycles):
         if c > 0:
             if cycle[0] == all_cycles[c - 1][1]:
@@ -933,7 +1005,6 @@ def check_cycle_order(all_cycles, info):
     1. Start latency earlier than end latency of previous SC
     2. End latency earlier then start latency of current SC
     """
-
     clean_cycles = []
     current_max_time = 0
     for c, cycle in enumerate(all_cycles):
@@ -1061,7 +1132,7 @@ def handle_issues(condition, info):
 # 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
+#    ==> see standardise_x_y_and_add_features_to_one_step & helper functions a
 # 4) immediately after adding features, we normalise a step to bin_num
 #    ==> see normalise_one_steps_data & helper functions b
 # 5) we add original and normalised steps to all_steps_data and normalised_steps_data
@@ -1078,20 +1149,40 @@ def analyse_and_export_stepcycles(data, all_cycles, info, folderinfo, cfg):
     save_to_xls = cfg["save_to_xls"]
     analyse_average_x = cfg["analyse_average_x"]
     bin_num = cfg["bin_num"]
+    standardise_x_coordinates = cfg["standardise_x_coordinates"]
     # do everything on a copy of the data df
     data_copy = data.copy()
     # exactly 1 step
     if len(all_cycles) == 1:
         this_step = data_copy.loc[all_cycles[0][0] : all_cycles[0][1]]
-        all_steps_data = norm_y_and_add_features_to_one_step(this_step, cfg)
-        normalised_steps_data = normalise_one_steps_data(all_steps_data, bin_num)
+        if standardise_x_coordinates:
+            all_steps_data, x_standardised_steps_data = (
+                standardise_x_y_and_add_features_to_one_step(this_step, 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
+            )
+            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 = 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
-        normalised_steps_data = normalise_one_steps_data(first_step, bin_num)
+        if standardise_x_coordinates:
+            all_steps_data, x_standardised_steps_data = (
+                standardise_x_y_and_add_features_to_one_step(first_step, 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
+            )
+            normalised_steps_data = normalise_one_steps_data(all_steps_data, bin_num)
         # some prep for addition of further steps
         sc_num = len(all_cycles)
         nanvector = data_copy.loc[[1]]
@@ -1107,13 +1198,29 @@ def analyse_and_export_stepcycles(data, all_cycles, info, folderinfo, cfg):
             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]]
-            this_step = norm_y_and_add_features_to_one_step(this_step, cfg)
+            if standardise_x_coordinates:
+                this_step, this_x_standardised_step = (
+                    standardise_x_y_and_add_features_to_one_step(this_step, 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_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
+            all_steps_data = add_step_separators(all_steps_data, nanvector, numvector)
             all_steps_data = pd.concat([all_steps_data, this_step], axis=0)
-            # this_normalised_step
-            this_normalised_step = normalise_one_steps_data(this_step, bin_num)
+            if standardise_x_coordinates:
+                x_standardised_steps_data = add_step_separators(
+                    x_standardised_steps_data, nanvector, numvector
+                )
+                x_standardised_steps_data = pd.concat(
+                    [x_standardised_steps_data, this_x_standardised_step], axis=0
+                )
             normalised_steps_data = add_step_separators(
                 normalised_steps_data, nanvector, numvector
             )
@@ -1121,6 +1228,8 @@ def analyse_and_export_stepcycles(data, all_cycles, info, folderinfo, cfg):
                 [normalised_steps_data, this_normalised_step], axis=0
             )
     # compute average & std data
+    # => note that normalised_steps_data is automatically based on x-standardisation
+    #    which translates to average_data & std_data
     average_data, std_data = compute_average_and_std_data(
         name, normalised_steps_data, bin_num, analyse_average_x
     )
@@ -1130,6 +1239,8 @@ def analyse_and_export_stepcycles(data, all_cycles, info, folderinfo, cfg):
     results["average_data"] = average_data
     results["std_data"] = std_data
     results["all_cycles"] = all_cycles
+    if standardise_x_coordinates:
+        results["x_standardised_steps_data"] = x_standardised_steps_data
     # save to files
     save_results_sheet(
         all_steps_data,
@@ -1149,27 +1260,47 @@ def analyse_and_export_stepcycles(data, all_cycles, info, folderinfo, cfg):
     save_results_sheet(
         std_data, save_to_xls, os.path.join(results_dir, name + STD_XLS_FILENAME)
     )
+    if standardise_x_coordinates:
+        save_results_sheet(
+            x_standardised_steps_data,
+            save_to_xls,
+            os.path.join(results_dir, name + X_STANDARDISED_XLS_FILENAME),
+        )
     return results
 
 
 # ......................................................................................
-# ...............  helper functions a - norm z and add features  .......................
+# ............  helper functions a - standardise x, y and add features  ................
 # ......................................................................................
 
 
-def norm_y_and_add_features_to_one_step(step, cfg):
-    """For a single step cycle's data, normalise z if wanted, flip y columns if needed
-    (to simulate equal run direction) and add features (angles & velocities)
-    """
-    # if user wanted this, normalise z (height) at step-cycle level
+def standardise_x_y_and_add_features_to_one_step(step, 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()
-    if cfg["normalise_height_at_SC_level"] is True:
+    if cfg["standardise_y_at_SC_level"] is True:
         y_cols = [col for col in step_copy.columns if col.endswith("y")]
-        this_y_min = step_copy[y_cols].min().min()
+        if cfg["standardise_y_to_a_joint"] is True:
+            # note the [0] here is important because it's still a list of len=1!!
+            this_y_min = step_copy[cfg["y_standardisation_joint"][0] + "y"].min()
+        else:
+            this_y_min = step_copy[y_cols].min().min()
         step_copy[y_cols] -= this_y_min
     # add angles and velocities
     step_copy = add_features(step_copy, cfg)
-    return step_copy
+    # standardise x (horizontal dimension) at step-cycle level too
+    if cfg["standardise_x_coordinates"] is True:
+        x_norm_step = step_copy.copy()
+        x_cols = [col for col in x_norm_step.columns if col.endswith("x")]
+        # note the [0] here is important because it's still a list of len=1!!
+        min_x_standardisation_joint = x_norm_step[
+            cfg["x_standardisation_joint"][0] + "x"
+        ].min()
+        x_norm_step[x_cols] -= min_x_standardisation_joint
+        x_norm_step = add_features(x_norm_step, cfg)
+        return step_copy, x_norm_step
+    else:
+        return step_copy
 
 
 def add_features(step, cfg):
@@ -1399,6 +1530,22 @@ def add_step_separators(dataframe, nanvector, numvector):
 
 # ..............................  master function  .............................
 
+# A note on x-standardisation (14.08.2024)
+# => If x-standardisation was performed, original as well as x-standardised dfs are
+#    generated and exported to xls
+# => Our plotting functions only used all_steps_data, average_data & std_data
+# => Conveniently, if x-standardisation is performed, all_steps_data DOES NOT include
+#    x-standardisation and is thus still the correct choice for the step-cycle level
+#    plots (#1-#5)
+# => On the other hand, average_data & std_data (plots #6-12) DO and SHOULD include
+#    x-standardisation
+# => Note that there is a slight discrepancy because angle-plots are based on
+#    x-standardised values  for the step-cycle level plots (#3) but not for the average
+#    plots (#8)
+#   -- This is not an issue since x-standardisation does not affect angles, even though
+#      the values of x change because they change by a constant for all joints (there
+#      is a unit test for this)
+
 # A note on updated colour cyclers after pull request that was merged 20.06.2024
 # => Using color palettes instead of colour maps as I had previously means that
 #    we cycle through neighbouring colours
@@ -1770,7 +1917,7 @@ def plot_hindlimb_stickdiagram(all_steps_data, sc_idxs, info, cfg, plot_panel_in
                 ax.plot(this_xs, this_ys, color=this_color, label=this_label)
             else:
                 ax.plot(this_xs, this_ys, color=this_color)
-    ax.set_title(name + " - Hindlimb Stick Diagram")
+    ax.set_title(name + " - Primary Stick Diagram")
     # legend adjustments
     if legend_outside is True:
         ax.legend(
@@ -1786,7 +1933,7 @@ def plot_hindlimb_stickdiagram(all_steps_data, sc_idxs, info, cfg, plot_panel_in
     else:
         ax.set_xlabel("x (pixels)")
         ax.set_ylabel("y (pixels)")
-    figure_file_string = " - Hindlimb Stick Diagram"
+    figure_file_string = " - Primary Stick Diagram"
     save_figures(f, results_dir, name, figure_file_string)
     if dont_show_plots:
         plt.close(f)
@@ -1834,7 +1981,7 @@ def plot_forelimb_stickdiagram(all_steps_data, sc_idxs, info, cfg, plot_panel_in
                 ax.plot(this_xs, this_ys, color=this_color, label=this_label)
             else:
                 ax.plot(this_xs, this_ys, color=this_color)
-    ax.set_title(name + " - Forelimb Stick Diagram")
+    ax.set_title(name + " - Secondary Stick Diagram")
     if convert_to_mm:
         tickconvert_mm_to_cm(ax, "both")
     # legend adjustments
@@ -1852,7 +1999,7 @@ def plot_forelimb_stickdiagram(all_steps_data, sc_idxs, info, cfg, plot_panel_in
     else:
         ax.set_xlabel("x (pixels)")
         ax.set_ylabel("y (pixels)")
-    figure_file_string = " - Forelimb Stick Diagram"
+    figure_file_string = " - Secondary Stick Diagram"
     save_figures(f, results_dir, name, figure_file_string)
     if dont_show_plots:
         plt.close(f)