biomechzoo 0.1.1__py3-none-any.whl

biomechzoo/__init__.py

@@ -0,0 +1,5 @@
+from .biomechzoo import BiomechZoo  # or from .core, etc.
+
+__all__ = ['BiomechZoo']
+
+__version__ = "0.1.0"

biomechzoo/__main__.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from biomechzoo!")
+
+
+if __name__ == "__main__":
+    main()

biomechzoo/biomech_ops/continuous_relative_phase_data.py

@@ -0,0 +1,31 @@
+from biomechzoo.biomech_ops.continuous_relative_phase_line import continuous_relative_phase_line
+from biomechzoo.processing.addchannel_data import addchannel_data
+
+
+def continuous_relative_phase_data(data, ch_dist, ch_prox):
+    """ This function determines the CRP on a 0-180 scale, correcting for
+           discontinuity in the signals >180.
+    See Also phase_angle_data.py and phase_angle_line.py
+    """
+
+    data_new = data.copy()
+    prox = data[ch_prox]['line']
+    dist = data[ch_dist]['line']
+    crp = continuous_relative_phase_line(dist, prox)
+    data_new = addchannel_data(data_new, ch_new_name=ch_dist + '_' + ch_prox + '_' + 'crp', ch_new_data=crp)
+    return data_new
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from biomechzoo.utils.zload import zload
+    from biomechzoo.utils.zplot import zplot
+    # note: crp should be computed on phase angle data. Here we just demonstrate that it works.
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC032A18_exploded.zoo')
+    data = zload(fl)
+    data = continuous_relative_phase_data(data, ch_dist='RKneeAngles_x', ch_prox='RHipAngles_x')
+    zplot(data, 'RKneeAngles_x_RHipAngles_x_crp')
+

biomechzoo/biomech_ops/continuous_relative_phase_line.py

@@ -0,0 +1,36 @@
+def continuous_relative_phase_line(dist, prox):
+    """ This function determines the CRP on a 0-180 scale, correcting for
+       discontinuity in the signals >180.
+
+    Arguments
+    dist, ndarray: data of distal segment or joint
+    prox, ndarray: data of proximal segment or joibt
+
+    Returns
+    crp, ndarray: continous relative phase betweeen dist and prox data
+    """
+    temp_CRP = abs(dist - prox)
+    idx = temp_CRP > 180  # This corrects discontinuity in the data and puts everything on a 0-180 scale.
+    temp_CRP[idx] = 360 - temp_CRP[idx]
+    crp = temp_CRP
+    return crp
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from biomechzoo.utils.zload import zload
+    from biomechzoo.biomech_ops.phase_angle_line import phase_angle_line
+    from matplotlib import pyplot as plt
+    # note: crp should be computed on phase angle data. Here we just demonstrate that it works.
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC032A18_exploded.zoo')
+    data = zload(fl)
+    knee = data['RKneeAngles_x']['line']
+    hip = data['RHipAngles_x']['line']
+    knee_pa = phase_angle_line(knee)
+    hip_pa = phase_angle_line(hip)
+    crp = continuous_relative_phase_line(knee_pa, hip_pa)
+    plt.plot(crp)
+    plt.show()

biomechzoo/biomech_ops/filter_data.py

@@ -0,0 +1,56 @@
+from biomechzoo.biomech_ops.filter_line import filter_line
+
+
+def filter_data(data, ch, filt=None):
+    """
+    Filter one or more channels from a zoo data dictionary using specified filter parameters.
+
+    Arguments
+    ----------
+    data : dict
+        The zoo data dictionary containing signal channels.
+    ch : str or list of str
+        The name(s) of the channel(s) to filter.
+    filt : dict, optional
+        Dictionary specifying filter parameters. Keys may include:
+        - 'type': 'butter' (default)
+        - 'order': filter order (default: 4)
+        - 'cutoff': cutoff frequency or tuple (Hz)
+        - 'btype': 'low', 'high', 'bandpass', 'bandstop' (default: 'low')
+
+    Returns
+    -------
+    dict
+        The updated data dictionary with filtered channels.
+    """
+
+    if filt is None:
+        filt = {}
+
+    if isinstance(ch, str):
+        ch = [ch]
+
+    analog_channels = data['zoosystem']['Analog']['Channels']
+    if analog_channels:
+        analog_freq = data['zoosystem']['Analog']['Freq']
+    video_channels = data['zoosystem']['Video']['Channels']
+    if video_channels:
+        video_freq = data['zoosystem']['Video']['Freq']
+
+    for c in ch:
+        if c not in data:
+            raise KeyError('Channel {} not found in data'.format(c))
+
+        if 'fs' not in filt:
+            if c in analog_channels:
+                filt['fs'] = analog_freq
+            elif c in video_freq:
+                filt['fs'] = video_freq
+            else:
+                raise ValueError('frequency not provided and cannot be inferred from zoosystem for channel'.format(c))
+
+        signal_raw = data[c]['line']
+        signal_filtered = filter_line(signal_raw, filt)
+        data[c]['line'] = signal_filtered
+
+    return data

