biomechzoo 0.1.1__py3-none-any.whl

biomechzoo/processing/add_channel_data.py

@@ -0,0 +1,71 @@
+import numpy as np
+
+
+def add_channel_data(data, ch_new_name, ch_new_data, section='Video'):
+    """
+    Add a new channel to zoo data.
+
+    Parameters
+    ----------
+    data : dict
+        Zoo file data.
+    ch_new_name : str
+        Name of the new channel.
+    ch_new_data : array-like
+        New data to be added to the channel (should be n x 1 or n x 3).
+    section : str
+        Section of zoo data ('Video' or 'Analog').
+
+    Returns
+    -------
+    dict
+        Updated zoo data with new channel added.
+
+    Notes
+    -----
+    - If the channel already exists, it will be overwritten.
+    - Adds channel name to the list in data['zoosystem'][section]['Channels'].
+    """
+
+    # Warn if overwriting
+    if ch_new_name in data:
+        print('Warning: channel {} already exists, overwriting...'.format(ch_new_name))
+
+# Assign channel data
+    data[ch_new_name] = {
+        'line': ch_new_data,
+        'event': {}
+    }
+
+    # Update channel list
+    ch_list = data['zoosystem'][section].get('Channels', [])
+
+    # If the channel list is a NumPy array, convert it to a list
+    if isinstance(ch_list, np.ndarray):
+        ch_list = ch_list.tolist()
+
+    # Ensure it's a flat list of strings
+    if isinstance(ch_list, list) and ch_new_name not in ch_list:
+        ch_list.append(ch_new_name)
+        data['zoosystem'][section]['Channels'] = ch_list
+
+    return data
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from src.biomechzoo.utils.zload import zload
+    from src.biomechzoo.utils.zplot import zplot
+    # get path to sample zoo file
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC030A05.zoo')
+
+    # load  zoo file
+    data = zload(fl)
+    data = data['data']
+    r = data['RKneeAngles']['line']*3
+    data= add_channel_data(data, ch_new_name='blah', ch_new_data=r)
+    zplot(data, 'blah')
+

biomechzoo/processing/addchannel_data.py

@@ -0,0 +1,71 @@
+import numpy as np
+
+
+def addchannel_data(data, ch_new_name, ch_new_data, section='Video'):
+    """
+    Add a new channel to zoo data.
+
+    Parameters
+    ----------
+    data : dict
+        Zoo file data.
+    ch_new_name : str
+        Name of the new channel.
+    ch_new_data : array-like
+        New data to be added to the channel (should be n x 1 or n x 3).
+    section : str
+        Section of zoo data ('Video' or 'Analog').
+
+    Returns
+    -------
+    dict
+        Updated zoo data with new channel added.
+
+    Notes
+    -----
+    - If the channel already exists, it will be overwritten.
+    - Adds channel name to the list in data['zoosystem'][section]['Channels'].
+    """
+
+    # Warn if overwriting
+    if ch_new_name in data:
+        print('Warning: channel {} already exists, overwriting...'.format(ch_new_name))
+
+# Assign channel data
+    data[ch_new_name] = {
+        'line': ch_new_data,
+        'event': {}
+    }
+
+    # Update channel list
+    ch_list = data['zoosystem'][section].get('Channels', [])
+
+    # If the channel list is a NumPy array, convert it to a list
+    if isinstance(ch_list, np.ndarray):
+        ch_list = ch_list.tolist()
+
+    # Ensure it's a flat list of strings
+    if isinstance(ch_list, list) and ch_new_name not in ch_list:
+        ch_list.append(ch_new_name)
+        data['zoosystem'][section]['Channels'] = ch_list
+
+    return data
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from src.biomechzoo.utils.zload import zload
+    from src.biomechzoo.utils.zplot import zplot
+    # get path to sample zoo file
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC030A05.zoo')
+
+    # load  zoo file
+    data = zload(fl)
+    data = data['data']
+    r = data['RKneeAngles']['line']*3
+    data= addchannel_data(data, ch_new_name='blah', ch_new_data=r)
+    zplot(data, 'blah')
+

biomechzoo/processing/addevent_data.py

