CIMAP 1.1.1

A Python package for muscle activation pattern analysis

CIMAP: Clustering for Identification of Muscle Activation Patterns

The accurate temporal analysis of muscle activation is of great interest in several research areas, spanning from neurorobotic systems to the assessment of altered locomotion patterns in orthopedic and neurological patients and the monitoring of their motor rehabilitation. However, due to the high intra-cycle variability of the muscle activation patterns, specific algorithms are needed to help scientists to easily characterize and assess muscle activation patterns during cyclical movements. CIMAP is a python algorithm based on agglomerative hierarchical clustering that aims at characterizing muscle activation patterns during cyclical movements by grouping strides with similar muscle activity. More specifically, CIMAP allows for widening our understanding of muscle activation patterns by applying hierarchical clustering techniques to muscle activation intervals (i.e., onset and offset time-instants of muscle activations). From muscle activation intervals to the graphical representation of the clustering results, the proposed algorithm offers a complete analysis framework for assessing muscle activation patterns that can be applied to cyclical movements different from walking. The algorithm can be flexibly modified at need to comply with the necessities of the user. CIMAP is addressed to scientists of any programming skill level working in different research areas such as biomedical engineering, robotics, sports, clinics, biomechanics, and neuroscience.

Installation

The latest stable release of CIMAP is freely available on GitHub. Documentation and representative examples are freely available in each version’s readme file. The latest stable release of CIMAP can be easily installed through the bash shell or command prompt with the following commands:

• Download Python and install (please have Python >= 3.11.0)
• Open the bash shell or the command prompt and install the algorithm with pip install CIMAP

Using the setup.py file

You can download CIMAP from its GitHub repository as a zip file. A setup.py file (setuptools) is included in the root folder of CIMAP. Enter the package's root folder and run: python setup.py install.

Done! CIMAP is now correctly installed on your computer and ready to be used.

What the CIMAP algorithm does:

1. Data preparation (i.e., to read input data and convert them into the format needed for the following steps)
2. Data pre-processing (i.e., to split input data based on the number of muscle activations within each cycle)
3. Agglomerative hierarchical clustering:
   • Cutting point identification based on the intra-cluster variability
   • Distance metric selection based on the lowest inter-cluster variability
4. Clusters' representation (available also at points 3 and 4)
5. Data saving (clustering results are saved in an easy-to-read and open-source format)

Documentation

Detailed information on data requirements and algorithm functions can be found on the Documentation page. Moreover, a complete CIMAPapplication example is provided.

Functions description

A detailed description of all the functions developed for performing CIMAP is available in the Documentation in the Algorithm Functions section.

Application Example

A comprehensive application example is provided in the Documentation page in the Applying CIMAP to gait analysis section. The dataset on which CIMAP is applied is the same that is provided in the example_data folder. Following the same steps showed in the example section of the Documentation it is possible to apply CIMAP to other datasets.

References

If you use CIMAP algorithm in your work, please cite the following two articles:

• S. Rosati, V. Agostini, M. Knaflitz, and G. Balestra, “Muscle activation patterns during gait: A hierarchical clustering analysis,” Biomed. Signal Process. Control, vol. 31, pp. 463–469, 2017, doi: 10.1016/j.bspc.2016.09.017.

• S. Rosati, C. Castagneri, V. Agostini, M. Knaflitz, and G. Balestra, “Muscle contractions in cyclic movements: Optimization of CIMAP algorithm,” 2017, doi: 10.1109/EMBC.2017.8036762.

How to contribute to CIMAP

Thank you for your interest in our algorithm and for taking the time to read this document. Please refer to the Contributing section for a complete guide on how to contribute to this algorithm.

Disclaimer

This algorithm is provided as-is, and there are no guarantees that it fits your purposes or that it is bug-free.