biomechzoo/biomech_ops/filter_line.py

@@ -0,0 +1,88 @@
+import numpy as np
+from scipy.signal import butter, filtfilt
+
+
+def filter_line(signal_raw, filt):
+    """ filter an array
+
+    Arguments
+    ----------
+    signal_raw : n, or n x 3 array signal to be filtered
+    filt : dict, optional
+        Dictionary specifying filter parameters. Keys may include:
+        - 'type': 'butter' (default)
+        - 'order': filter order (default: 4)
+        - 'cutoff': cutoff frequency or tuple (Hz)
+        - 'btype': 'low', 'high', 'bandpass', 'bandstop' (default: 'low')
+        - 'fs' frequency
+
+    Returns
+    -------
+    signal_filtered: filtered version of signal_raw"""
+    # todo allow for missing frequency to be obtained from zoosystem metadata
+    if filt is None:
+        filt = {}
+    if filt['type'] is 'butterworth':
+        filt['type'] = 'butter'
+    # Set default filter parameters
+    ftype = filt.get('type', 'butter')
+    order = filt.get('order', 4)
+    cutoff = filt.get('cutoff', None)
+    btype = filt.get('btype', 'low')
+    fs = filt.get('fs', None)
+
+    if ftype != 'butter':
+        raise NotImplementedError(f"Filter type '{ftype}' not implemented.")
+
+    if fs is None:
+        raise ValueError("Sampling frequency 'fs' must be specified in filt.")
+
+    if cutoff is None:
+        raise ValueError("Cutoff frequency 'cutoff' must be specified in filt.")
+
+    nyq = 0.5 * fs
+    norm_cutoff = np.array(cutoff) / nyq
+
+    b, a = butter(order, norm_cutoff, btype=btype, analog=False)
+
+    if signal_raw.ndim == 1:
+        signal_filtered = filtfilt(b, a, signal_raw)
+    else:
+        # Apply filter to each column if multivariate
+        signal_filtered = np.array([filtfilt(b, a, signal_raw[:, i]) for i in range(signal_raw.shape[1])]).T
+
+    return signal_filtered
+
+
+if __name__ == '__main__':
+    """ -------TESTING--------"""
+    import os
+    import matplotlib.pyplot as plt
+    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')
+    data = zload(fl)
+    data = data['data']
+    signal_raw = data['ForceFz1']['line']
+    filt = {'type': 'butterworth',
+            'order': 3,
+            'cutoff': 20,
+            'btype': 'low',
+            'fs': data['zoosystem']['Analog']['Freq']
+            }
+    signal_filtered = filter_line(signal_raw, filt)
+
+    # now plot
+    plt.figure(figsize=(10, 4))
+    plt.plot(signal_raw, label='Raw', alpha=0.6)
+    plt.plot(signal_filtered, label='Filtered', linewidth=2)
+    plt.xlabel('Frame')
+    plt.ylabel('Amplitude')
+    plt.title('Testing filter_line')
+    plt.legend()
+    plt.grid(True)
+    plt.tight_layout()
+    plt.show()
+
+

biomechzoo/biomech_ops/normalize_data.py

@@ -0,0 +1,35 @@
+import warnings
+from biomechzoo.biomech_ops.normalize_line import normalize_line
+
+
+def normalize_data(data, nlength=101):
+    """normalize all channels in the loaded zoo dict to nlen.
+    Arguments
+        data: dict, loaded zoo file
+        nlength: int: new length of data. Default = 101, usually a movement cycle
+    Returns:
+        None
+    Notes:
+        -It is often needed to partition data to a single cycle first (see partition_data)
+    """
+
+    # normalize channel length
+    data_new = data.copy()
+    for ch_name, ch_data in data_new.items():
+        if ch_name != 'zoosystem':
+            ch_data_line = ch_data['line']
+            ch_data_event = ch_data['event']
+            ch_data_normalized = normalize_line(ch_data_line, nlength)
+    data_new[ch_name]['line'] = ch_data_normalized
+    data_new[ch_name]['event'] = ch_data_event
+    warnings.warn('event data have not been normalized')
+
+    # update zoosystem
+    # todo: update all relevant zoosystem meta data related to data lengths
+    warnings.warn('zoosystem data have not been fully updated')
+    if 'Video' in data['zoosystem']:
+        data['zoosystem']['Video']['CURRENT_END_FRAME'] = nlength
+    if 'Analog' in data['zoosystem']:
+        data['zoosystem']['Analog']['CURRENT_END_FRAME'] = nlength
+
+    return data_new