@@ -0,0 +1,46 @@
+import numpy as np
+
+
+def addevent_data(data, ch, ename, etype):
+    if isinstance(ch, str):
+        ch = [ch]
+
+    if len(ch) == 1 and ch[0].lower() == 'all':
+        ch = [key for key in data if key != 'zoosystem']
+
+    for channel in ch:
+        if ename == '':
+            data[channel]['event'] = {}
+            continue
+
+        if channel not in data:
+            print(f'Channel {channel} does not exist')
+            continue
+
+        yd = data[channel]['line']  # 1D array
+        etype = etype.lower()
+        if etype == 'absmax':
+            exd = int(np.argmax(np.abs(yd)))
+            eyd = float(yd[exd])
+        elif etype == 'first':
+            exd = 0
+            eyd = float(yd[exd])
+        elif etype == 'last':
+            exd = len(yd) - 1
+            eyd = float(yd[exd])
+        elif etype == 'max':
+            exd = int(np.argmax(yd))
+            eyd = float(yd[exd])
+        elif etype == 'min':
+            exd = int(np.argmin(yd))
+            eyd = float(yd[exd])
+        elif etype == 'rom':
+            eyd = float(np.max(yd) - np.min(yd))
+            exd = 0  # dummy index (like MATLAB version)
+        else:
+            raise ValueError(f'Unknown event type: {etype}')
+
+        # Add event to the channel's event dict
+        data[channel]['event'][ename] = [exd, eyd, 0]
+
+    return data

biomechzoo/processing/explodechannel_data.py

@@ -0,0 +1,46 @@
+def explodechannel_data(data, channels=None):
+    """ Explodes 3D channels (n x 3 arrays) into separate X, Y, Z channels.
+
+    Arguments:
+        data (dict): Zoo data loaded from a file
+        channels (list of str or None): Channels to explode.
+        If None, explode all channels with 'line' shaped (n x 3).
+
+    Returns:
+        data_new (dict): Modified zoo dictionary with exploded channels.
+    """
+
+    data_new = data.copy()
+
+    # Find default channels if none provided
+    if channels is None:
+        channels = []
+        for ch in data_new:
+            if ch == 'zoosystem':
+                continue
+            ch_data = data_new[ch]['line']
+            if ch_data.ndim == 2 and ch_data.shape[1] == 3:
+                channels.append(ch)
+
+    # Explode each channel
+    for ch in channels:
+        if ch not in data_new:
+            print('Warning: channel {} not found, skipping.'.format(ch))
+            continue
+
+        ch_data = data_new[ch]['line']
+        if ch_data.ndim != 2 or ch_data.shape[1] != 3:
+            print(f"Warning: channel '{ch}' 'line' is not n x 3 shape, skipping.")
+            continue
+
+        x, y, z = ch_data[:, 0], ch_data[:, 1], ch_data[:, 2]
+        for axis, line in zip(['_x', '_y', '_z'], [x, y, z]):
+            key = ch + axis
+            data_new[key] = {
+                'line': line,
+                'event': data[ch]['event']}
+
+        # Remove original channel
+        del data_new[ch]
+
+    return data_new

biomechzoo/processing/partition_data.py

@@ -0,0 +1,51 @@
+from biomechzoo.utils.findfield import findfield
+import warnings
+
+
+def partition_data(data, evt_start, evt_end):
+    """ partition data for all channels between events evt_start and evt_end"""
+
+    # extract event values
+    e1, _ = findfield(data,evt_start)
+    e2, _ = findfield(data,evt_end)
+
+    data_new = data.copy()
+    for ch_name, ch_data in data_new.items():
+        if ch_name != 'zoosystem':
+            try:
+                data_new[ch_name]['line'] = ch_data[e1[0]:e2[0], :]
+            except (IndexError, ValueError) as e:
+                # IndexError: if e1[0]:e2[0] goes beyond the available indices
+                # ValueError: less likely, but may arise with shape mismatches
+                warnings.warn(f"Skipping {ch_name} due to error: {e}")
+
+            # partition events
+            events = ch_data['event']
+            for event_name, value in events.items():
+                original_frame = value[0]
+                if original_frame == 1:
+                    continue  # leave index 1 as is (per MATLAB version)
+                elif original_frame == 999:
+                    continue  # do not change outlier markers
+                else:
+                    new_frame = original_frame - e1[0] + 1
+                    data_new[ch_name]['event'][event_name][0] = new_frame
+
+    return data_new
+
+
+def _partition_line(arr, evt_start, evt_end):
+    arr_new = arr[evt_start:evt_end, :]
+    return arr_new
+
+
+def _partition_event(event_dict, evt_start, evt_end, arr_len):
+    raise NotImplementedError
+    # event_dict_new = {}
+    # for event, event_val in event_dict:
+    #     event_val_new =
+    #     event_dict_new[event] =
+    #
+    #
+    #
+    # return event_dict_new

biomechzoo/processing/removechannel_data.py

