biomechzoo 0.1.1__tar.gz

biomechzoo-0.1.1/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.1.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: biomechzoo
+Version: 0.1.1
+Summary: Python implementation of the biomechZoo Matlab toolbox
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mcgillmotionlab/biomechzoo
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ezc3d>=1.5.19
+Requires-Dist: matplotlib>=3.10.6
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: scipy>=1.16.2
+Dynamic: license-file
+
+# Repository for the Python version of biomechZoo
+This is a development version of the biomechzoo toolbox for python. To use biomechzoo
+as a packagage alongside your code, follow the "How to install" instructions below
+
+## How to install 
+- make sure the local version of your code sits at the same level as biomechzoo. 
+e.g.
+code_root/
+code_root/biomechzoo/         ← the repo with the actual package
+code_root/student_code/       ← where your scripts or notebooks live
+    
+- open terminal or command window
+- create an environment for your research project: ``conda create -n name python=3.13 -c conda-forge``, where name is of your choice
+- activate your new environment: ``conda activate name``
+- navigate to parent directory where biomechzoo was cloned. e.g. ``code_root``
+- install biomechzoo: ``pip install -e biomechzoo``
+- install additional requirements: ``pip install -r biomechzoo/pip_requirements.txt``
+
+## Updates (not tested)
+- If updates are made to biomechzoo, simply pull the latest version 
+  from github, you won't need to reinstall (unless there are new dependencies)
+
+## Usage notes
+- To use biomechzoo in your project, you will need to import biomechzoo as: 
+``from biomechzoo.biomechzoo import BiomechZoo``
+- Then, you can create an object that is an instance of the BimechZoo class as:
+``bmech = BiomechZoo(fld)`` where ``fld`` is the path to your data
+
+
+# opencap users
+- opencap users should pre-process their data using ``https://github.com/stanfordnmbl/opencap-processing``
+- processed data could be saved to csv using pandas and then imported to biomechzoo using csv2zoo (not yet functional)

biomechzoo-0.1.1/README.md

@@ -0,0 +1,32 @@
+# Repository for the Python version of biomechZoo
+This is a development version of the biomechzoo toolbox for python. To use biomechzoo
+as a packagage alongside your code, follow the "How to install" instructions below
+
+## How to install 
+- make sure the local version of your code sits at the same level as biomechzoo. 
+e.g.
+code_root/
+code_root/biomechzoo/         ← the repo with the actual package
+code_root/student_code/       ← where your scripts or notebooks live
+    
+- open terminal or command window
+- create an environment for your research project: ``conda create -n name python=3.13 -c conda-forge``, where name is of your choice
+- activate your new environment: ``conda activate name``
+- navigate to parent directory where biomechzoo was cloned. e.g. ``code_root``
+- install biomechzoo: ``pip install -e biomechzoo``
+- install additional requirements: ``pip install -r biomechzoo/pip_requirements.txt``
+
+## Updates (not tested)
+- If updates are made to biomechzoo, simply pull the latest version 
+  from github, you won't need to reinstall (unless there are new dependencies)
+
+## Usage notes
+- To use biomechzoo in your project, you will need to import biomechzoo as: 
+``from biomechzoo.biomechzoo import BiomechZoo``
+- Then, you can create an object that is an instance of the BimechZoo class as:
+``bmech = BiomechZoo(fld)`` where ``fld`` is the path to your data
+
+
+# opencap users
+- opencap users should pre-process their data using ``https://github.com/stanfordnmbl/opencap-processing``
+- processed data could be saved to csv using pandas and then imported to biomechzoo using csv2zoo (not yet functional)

biomechzoo-0.1.1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "biomechzoo"
+version = "0.1.1"
+description = "Python implementation of the biomechZoo Matlab toolbox"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "ezc3d>=1.5.19",
+    "matplotlib>=3.10.6",
+    "numpy>=2.3.3",
+    "pandas>=2.3.2",
+    "scipy>=1.16.2",
+]
+
+[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.1.1/setup.cfg

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

biomechzoo-0.1.1/src/biomechzoo/__init__.py

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

biomechzoo-0.1.1/src/biomechzoo/__main__.py

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

biomechzoo-0.1.1/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.1.1/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.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/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.1.1/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.1.1/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()
+