biomechzoo 0.5.3__tar.gz

biomechzoo-0.5.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] McGill MOTION Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

biomechzoo-0.5.3/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: biomechzoo
+Version: 0.5.3
+Summary: Python implementation of the biomechZoo toolbox
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mcgillmotionlab/biomechzoo
+Requires-Python: <3.12,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ezc3d>=1.5.19
+Requires-Dist: matplotlib>=3.10.6
+Requires-Dist: numpy==2.2.6
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: scipy>=1.16.2
+Requires-Dist: pyarrow>=19.0.0
+Dynamic: license-file
+
+# BiomechZoo for Python
+This is a development version of the biomechzoo toolbox for python. 
+
+## How to install 
+- biomechZoo for python is now an official package, you can simply add biomechZoo to your environment using
+``pip install biomechzoo``
+
+## Usage notes
+- If you need to install a specific version, run ``pip install biomechzoo==x.x.x`` where x.x.x is the version number. 
+- If you need to update biomechzoo to the latest version in your env, run ``pip install biomechzoo --upgrade``
+
+## Dependencies notes
+- We use Python 3.11 for compatibility with https://github.com/stanfordnmbl/opencap-processing
+- We use Numpy 2.2.6 for compatibility with https://pypi.org/project/numba/
+
+See also http://www.github.com/mcgillmotionlab/biomechzoo or http://www.biomechzoo.com for more information
+
+## Developer notes
+
+### Installing a dev environment
+conda create -n biomechzoo-dev python=3.11
+conda activate biomechzoo-dev
+cd biomechzoo root folder
+pip install -e ".[dev]"
+
+### import issues
+if using PyCharm: 
+- Right-click on src/.
+- Select Mark Directory as → Sources Root.

biomechzoo-0.5.3/README.md

@@ -0,0 +1,29 @@
+# BiomechZoo for Python
+This is a development version of the biomechzoo toolbox for python. 
+
+## How to install 
+- biomechZoo for python is now an official package, you can simply add biomechZoo to your environment using
+``pip install biomechzoo``
+
+## Usage notes
+- If you need to install a specific version, run ``pip install biomechzoo==x.x.x`` where x.x.x is the version number. 
+- If you need to update biomechzoo to the latest version in your env, run ``pip install biomechzoo --upgrade``
+
+## Dependencies notes
+- We use Python 3.11 for compatibility with https://github.com/stanfordnmbl/opencap-processing
+- We use Numpy 2.2.6 for compatibility with https://pypi.org/project/numba/
+
+See also http://www.github.com/mcgillmotionlab/biomechzoo or http://www.biomechzoo.com for more information
+
+## Developer notes
+
+### Installing a dev environment
+conda create -n biomechzoo-dev python=3.11
+conda activate biomechzoo-dev
+cd biomechzoo root folder
+pip install -e ".[dev]"
+
+### import issues
+if using PyCharm: 
+- Right-click on src/.
+- Select Mark Directory as → Sources Root.

biomechzoo-0.5.3/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "biomechzoo"
+version = "0.5.3"
+description = "Python implementation of the biomechZoo toolbox"
+readme = "README.md"
+requires-python = ">=3.11,<3.12"   # max version for opencap-process tools is 3.11
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "ezc3d>=1.5.19",        # for reading c3d files
+    "matplotlib>=3.10.6",
+    "numpy==2.2.6",         # max version for opencap-process tools
+    "pandas>=2.3.2",
+    "scipy>=1.16.2",
+    "pyarrow>=19.0.0",      # for parquet support
+]
+
+[project.urls]
+Homepage = "https://github.com/mcgillmotionlab/biomechzoo"
+
+[project.scripts]
+biomechzoo = "main:main"
+
+[build-system]
+requires = ["setuptools>=78.1.0", "wheel>=0.45.1"]
+build-backend = "setuptools.build_meta"
+
+[[tool.uv.index]]
+name = "testbiomechzoo"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

biomechzoo-0.5.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

biomechzoo-0.5.3/src/__init__.py