@@ -0,0 +1,36 @@
+def removechannel_data(data, channels, mode='remove'):
+    """
+    File-level processing: Remove or keep specified channels in a single zoo dictionary.
+
+    Parameters:
+    - data (dict): Zoo data loaded from a file
+    - channels (list of str): List of channels to remove or keep
+    - mode (str): 'remove' or 'keep'
+
+    Returns:
+    - dict: Modified zoo dictionary with updated channels
+    """
+    if mode not in ['remove', 'keep']:
+        raise ValueError("mode must be 'remove' or 'keep'.")
+
+    zoosystem = data.get('zoosystem', {})
+    all_channels = [ch for ch in data if ch != 'zoosystem']
+
+    # Check for missing channels
+    missing = [ch for ch in channels if ch not in all_channels]
+    if missing:
+        print('Warning: the following channels were not found {}'.format(missing))
+
+    if mode == 'remove':
+        keep_channels = [ch for ch in all_channels if ch not in channels]
+    elif mode == 'keep':
+        keep_channels = [ch for ch in all_channels if ch in channels]
+    else:
+        raise ValueError("Mode must be 'remove' or 'keep'.")
+
+    # Build new zoo dictionary
+    data_new = {'zoosystem': zoosystem}
+    for ch in keep_channels:
+        data_new[ch] = data[ch]
+
+    return data_new

biomechzoo/processing/renamechannel_data.py

@@ -0,0 +1,79 @@
+import numpy as np
+
+
+def renamechannel_data(data, ch_old_names, ch_new_names, section='Video'):
+    """
+    Rename channels in a zoo data.
+
+    Parameters
+    ----------
+    data : dict
+        Zoo file data.
+    ch_old_names : str or list
+        Name of the old channels.
+    ch_new_names : str or list
+        Name of the new channels.
+
+    section : str
+        Section of zoo data ('Video' or 'Analog').
+
+    Returns
+    -------
+    dict
+        Updated zoo data with new channel added.
+
+    Notes
+    -----
+    - If the channel already exists, it will be overwritten.
+    - Adds channel name to the list in data['zoosystem'][section]['Channels'].
+    """
+
+    for i, ch_old_name in enumerate(ch_old_names):
+        ch_new_name = ch_new_names[i]
+        # Warn if overwriting
+        if ch_new_name in data:
+            print('Warning: channel {} already exists, overwriting...'.format(ch_new_name))
+
+        # Assign new channel
+        data[ch_new_name] = {
+            'line': data[ch_old_name]['line'],
+            'event': data[ch_old_name]['event']
+        }
+
+        # remove old channel
+        data.pop(ch_old_name)
+
+    # Update channel list
+    ch_list = data['zoosystem'][section].get('Channels', [])
+
+    # If the channel list is a NumPy array, convert it to a list
+    if isinstance(ch_list, np.ndarray):
+        ch_list = ch_list.tolist()
+
+    # Ensure it's a flat list of strings
+    if isinstance(ch_list, list) and ch_new_name not in ch_list:
+        ch_list.append(ch_new_name)
+        data['zoosystem'][section]['Channels'] = ch_list
+
+    return data
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from src.biomechzoo.utils.zload import zload
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC030A05.zoo')
+
+    # load  zoo file
+    data = zload(fl)
+    ch_old_name = 'RKneeAngles'
+    ch_new_name = 'RightKneeAngles'
+    data = renamechannel_data(data, ch_old_name=ch_old_name, ch_new_name=ch_new_name)
+
+    if ch_old_name not in data:
+        print('RkneeAngles removed')
+    if ch_new_name in data:
+        print('RightKneeAngles added')
+

biomechzoo/processing/renameevent_data.py

