pyomeca: An Open-Source Framework for Biomechanical Analysis

Biomechanics is defined as the study of the structure and function of biological systems by means of the methods of mechanics (Hatze, 1974). While musculoskeletal biomechanics branches into several subfields, the data used are remarkably similar. The processing, analysis and visualization of these data could therefore be unified in a software package. Most biomechanical data characterizing human and animal movement appear as temporal waveforms representing specific measures such as muscle activity or joint angles. These data are typically multidimensional arrays structured around labels with arbitrary metadata (Figure 1). Existing software solutions share some limitations. Some of them are proprietary (Damsgaard, Rasmussen, Christensen, Surma, & Zee, 2006) or based on closed-source programming language (Dixon, Loh, Michaud-Paquette, & Pearsall, 2017; Muller, Pontonnier, Puchaud, & Dumont, 2019). Others do not leverage labels and metadata (Hachaj & Ogiela, 2019; Virtanen et al., 2020; Walt, Colbert, & Varoquaux, 2011). pyomeca is a Python package designed to address these limitations. It provides basic operations useful in the daily workflow of a biomechanical researcher such as reading, writing, filtering and plotting, but also more advanced biomechanical routines geared towards rigid body mechanics and signal processing. By offering a single, efficient and flexible implementation, pyomeca standardizes these procedures, freeing up valuable research time, thereby allowing researchers to focus on the scientific research questions at hand.


Statement of Need
Biomechanics is defined as the study of the structure and function of biological systems by means of the methods of mechanics (Hatze, 1974). While musculoskeletal biomechanics branches into several subfields, the data used are remarkably similar. The processing, analysis and visualization of these data could therefore be unified in a software package. Most biomechanical data characterizing human and animal movement appear as temporal waveforms representing specific measures such as muscle activity or joint angles. These data are typically multidimensional arrays structured around labels with arbitrary metadata (Figure 1). Existing software solutions share some limitations. Some of them are proprietary (Damsgaard, Rasmussen, Christensen, Surma, & Zee, 2006) or based on closed-source programming language (Dixon, Loh, Michaud-Paquette, & Pearsall, 2017;Muller, Pontonnier, Puchaud, & Dumont, 2019). Others do not leverage labels and metadata (Hachaj & Ogiela, 2019;Virtanen et al., 2020;Walt, Colbert, & Varoquaux, 2011). pyomeca is a Python package designed to address these limitations. It provides basic operations useful in the daily workflow of a biomechanical researcher such as reading, writing, filtering and plotting, but also more advanced biomechanical routines geared towards rigid body mechanics and signal processing. By offering a single, efficient and flexible implementation, pyomeca standardizes these procedures, freeing up valuable research time, thereby allowing researchers to focus on the scientific research questions at hand.

Summary
As a Python library, pyomeca enables extraction, processing and visualization of biomechanical data for use in research and education. It is motivated by the need for simpler tools and more reproducible workflows allowing practitioners to focus on their specific interests and leaving pyomeca to handle the computational details for them. pyomeca builds on the core scientific Python packages, in particular numpy (Walt et al., 2011), scipy (Virtanen et al., 2020), matplotlib (Hunter, 2007) and xarray (Hoyer & Hamman, 2017). By providing labeled querying and computation, efficient algorithms and persistent metadata, the integration of xarray facilitates usability, which seems to be relevant in a context where scientists do not always receive extensive training in programming. xarray is designed as a general-purpose library and tries to avoid including domain specific functionalities -but inevitably, the need for more domain specific logic arises. pyomeca provides a biomechanics layer that supports specialized file formats (c3d, mat, trc, sto, mot, csv and xlsx) and implements signal processing and matrix manipulation routines commonly used in musculoskeletal biomechanics. We believe pyomeca is a solid foundation for more advanced research implementations and could, in the future, provide functions for processing and extracting meaningful clinical outputs from the raw data. pyomeca was written with the Unix philosophy in mind, that is to design each program to do one thing well and expect the output of every program to become the input to another, as yet unknown, program. As such, it is written in a modular, object-oriented way -which makes it extensible and easy to develop -and it interacts well with other projects under the pyomeca umbrella, namely ezc3d, pyosim or biorbd-viz. pyomeca follows software best practices by being fully tested, linted and type annotated -ensuring that the package is easily distributable and modifiable. In addition to the static documentation and API reference, pyomeca includes a set of Jupyter Notebooks with examples. These notebooks can be read and executed by anyone with only a web browser through binder.

Features
pyomeca inherits from the xarray feature set, which includes label-based indexing, arithmetic, aggregation and alignment, resampling and rolling window operations, plotting, missing data handling and out-of-core computation. In addition, pyomeca has four data structures built upon xarray. Each structure is associated with a specific biomechanical data type: • Angles: joint angles, • Rototrans: rototranslation matrix, • Analogs: generic signals such as electromyographic (EMG) and force signals or any other analog signals, • Markers: skin markers positions.
While there are technically dozens of functions implemented in pyomeca, one can generally group them into two distinct categories: object creation and data processing.

Object Creation
The starting point for working with pyomeca is to create an object with one of the specific methods associated with the different classes available. pyomeca offers several ways to create these objects: by directly specifying the data, by sampling random data from distributions, by converting other data structures or by reading files (Figure 2).

Data Processing
pyomeca's main functionality is to offer dedicated biomechanical routines. These features can be broadly grouped into different categories: filtering, signal processing, normalization, matrix manipulation and file output functions (Figure 3). : pyomeca data processing capabilities are available through the meca DataArrayAccessor (e.g. array.meca) that allow implementing domain specific methods on xarray data objects. These methods can be categorized into filters (orange), signal processing (red), normalization (blue), matrix manipulation (green) and file output (purple) routines.

Research Projects Using pyomeca
You can find an up-to-date list of research projects using pyomeca on the static documentation.