biomechzoo/biomech_ops/normalize_line.py

@@ -0,0 +1,27 @@
+import numpy as np
+from scipy.interpolate import interp1d
+
+
+def normalize_line(channel_data, nlength=101):
+    """
+    Channel-level: interpolate channel data to target length.
+    Assumes channel_data is a 1D or 2D numpy array.
+    """
+    original_length = channel_data.shape[0]
+
+    if original_length == nlength:
+        return channel_data
+
+    x_original = np.linspace(0, 1, original_length)
+    x_target = np.linspace(0, 1, nlength)
+
+    if channel_data.ndim == 1:
+        f = interp1d(x_original, channel_data, kind='linear')
+        channel_data_norm = f(x_target)
+    else:
+        channel_data_norm = np.zeros((nlength, channel_data.shape[1]))
+        for i in range(channel_data.shape[1]):
+            f = interp1d(x_original, channel_data[:, i], kind='linear')
+            channel_data_norm[:, i] = f(x_target)
+
+    return channel_data_norm

biomechzoo/biomech_ops/phase_angle_data.py

@@ -0,0 +1,39 @@
+from biomechzoo.biomech_ops.phase_angle_line import phase_angle_line
+from biomechzoo.processing.addchannel_data import addchannel_data
+
+
+def phase_angle_data(data, channels):
+    """Compute phase angle using Hilbert Transform.
+    Arguments
+        data: dict, zoo data to operate on
+        channels, list. Channel names on which to apply calculations
+    Returns:
+        data: dict, zoo data with calculations appended to new channel(s)
+    """
+    data_new = data.copy()
+    for ch in channels:
+        if ch not in data_new:
+            raise ValueError('Channel {} not in data. Available keys: {}'.format(ch, list(data_new.keys())))
+        r = data_new[ch]['line']
+        phase_angle = phase_angle_line(r)
+        ch_new = ch + '_phase_angle'
+        data_new = addchannel_data(data_new, ch_new_name=ch_new, ch_new_data=phase_angle)
+    return data_new
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from biomechzoo.utils.zload import zload
+    from 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', 'HC032A18_exploded.zoo')
+
+    # load  zoo file
+    data = zload(fl)
+    data = data['data']
+    data = phase_angle_data(data, channels=['RKneeAngles_x', 'RHipAngles_x'])
+    zplot(data, 'RKneeAngles_x_phase_angle')
+

biomechzoo/biomech_ops/phase_angle_line.py

@@ -0,0 +1,48 @@
+import numpy as np
+from scipy.signal import hilbert
+
+
+def phase_angle_line(r):
+    """
+    Computes the phase angle for a single kinematic waveform using the Hilbert transform method.
+
+    Parameters:
+    r : array_like
+        (n, 1) array of kinematic data (e.g., joint or segment angle)
+
+    Returns:
+    PA_data : ndarray
+        1D array of phase angle (in degrees) computed from input using the Hilbert transform.
+
+    Reference:
+    Lamb and Stöckl (2014). "On the use of continuous relative phase..."
+    Clinical Biomechanics. https://doi.org/10.1016/j.clinbiomech.2014.03.008
+    """
+
+    # Step 1: Center the data around zero as per Lamb and Stöckl eq. 11
+    cdata = r - np.min(r) - (np.max(r) - np.min(r)) / 2
+
+    # Step 2: Hilbert transform
+    X = hilbert(cdata)
+
+    # Step 3: Phase angle calculation
+    PA = np.rad2deg(np.arctan2(np.imag(X), np.real(X)))
+
+    return PA
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from biomechzoo.utils.zload import zload
+    from matplotlib import pyplot as plt
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(current_dir)
+    fl = os.path.join(project_root, 'data', 'other', 'HC032A18_exploded.zoo')
+    data = zload(fl)
+    print(data)
+    r = data['RKneeAngles_x']['line']
+    phase_angle = phase_angle_line(r)
+    plt.plot(phase_angle)
+    plt.show()
+