@@ -0,0 +1,33 @@
+"""
+BiomechZoo: A Python toolbox for processing and analyzing human movement data.
+
+This package provides functions for converting, processing, analyzing,
+and visualizing biomechanical data (e.g., motion capture, EMG, kinetics).
+
+Example:
+    from biomechzoo import BiomechZoo
+    from biomechzoo.conversion import c3d2zoo
+
+    zoo = BiomechZoo()
+    zoo.conversion.c3d2zoo('path/to/data')
+"""
+
+# Import main class or entry point
+from .biomechzo import BiomechZoo
+
+# Import commonly used submodules
+from . import conversion
+from . import processing
+from . import plotting
+from . import utils
+
+# Define what gets exposed with "from biomechzoo import *"
+__all__ = [
+    "BiomechZoo",
+    "conversion",
+    "processing",
+    "plotting",
+    "utils",
+]
+
+__version__ = "0.4.4"

biomechzoo-0.5.3/src/biomechzoo/__main__.py

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

biomechzoo-0.5.3/src/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-0.5.3/src/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-0.5.3/src/biomechzoo/biomech_ops/filter_data.py

@@ -0,0 +1,58 @@
+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:
+        - 'ftype': 'butter' (default)
+        - 'order': filter order (default: 4)
+        - 'cutoff': cutoff frequency or tuple (Hz)
+        - 'btype': 'low', 'high', 'bandpass', 'bandstop' (default: 'lowpass')
+
+    Returns
+    -------
+    dict
+        The updated data dictionary with filtered channels.
+    """
+
+    if filt is None:
+        filt = {'ftype': 'butter',
+                'order': 4,
+                'cutoff': 10,
+                'btype': 'lowpass',
+                'filtfilt': True}
+
+    if isinstance(ch, str):
+        ch = [ch]
+
+    # loop through all channels and filter
+    for c in ch:
+        if c not in data:
+            raise KeyError('Channel {} not found in data'.format(c))
+
+        if 'fs' not in filt:
+
+            video_channels = data['zoosystem']['Video']['Channels']
+            analog_channels = data['zoosystem']['Analog']['Channels']
+
+            if c in analog_channels:
+                filt['fs'] = data['zoosystem']['Analog']['Freq']
+            elif c in video_channels:
+                filt['fs'] =  data['zoosystem']['Video']['Freq']
+            else:
+                raise ValueError('Channel not analog or video')
+
+        signal_raw = data[c]['line']
+        signal_filtered = filter_line(signal_raw=signal_raw, filt=filt)
+        data[c]['line'] = signal_filtered
+
+    return data

biomechzoo-0.5.3/src/biomechzoo/biomech_ops/filter_line.py

@@ -0,0 +1,85 @@
+import numpy as np
+import scipy.signal as sgl
+
+
+def filter_line(signal_raw, filt=None, fs=None):
+    """Filter an array using a Butterworth filter."""
+    #todo: verify that filter is working correctly
+    #todo add more filters
+    #todo: consider using kineticstoolkit
+
+    if filt is None:
+        filt = {'ftype': 'butter',
+                'order': 4,
+                'cutoff': 10,
+                'btype': 'lowpass',
+                'filtfilt': True}
+        if fs is None:
+            raise ValueError('fs is required if no filt is specified')
+
+    else:
+        if 'fs' not in filt:
+            raise ValueError('fs is a required key of filt')
+
+    # Normalize filter type strings
+    if filt['ftype'] == 'butterworth':
+        filt['ftype'] = 'butter'
+    if filt['btype'] is 'low':
+        filt['btype'] = 'lowpass'
+    if filt['btype'] is 'high':
+        filt['btype'] = 'highpass'
+
+    # Extract parameters
+    ftype = filt['ftype']
+    order = filt['order']
+    cutoff = filt['cutoff']
+    btype = filt['btype']
+    filtfilt = filt['filtfilt']
+    fs = filt['fs']
+
+    # prepare normalized cutoff(s)
+    nyq = 0.5 * fs
+    norm_cutoff = np.atleast_1d(np.array(cutoff) / nyq)
+
+    if ftype is 'butter':
+        signal_filtered = kt_butter(ts=signal_raw, fc=norm_cutoff, fs=fs, order=order, btype=btype, filtfilt=filtfilt)
+    else:
+        raise NotImplementedError(f"Filter type '{ftype}' not implemented.")
+
+    return signal_filtered
+
+
+def kt_butter(ts, fc, fs, order=2, btype='lowpass', filtfilt=True):
+    """
+    Apply a Butterworth filter to data.
+
+    Parameters
+    ----------
+    ts, ndarray, 1d.
+    fc, Cut-off frequency in Hz. This is a float for single-frequency filters
+        (lowpass, highpass), or a tuple of two floats (e.g., (10., 13.)
+        for two-frequency filters (bandpass, bandstop)).
+    order, Optional. Order of the filter. Default is 2.
+    btype, Optional. Can be either "lowpass", "highpass", "bandpass" or
+        "bandstop". Default is "lowpass".
+    filtfilt, Optional. If True, the filter is applied two times in reverse direction
+        to eliminate time lag. If False, the filter is applied only in forward
+        direction. Default is True.
+
+    Returns
+    -------
+    ts_f,  A copy of the input data which each data being filtered.
+    
+    Notes: 
+    - This code was adapted from kineticstoolkit Thanks @felxi
+    """
+
+    sos = sgl.butter(order, fc, btype, analog=False, output="sos", fs=fs)
+
+    # Filter
+    if filtfilt:
+        ts_f = sgl.sosfiltfilt(sos, ts, axis=0)
+    else:
+        ts_f = sgl.sosfilt(sos,ts, axis=0)
+
+    return ts_f

biomechzoo-0.5.3/src/biomechzoo/biomech_ops/movement_onset.py

@@ -0,0 +1,51 @@
+def movement_onset(yd, constant):
+    """
+    Extracts movement onset based on the average and standard deviation of a sliding window
+    Standard thresholds for running are mean_thresh=1.2, std_thresh=0.2. For walking mean_thresh=0.6, std_thresh=0.2.
+
+    yd: 1d array of the vector
+    constants: [sample_frequency, mean_thresh, std_thresh]
+    """
+    acc_mag = yd.copy()
+
+    # ----extract the constants----
+    fs = constant[0]
+    mean_thresh = constant[1]
+    std_thresh = constant[2]
+
+    # ----sliding window features----
+    features = []
+    timestamps = []
+    window_size = 2 * fs  # windows van 2 seconds
+    step_size = 1 * fs  # with an overlap of 1 seconds
+
+    for start in range(0, len(acc_mag) - window_size, step_size):
+        segment = acc_mag[start:start + window_size]
+        mean_val = segment.mean()
+        std_val = segment.std()
+        # entropy = -np.sum((segment / np.sum(segment)) * np.log2(segment / np.sum(segment) + 1e-12))
+        timestamps.append(start)
+        features.append((mean_val, std_val))
+
+    features = np.array(features)
+    timestamps = np.array(timestamps)
+
+    # ----Check already moving else find start----
+    initial_window = features[:5]  # First few seconds
+    if np.all(initial_window[:, 0] > mean_thresh) and np.all(initial_window[:, 1] > std_thresh):
+        print("already moving")
+        if etype == 'movement_offset':
+            index = 0
+    else:
+        # features, timestamps = self.sliding_window_features(acc_mag)
+        movement_flags = (features[:, 0] > mean_thresh) & (features[:, 1] > std_thresh)
+        index = None
+        for i in range(len(movement_flags) - int(min_duration * self.fs / 50)):
+            if np.all(movement_flags[i:i + int(min_duration * self.fs / 50)]):
+                index = i
+                break
+
+    if etype == 'movement_offset':
+        index = len(yd) - end_time
+
+    return timestamps[index] if index is not None else timestamps[0]

biomechzoo-0.5.3/src/biomechzoo/biomech_ops/normalize_data.py

@@ -0,0 +1,36 @@
+import warnings
+import copy
+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 = copy.deepcopy(data)
+    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-0.5.3/src/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-0.5.3/src/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-0.5.3/src/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()
+