biomechzoo 0.5.9__py3-none-any.whl

biomechzoo/statistics/eventval.py

@@ -0,0 +1,118 @@
+import os
+import pandas as pd
+from biomechzoo.utils.engine import engine
+from biomechzoo.utils.zload import zload
+from biomechzoo.utils.findfield import findfield  # assuming this exists
+
+def eventval(fld, dim1=None, dim2=None, ch=None, localevts=None, globalevts=None, anthroevts=None):
+    """
+    Extract event values from .zoo files and compile into a pandas DataFrame.
+
+    Parameters
+    ----------
+    fld : str
+        Path to the root data folder containing .zoo files.
+    dim1 : list of str, optional
+        List of conditions (subfolder names under fld).
+    dim2 : list of str, optional
+        List of participant identifiers.
+    ch : list of str
+        List of channels to extract events from.
+    localevts : list of str, optional
+        List of local events.
+    globalevts : list of str, optional
+        List of global events.
+    anthroevts : list of str, optional
+        List of events stored in the metadata.Usually anthropometric data
+
+    Returns
+    -------
+    pd.DataFrame
+        Columns: ['condition', 'subject', 'file', 'event_name', 'event_value']
+    """
+
+    zoo_files = engine(fld, extension='.zoo')
+    results = []
+    files_excluded = []
+    for fl in zoo_files:
+        data = zload(fl)
+        fname = os.path.basename(fl)
+        condition = next((c for c in (dim1 or []) if c in fl), '')
+        subject = next((s for s in (dim2 or []) if s in fl), '')
+
+        # Skip file if condition or subject is empty
+
+        if not condition or not subject:
+            files_excluded.append(fl)
+            continue
+        else:
+            print('processing {}'.format(fl))
+
+        # --- Local events ---
+        if localevts and ch:
+            print('extracting local events...')
+            for channel in ch:
+                if channel not in data:
+                    print('channel {} not found'.format(channel))
+                    continue
+                for evt in localevts:
+                    try:
+                        exd = int(data[channel]['event'][evt][0])  # xdata
+                        eyd = data[channel]['event'][evt][1]  # ydata
+                        results.append({
+                            'condition': condition,
+                            'subject': subject,
+                            'file': fname,
+                            'event_name': f"{channel}_{evt}",
+                            'event_index': exd,
+                            'event_value': eyd
+                        })
+                    except (KeyError, IndexError, TypeError) as e:
+                        print(f"Local event '{evt}' not found in channel '{channel}' for file '{fname}'")
+
+        # --- Global events ---
+        if globalevts and ch:
+            print('extracting global events...')
+            for evt in globalevts:
+                # use findfield to locate where the global event is stored
+                evt_val, evt_ch = findfield(data, evt)
+                if not evt_ch:
+                    print(f"Global event '{evt}' not found in any channel for file '{fname}'")
+                    continue
+
+                exd = int(evt_val[0])
+                for channel in ch:
+                    if channel not in data:
+                        print(f"Skipping {evt}: channel {channel} not in data")
+                        continue
+                    try:
+                        eyd = data[channel]['line'][exd]
+                        results.append({
+                            'condition': condition,
+                            'subject': subject,
+                            'file': fname,
+                            'event_name': f"{channel}_{evt}",
+                            'event_index': exd,
+                            'event_value': eyd
+                        })
+                    except (IndexError, KeyError, TypeError) as e:
+                        print(f"Global event '{evt}' index out of range in channel '{channel}' for file '{fname}': {e}")
+
+        if anthroevts and ch:
+            raise NotImplementedError
+            print('extracting anthropometric events...')
+            for evt in globalevts:
+                # use findfield to locate where the global event is stored
+                evt_val, _ = findfield(data, evt)
+
+                if evt_val:
+                    results.append({
+                        'condition': condition,
+                        'subject': subject,
+                        'file': fname,
+                        'event_name': evt,
+                        'event_index': evt_val[0],
+                        'event_value': evt_val[1]
+                    })
+
+    return pd.DataFrame(results)

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,88 @@
+import os
+import numpy as np
+
+
+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 or 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, or list; 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.
+    """
+    # check format of subfolder (string or list)
+    if subfolders is not None:
+        if type(subfolders) is str:
+            subfolders = [subfolders]
+
+    # check format of name_contants (str or list)
+    if name_contains is not None:
+        if type(name_contains) is str:
+            name_contains = [name_contains]
+
+    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
+            full_path = os.path.join(dirpath, file)
+            if name_contains is not None:
+                match = False
+                for name_contain in name_contains:
+                    if name_contain and name_contain.lower() in full_path.lower():  # <-- check full path
+                        match = True
+                        break
+                if not match:
+                    continue
+            matched_files.append(full_path)
+
+    # sort list
+    matched_files = np.sort(matched_files)
+
+    if verbose:
+        print("Found {} {} files in subfolder(s) 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(os.path.dirname(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
+

biomechzoo/utils/peak_sign.py

@@ -0,0 +1,24 @@
+import numpy as np
+
+def peak_sign(r):
+    """
+    Determine whether the largest absolute peak in the signal is positive or negative.
+
+    Parameters
+    ----------
+    r : array-like
+        Signal vector.
+
+    Returns
+    -------
+    sign : int
+        1 if the maximum peak is positive, -1 if negative.
+    """
+    r = np.asarray(r)
+    max_val = np.max(r)
+    min_val = np.min(r)
+
+    if abs(max_val) > abs(min_val):
+        return 1
+    else:
+        return -1

biomechzoo/utils/set_zoosystem.py

@@ -0,0 +1,66 @@
+import numpy as np
+from pathlib import Path
+from biomechzoo.utils.version import get_biomechzoo_version
+
+
+def set_zoosystem(fl=None):
+    """
+    Create the 'zoosystem' branch for data being imported to BiomechZoo.
+
+    Args:
+        fl: str
+            Path to the source file (e.g., C3D or CSV).
+
+    Returns:
+        zoosystem: dict
+            Dictionary containing default BiomechZoo system parameters.
+    """
+
+    # Default top-level fields
+    zch = ['Analog', 'Anthro', 'AVR', 'CompInfo', 'SourceFile',
+           'Units', 'Version', 'Video']
+
+    # Initialize top-level dict
+    zoosystem = {key: {} for key in zch}
+
+    # Section-specific defaults
+    section = ['Video', 'Analog']
+    for sec in section:
+        zoosystem[sec]['Channels'] = []
+        zoosystem[sec]['Freq'] = []
+        zoosystem[sec]['Indx'] = []
+        zoosystem[sec]['ORIGINAL_START_FRAME'] = []
+        zoosystem[sec]['ORIGINAL_END_FRAME'] = []
+        zoosystem[sec]['CURRENT_START_FRAME'] = []
+        zoosystem[sec]['CURRENT_END_FRAME'] = []
+
+    # Processing and AVR defaults
+    zoosystem['Processing'] = ''
+    zoosystem['AVR'] = 0
+
+    # Force plates defaults
+    zoosystem['Analog']['FPlates'] = {
+        'CORNERS': [],
+        'NUMUSED': 0,
+        'LOCALORIGIN': [],
+        'LABELS': []
+    }
+
+    # Version and source file
+    zoosystem['Version'] = get_biomechzoo_version()
+    if fl is None:
+        zoosystem['SourceFile'] = 'None'  # ensure string
+    else:
+        zoosystem['SourceFile'] = str(Path(fl))  # ensure string
+
+    # Units defaults
+    zoosystem['Units'] = {
+        'Markers': 'mm',
+        'Angles': 'deg',
+        'Forces': 'N',
+        'Moments': 'Nmm',
+        'Power': 'W/kg',
+        'Scalars': 'mm'
+    }
+
+    return zoosystem

biomechzoo/utils/version.py

@@ -0,0 +1,5 @@
+from importlib.metadata import version as get_version
+
+
+def get_biomechzoo_version() -> str:
+    return get_version("biomechzoo")

biomechzoo/utils/zload.py

@@ -0,0 +1,57 @@
+from scipy.io import loadmat
+import os
+import numpy as np
+
+
+def zload(filepath):
+    if not filepath.endswith('.zoo'):
+        raise ValueError(f"{filepath} is not a .zoo file")
+
+    if not os.path.exists(filepath):
+        raise FileNotFoundError(f"File not found: {filepath}")
+
+    mat_data = loadmat(filepath, struct_as_record=False, squeeze_me=True)
+
+    # Remove default MATLAB metadata fields
+    mat_data = {k: v for k, v in mat_data.items() if not k.startswith('__')}
+
+    # Convert MATLAB structs to Python dicts (recursively)
+    def mat_struct_to_dict(obj):
+        if isinstance(obj, dict):
+            return {k: mat_struct_to_dict(v) for k, v in obj.items()}
+        elif hasattr(obj, '_fieldnames'):
+            return {field: mat_struct_to_dict(getattr(obj, field)) for field in obj._fieldnames}
+        elif isinstance(obj, list):
+            return [mat_struct_to_dict(item) for item in obj]
+        else:
+            return obj
+    data = {k: mat_struct_to_dict(v) for k, v in mat_data.items()}
+
+    if 'data' in data:
+        data = data['data']
+
+    # Convert Video and Analog channel arrays to Python lists
+    for sys in ['Video', 'Analog']:
+        if 'zoosystem' in data and sys in data['zoosystem']:
+            channels = data['zoosystem'][sys].get('Channels', [])
+            # Convert to list and strip spaces
+            if isinstance(channels, np.ndarray):
+                channels = channels.tolist()
+            channels = [str(ch).strip() for ch in channels]
+            data['zoosystem'][sys]['Channels'] = channels
+
+    return data
+
+
+if __name__ == '__main__':
+    """ testing: load a single zoo file from the other subfolder in data"""
+    # -------TESTING--------
+    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)
+
+    channels = [k for k in data.keys()]
+    print('{} channels found'.format(len(channels)))
+    for ch in channels:
+        print({ch})

biomechzoo/utils/zplot.py

@@ -0,0 +1,61 @@
+import matplotlib.pyplot as plt
+
+
+def zplot(data, ch, xlabel='frames', ylabel='angles (deg)'):
+    """
+    Plot a single channel of a zoo file, along with any existing events.
+
+    Parameters
+    ----------
+    data : dict
+        Loaded zoo file.
+    ch : str
+        Name of the channel to plot, e.g., 'RkneeAngles'.
+    xlabel : str
+        Label for x-axis. Default is 'frames'.
+    ylabel : str
+        Label for y-axis. Default is 'angles (deg)'.
+
+    Returns
+    -------
+    None
+    """
+
+    if ch not in data:
+        raise KeyError(f"Channel '{ch}' not found in data.")
+
+    y = data[ch]['line']
+    x = range(len(y))
+
+    plt.figure(figsize=(10, 4))
+    plt.plot(x, y, label='Signal', linewidth=2)
+    plt.title(ch)
+    plt.xlabel(xlabel)
+    plt.ylabel(ylabel)
+    plt.grid(True)
+
+    # Plot events if available
+    events = data[ch].get('event', {})
+    for name, coords in events.items():
+        evtx, evty = coords[0], coords[1]
+        plt.plot(evtx, evty, 'ro')
+        plt.text(evtx, evty, name, fontsize=8, color='red', ha='left', va='bottom')
+
+    plt.tight_layout()
+    plt.show()
+
+
+if __name__ == '__main__':
+    # -------TESTING--------
+    import os
+    from 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)
+    ch = 'SACR'
+    zplot(data, ch)

biomechzoo/utils/zsave.py

@@ -0,0 +1,54 @@
+from scipy.io import savemat
+import inspect
+import os
+
+from biomechzoo.utils.batchdisp import batchdisp
+
+
+def zsave(fl, data, inplace=True, out_folder=None, root_folder=None, verbose=False):
+    """
+    Save zoo data to .zoo file (MAT format)
+
+    Arguments:
+        fl (str): Full path to original .zoo file
+        data (dict): Zoo data to save
+        inplace (bool): Whether to overwrite original file
+        out_folder (str or None): If not inplace, output folder name (relative to root_folder or file location)
+        root_folder (str or None): Optional base directory for saving when inplace=False
+    """
+    # Get caller function name for logging
+    caller_name = inspect.stack()[1].function
+
+    # Initialize zoosystem and processing history
+    zoosystem = data.get('zoosystem', {})
+    processing = zoosystem.get('Processing', [])
+    if not isinstance(processing, list):
+        processing = [processing]
+    processing.append(caller_name)
+    zoosystem['Processing'] = processing
+    data['zoosystem'] = zoosystem
+
+    # Determine save path
+    if inplace:
+        fl_new = fl
+        out_dir = os.path.dirname(fl)
+    else:
+        if out_folder is None:
+            out_folder = 'processed'
+
+        if root_folder is None:
+            root_folder = os.path.dirname(fl)
+
+        root_path = os.path.dirname(root_folder)
+        in_folder = os.path.basename(root_folder)
+        out_dir = os.path.join(root_path, out_folder)
+        os.makedirs(out_dir, exist_ok=True)
+        fl_new = fl.replace(in_folder, out_folder)
+        save_folder = os.path.dirname(fl_new)
+        os.makedirs(save_folder, exist_ok=True)
+
+    # Save the .zoo file
+    savemat(fl_new, data)
+    batchdisp('all files saved to ' + out_dir, level=1, verbose=verbose)
+
+

biomechzoo-0.5.9.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: biomechzoo
+Version: 0.5.9
+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.