@@ -0,0 +1,68 @@
+def renameevent_data(data, evt, nevt):
+    """
+    Rename events in the Zoo data structure.
+
+    Parameters
+    ----------
+    data : dict
+        The Zoo-formatted dictionary.
+    evt : str or list of str
+        Names of existing events to rename.
+    nevt : str or list of str
+        Names of new events to apply.
+
+    Returns
+    -------
+    data : dict
+        Updated Zoo data with renamed events.
+    """
+    # Convert to list if passed as single string
+    if isinstance(evt, str):
+        evt = [evt]
+    if isinstance(nevt, str):
+        nevt = [nevt]
+
+    if len(evt) != len(nevt):
+        raise ValueError("`evt` and `nevt` must have the same length.")
+
+    # Get all data channels except 'zoosystem'
+    channels = [ch for ch in data if ch != 'zoosystem']
+    for old_name, new_name in zip(evt, nevt):
+        eventsRenamed = False
+        for ch in channels:
+            events = data[ch].get('event', {})
+            if old_name in events:
+                print('Renaming event {} in channel {} to {}'.format(old_name, ch, new_name))
+                data[ch]['event'][new_name] = events[old_name]
+                del data[ch]['event'][old_name]
+                eventsRenamed = True
+
+        if not eventsRenamed:
+            print('no event {} found in any channel'.format(old_name))
+
+    return data
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from src.biomechzoo.utils.zload import zload
+    # get path to sample zoo file
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC030A05.zoo')
+
+    # load  zoo file
+    data = zload(fl)
+    evt = ['Left_FootStrike1', 'Left_FootStrike2', 'NonExistingEvent']
+
+    # see existing keys
+    missing = [k for k in evt if k not in data['SACR']['event']]
+    print("Missing keys:", missing)   # expected behavior is missing 'NonExistingEvent'
+
+    nevt = ['LFS_1', 'LFS2', 'NE_1']
+    data = renameevent_data(data, evt=evt, nevt=nevt)
+
+    # after applying renameevent_data
+    missing = [k for k in nevt if k not in data['SACR']['event']]
+    print("Missing keys:", missing)   # expected behavior is missing 'NE_1'

biomechzoo/processing/split_trial_by_gait_cycle.py

@@ -0,0 +1,52 @@
+import numpy as np
+import os
+import scipy.io as sio
+from biomechzoo.utils.findfield import findfield
+
+
+def split_trial_by_gait_cycle(fl, event_name):
+    """ splits lengthy trials containing n cycles into n trials based on side"""
+
+    # extract folder and file name
+    fld = os.path.dirname(fl)
+    fl_name = os.path.splitext(os.path.basename(fl))[0]
+
+    # load file
+    data = zload(fl)
+
+    # find all events, events should follow style name1, name2, etc..
+    split_events = []
+    i = 1
+    _, channel_name = findfield(data, event_name)
+    event_name_root = event_name[0:-1]
+    while True:
+        key = f"{event_name_root}{i}"
+        if key in data[channel_name]['event']:
+            split_events.append(data[channel_name]['event'][key])
+            i += 1
+        else:
+            break
+
+    n_segments = len(split_events) - 1
+    if n_segments < 1:
+        print("Not enough {} events to split.".format(event_name_root))
+        return
+
+    for i in range(n_segments):
+
+        start = split_events[i][0]
+        end = split_events[i + 1][0]
+        fl_new = os.path.join(fld, fl_name + '_' + str(i+1) + '.zoo')
+        data_new = _split_trial(fld, fl_new, start, end)
+
+def _split_trial(fld, fl_new, start, end):
+    raise NotImplementedError
+
+if __name__ == '__main__':
+    """ testing: load a single zoo file from the other subfolder in data"""
+    # -------TESTING--------
+    from src.biomechzoo.utils.zload import zload
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC030A05.zoo')
+    split_trial_by_gait_cycle(fl, event_name='Right_FootStrike1')

biomechzoo/utils/batchdisp.py

@@ -0,0 +1,21 @@
+def batchdisp(msg, level=1, verbose='none'):
+    """ utility to control verbosity level during batch processing"""
+    level = _normalize_verbose(level)
+    verbose = _normalize_verbose(verbose)
+    if verbose >= level:
+        print(msg)
+
+def _normalize_verbose(verbose):
+    if isinstance(verbose, int):
+        if verbose not in (0, 1, 2):
+            raise ValueError("Integer verbose level must be 0 (none), 1 (minimal), or 2 (all)")
+        return verbose
+    elif isinstance(verbose, str):
+        verbose_map = {'none': 0, 'minimal': 1, 'all': 2}
+        if verbose.lower() not in verbose_map:
+            raise ValueError("String verbose level must be 'none', 'minimal', or 'all'")
+        return verbose_map[verbose.lower()]
+    else:
+        raise TypeError("Verbose must be an int (0–2) or str ('none', 'minimal', 'all')")
+
+

biomechzoo/utils/compute_sampling_rate_from_time.py

@@ -0,0 +1,25 @@
+import numpy as np
+
+
+def compute_sampling_rate_from_time(t, verbose=False):
+    """ computes sampling rate from time column
+    Arguments
+    t, 1D numpy array, recorded times
+
+    Returns
+    fsamp, int: sampling rate of capture
+    """
+    # Calculate differences between consecutive time points
+    dt = np.diff(t)
+
+    # Average time difference (seconds)
+    avg_dt = np.mean(dt)
+
+    # Sampling frequency (Hz)
+    # Sampling frequency (Hz)
+    fsamp = int(np.round(1 / avg_dt))
+
+    if verbose:
+        print('Inferred sampling rate: {} Hz'.format(fsamp))
+
+    return fsamp

biomechzoo/utils/engine.py

@@ -0,0 +1,68 @@
+import os
+
+
+def engine(root_folder, extension='.zoo', subfolders=None, name_contains=None, verbose=False):
+    """
+    Recursively search for files with a given extension, optionally filtering by
+    specific subfolders and substrings in filenames.
+
+    This function walks through every directory and subdirectory starting at
+    'root_folder'. If 'subfolders' is provided, it limits the search only to those
+    folders (or any of their subfolders) whose names appear in 'subfolders'. For
+    example, if subfolders=['Straight'], it will only consider files inside any
+    folder named 'Straight' at any depth within the root folder.
+
+    For each file found, it checks whether the file's extension matches the given
+    'extension' (case-insensitive). If 'name_contains' is specified, it also
+    requires the filename to contain that substring (case-insensitive).
+
+    Arguments:
+        root_folder (str): The root directory path where the search begins.
+        extension (str): File extension to search for (e.g., '.zoo', '.c3d'). Default .zoo
+        subfolders (list of str, optional): List of folder names to restrict the search to.
+            Only files inside these folders (or their subfolders) are included.
+            If None, search all subfolders.
+        name_contains (str, optional): Substring that must be present in the filename
+            (case-insensitive). If None, no substring filtering is applied.
+        verbose (bool, optional): If true, displays additional information to user
+    Returns:
+        list of str: List of full file paths matching the criteria.
+    """
+    matched_files = []
+
+    subfolders_set = set(subfolders) if subfolders else None
+
+    for dirpath, _, filenames in os.walk(root_folder):
+        if subfolders_set is not None:
+            rel_path = os.path.relpath(dirpath, root_folder)
+            if rel_path == '.':
+                continue
+            # Split the relative path into all folder parts
+            parts = rel_path.split(os.sep)
+            # Check if any folder in the path matches one in subfolders_set
+            if not any(part in subfolders_set for part in parts):
+                continue
+
+        for file in filenames:
+            if not file.lower().endswith(extension.lower()):
+                continue
+            if name_contains and name_contains.lower() not in file.lower():
+                continue
+            matched_files.append(os.path.join(dirpath, file))
+
+    if verbose:
+        print("Found {} {} files in subfolders named {} with substring {}:".format(len(matched_files), extension, subfolders, name_contains))
+        for f in matched_files:
+            print(" - {}".format(f))
+
+    return matched_files
+
+
+if __name__ == '__main__':
+    """ testing: use engine to search for files in any subfolder called 'Straight' for files with the substring 'HC03'
+    with extension .c3d in the sample study folder (data)"""
+    # -------TESTING--------
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    sample_dir = os.path.join(project_root, 'data', 'sample_study', 'raw c3d files')
+    c3d_files = engine(sample_dir, '.c3d', subfolders=['Straight'], name_contains='HC03', verbose=True)

biomechzoo/utils/findfield.py

@@ -0,0 +1,11 @@
+def findfield(data, target_event):
+    """ searches in zoo data for the event value and channel name associated with target_event"""
+    for channel, content in data.items():
+        if channel == 'zoosystem':
+            continue
+        events = content.get('event', {})
+        if target_event in events:
+            return events[target_event], channel
+    return None, None
+
+

biomechzoo/utils/get_split_events.py

@@ -0,0 +1,33 @@
+from biomechzoo.utils.findfield import findfield
+
+
+def get_split_events(data, first_event_name):
+    """ splits lengthy trials containing n cycles into n trials based on side"""
+
+    # find all events, events should follow style name1, name2, etc..
+    split_events = []
+    _, channel_name = findfield(data, first_event_name)
+    if channel_name is None:
+        return None
+
+    event_name_root = first_event_name[0:-1]
+    first_event_number = int(first_event_name[-1])
+    i = 1
+    if first_event_number > 1:
+        i = first_event_number
+
+    while True:
+        key = f"{event_name_root}{i}"
+        if key in data[channel_name]['event']:
+            split_events.append(key)
+            i += 1
+        else:
+            break
+
+    n_segments = len(split_events) - 1
+    if n_segments < 1:
+        print("Not enough {} events to split.".format(event_name_root))
+        return
+
+    return split_events
+