motor-unit-toolbox 1.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- motor_unit_toolbox-1.2.0/CITATION.cff +23 -0
- motor_unit_toolbox-1.2.0/LICENSE +21 -0
- motor_unit_toolbox-1.2.0/MANIFEST.in +4 -0
- motor_unit_toolbox-1.2.0/PKG-INFO +150 -0
- motor_unit_toolbox-1.2.0/README.md +104 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox/__init__.py +1 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox/muap_comp.py +1274 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox/plots.py +415 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox/props.py +1035 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox/spike_comp.py +837 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox/utils.py +36 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox.egg-info/PKG-INFO +150 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox.egg-info/SOURCES.txt +22 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox.egg-info/dependency_links.txt +1 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox.egg-info/requires.txt +20 -0
- motor_unit_toolbox-1.2.0/motor_unit_toolbox.egg-info/top_level.txt +1 -0
- motor_unit_toolbox-1.2.0/pyproject.toml +148 -0
- motor_unit_toolbox-1.2.0/setup.cfg +4 -0
- motor_unit_toolbox-1.2.0/tests/conftest.py +113 -0
- motor_unit_toolbox-1.2.0/tests/test_muap_comp.py +269 -0
- motor_unit_toolbox-1.2.0/tests/test_plots.py +84 -0
- motor_unit_toolbox-1.2.0/tests/test_props.py +246 -0
- motor_unit_toolbox-1.2.0/tests/test_spike_comp.py +167 -0
- motor_unit_toolbox-1.2.0/tests/test_utils.py +29 -0
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use this software, please cite it as below."
|
|
3
|
+
authors:
|
|
4
|
+
- family-names: "Mendez Guerra"
|
|
5
|
+
given-names: "Irene"
|
|
6
|
+
orcid: "https://orcid.org/0000-0001-7361-4618"
|
|
7
|
+
title: "Motor Unit Toolbox"
|
|
8
|
+
abstract: >-
|
|
9
|
+
Python functions to analyse motor unit behaviour: firing and motor unit
|
|
10
|
+
action potential (MUAP) properties, spike train comparison, and MUAP tracking.
|
|
11
|
+
version: 1.2.0
|
|
12
|
+
# doi: TODO add the Zenodo DOI after the first archived release
|
|
13
|
+
# date-released: TODO set to the release date (YYYY-MM-DD) before tagging
|
|
14
|
+
license: MIT
|
|
15
|
+
url: "https://imendezguerra.github.io/motor_unit_toolbox/"
|
|
16
|
+
repository-code: "https://github.com/imendezguerra/motor_unit_toolbox"
|
|
17
|
+
keywords:
|
|
18
|
+
- motor unit
|
|
19
|
+
- EMG
|
|
20
|
+
- HD-EMG
|
|
21
|
+
- MUAP
|
|
22
|
+
- spike train
|
|
23
|
+
- decomposition
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Irene Mendez Guerra
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: motor_unit_toolbox
|
|
3
|
+
Version: 1.2.0
|
|
4
|
+
Summary: Analyse motor unit firing behaviour and action potentials from decomposed EMG
|
|
5
|
+
Author-email: Irene Mendez Guerra <irene.mendez17@imperial.ac.uk>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://imendezguerra.github.io/motor_unit_toolbox/
|
|
8
|
+
Project-URL: Documentation, https://imendezguerra.github.io/motor_unit_toolbox/
|
|
9
|
+
Project-URL: Source, https://github.com/imendezguerra/motor_unit_toolbox
|
|
10
|
+
Project-URL: Issues, https://github.com/imendezguerra/motor_unit_toolbox/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/imendezguerra/motor_unit_toolbox/releases
|
|
12
|
+
Keywords: motor unit,motor neuron,MUAP,EMG,spike train,decomposition,MUAP tracking
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: numpy>=1.22
|
|
28
|
+
Requires-Dist: scikit-learn>=1.0
|
|
29
|
+
Requires-Dist: scipy>=1.8
|
|
30
|
+
Requires-Dist: pandas>=1.4
|
|
31
|
+
Requires-Dist: matplotlib>=3.5
|
|
32
|
+
Requires-Dist: seaborn>=0.11
|
|
33
|
+
Requires-Dist: networkx>=2.6
|
|
34
|
+
Requires-Dist: easydict>=1.9
|
|
35
|
+
Provides-Extra: dev
|
|
36
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
37
|
+
Requires-Dist: pytest-cov>=4; extra == "dev"
|
|
38
|
+
Requires-Dist: hypothesis>=6; extra == "dev"
|
|
39
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
40
|
+
Requires-Dist: pre-commit>=3; extra == "dev"
|
|
41
|
+
Provides-Extra: docs
|
|
42
|
+
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
|
|
43
|
+
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
|
|
44
|
+
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
|
|
45
|
+
Dynamic: license-file
|
|
46
|
+
|
|
47
|
+
# Motor Unit Toolbox
|
|
48
|
+
|
|
49
|
+
[](https://pypi.org/project/motor-unit-toolbox/)
|
|
50
|
+
[](https://pypi.org/project/motor-unit-toolbox/)
|
|
51
|
+
[](https://github.com/imendezguerra/motor_unit_toolbox/actions/workflows/ci.yml)
|
|
52
|
+
[](https://imendezguerra.github.io/motor_unit_toolbox/)
|
|
53
|
+
|
|
54
|
+
## Overview
|
|
55
|
+
<!-- --8<-- [start:overview] -->
|
|
56
|
+
Motor Unit Toolbox is a Python package to analyse motor unit (MU) behaviour, from computing basic firing and motor unit action potential (MUAP) properties, to comparing sets of spike trains and tracking MUAPs.
|
|
57
|
+
|
|
58
|
+
The package is composed of the following modules:
|
|
59
|
+
|
|
60
|
+
- `props`: MU properties such as discharge rate, pulse to noise ratio, silhouette measure, and coefficient of variation of the interspike intervals, as well as MUAP features.
|
|
61
|
+
- `spike_comp`: compare spike trains between paired or unpaired sets, as well as within sets. Main metrics are rate of agreement, precision, sensitivity, F1 score, true positives, false positives, and false negatives.
|
|
62
|
+
- `muap_comp`: compare, cluster and track MUAPs within or across recordings.
|
|
63
|
+
- `plots`: plot spike trains, MUAPs, and grouped MUAPs.
|
|
64
|
+
- `utils`: convert between lists of firing times and binary spike train matrices.
|
|
65
|
+
<!-- --8<-- [end:overview] -->
|
|
66
|
+
|
|
67
|
+
## Table of Contents
|
|
68
|
+
- [Installation](#installation)
|
|
69
|
+
- [Quick start](#quick-start)
|
|
70
|
+
- [Documentation](#documentation)
|
|
71
|
+
- [Contributing](#contributing)
|
|
72
|
+
- [License](#license)
|
|
73
|
+
- [Citation](#citation)
|
|
74
|
+
- [Contact](#contact)
|
|
75
|
+
|
|
76
|
+
## Installation
|
|
77
|
+
<!-- --8<-- [start:install] -->
|
|
78
|
+
Install the latest release from PyPI (Python 3.10 or newer):
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
pip install motor-unit-toolbox
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The package is imported as `motor_unit_toolbox`.
|
|
85
|
+
<!-- --8<-- [end:install] -->
|
|
86
|
+
|
|
87
|
+
To work on the code itself, see the development setup in [CONTRIBUTING.md](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/CONTRIBUTING.md#development-setup).
|
|
88
|
+
|
|
89
|
+
## Quick start
|
|
90
|
+
<!-- --8<-- [start:quickstart] -->
|
|
91
|
+
Spike trains are binary matrices of shape `(samples, motor units)`. The example below builds two synthetic motor units, computes their firing properties and compares them with a second (shifted) decomposition:
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
import numpy as np
|
|
95
|
+
|
|
96
|
+
from motor_unit_toolbox import props, spike_comp, utils
|
|
97
|
+
|
|
98
|
+
fs = 2048 # sampling frequency (Hz)
|
|
99
|
+
n_samples = 10 * fs # 10 s recording
|
|
100
|
+
timestamps = np.arange(n_samples) / fs
|
|
101
|
+
|
|
102
|
+
# Spike times (in samples) of two motor units firing at ~10 Hz and ~15 Hz
|
|
103
|
+
rng = np.random.default_rng(0)
|
|
104
|
+
firings = [
|
|
105
|
+
np.cumsum(rng.normal(fs / 10, 10, size=95)).astype(int),
|
|
106
|
+
np.cumsum(rng.normal(fs / 15, 10, size=140)).astype(int),
|
|
107
|
+
]
|
|
108
|
+
spike_trains = utils.firings_to_binary(firings, n_samples) # (samples, units)
|
|
109
|
+
|
|
110
|
+
# Firing properties per motor unit
|
|
111
|
+
props.get_discharge_rate(spike_trains, timestamps) # array([10.05, 15.18]) Hz
|
|
112
|
+
props.get_coefficient_of_variation(spike_trains, timestamps) # array([0.047, 0.074])
|
|
113
|
+
|
|
114
|
+
# Agreement with a second decomposition of the same units (here: shifted by 2 samples)
|
|
115
|
+
roa, pairs, lags = spike_comp.rate_of_agreement_paired(
|
|
116
|
+
spike_trains, np.roll(spike_trains, 2, axis=0), fs=fs
|
|
117
|
+
)
|
|
118
|
+
roa # array([1., 1.])
|
|
119
|
+
```
|
|
120
|
+
<!-- --8<-- [end:quickstart] -->
|
|
121
|
+
|
|
122
|
+
## Documentation
|
|
123
|
+
The full API reference, with every function and its arguments, is at
|
|
124
|
+
[imendezguerra.github.io/motor_unit_toolbox](https://imendezguerra.github.io/motor_unit_toolbox/).
|
|
125
|
+
|
|
126
|
+
## Contributing
|
|
127
|
+
Contributions are welcome! [CONTRIBUTING.md](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/CONTRIBUTING.md) explains how to set up a development environment, run the tests, preview the docs, and what the automated checks (pre-commit and CI) do.
|
|
128
|
+
|
|
129
|
+
## License
|
|
130
|
+
This project is licensed under the [MIT License](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/LICENSE).
|
|
131
|
+
|
|
132
|
+
## Citation
|
|
133
|
+
|
|
134
|
+
If you use this code in your research, please cite it. On GitHub, the **Cite this repository** button (from [`CITATION.cff`](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/CITATION.cff)) gives APA and BibTeX formats, or use:
|
|
135
|
+
|
|
136
|
+
```bibtex
|
|
137
|
+
@software{Mendez_Guerra_Motor_Unit_Toolbox,
|
|
138
|
+
author = {Mendez Guerra, Irene},
|
|
139
|
+
title = {{Motor Unit Toolbox}},
|
|
140
|
+
url = {https://github.com/imendezguerra/motor_unit_toolbox}
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Contact
|
|
145
|
+
|
|
146
|
+
For any questions or inquiries, please contact:
|
|
147
|
+
```
|
|
148
|
+
Irene Mendez Guerra
|
|
149
|
+
irene.mendez17@imperial.ac.uk
|
|
150
|
+
```
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Motor Unit Toolbox
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/motor-unit-toolbox/)
|
|
4
|
+
[](https://pypi.org/project/motor-unit-toolbox/)
|
|
5
|
+
[](https://github.com/imendezguerra/motor_unit_toolbox/actions/workflows/ci.yml)
|
|
6
|
+
[](https://imendezguerra.github.io/motor_unit_toolbox/)
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
<!-- --8<-- [start:overview] -->
|
|
10
|
+
Motor Unit Toolbox is a Python package to analyse motor unit (MU) behaviour, from computing basic firing and motor unit action potential (MUAP) properties, to comparing sets of spike trains and tracking MUAPs.
|
|
11
|
+
|
|
12
|
+
The package is composed of the following modules:
|
|
13
|
+
|
|
14
|
+
- `props`: MU properties such as discharge rate, pulse to noise ratio, silhouette measure, and coefficient of variation of the interspike intervals, as well as MUAP features.
|
|
15
|
+
- `spike_comp`: compare spike trains between paired or unpaired sets, as well as within sets. Main metrics are rate of agreement, precision, sensitivity, F1 score, true positives, false positives, and false negatives.
|
|
16
|
+
- `muap_comp`: compare, cluster and track MUAPs within or across recordings.
|
|
17
|
+
- `plots`: plot spike trains, MUAPs, and grouped MUAPs.
|
|
18
|
+
- `utils`: convert between lists of firing times and binary spike train matrices.
|
|
19
|
+
<!-- --8<-- [end:overview] -->
|
|
20
|
+
|
|
21
|
+
## Table of Contents
|
|
22
|
+
- [Installation](#installation)
|
|
23
|
+
- [Quick start](#quick-start)
|
|
24
|
+
- [Documentation](#documentation)
|
|
25
|
+
- [Contributing](#contributing)
|
|
26
|
+
- [License](#license)
|
|
27
|
+
- [Citation](#citation)
|
|
28
|
+
- [Contact](#contact)
|
|
29
|
+
|
|
30
|
+
## Installation
|
|
31
|
+
<!-- --8<-- [start:install] -->
|
|
32
|
+
Install the latest release from PyPI (Python 3.10 or newer):
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
pip install motor-unit-toolbox
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The package is imported as `motor_unit_toolbox`.
|
|
39
|
+
<!-- --8<-- [end:install] -->
|
|
40
|
+
|
|
41
|
+
To work on the code itself, see the development setup in [CONTRIBUTING.md](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/CONTRIBUTING.md#development-setup).
|
|
42
|
+
|
|
43
|
+
## Quick start
|
|
44
|
+
<!-- --8<-- [start:quickstart] -->
|
|
45
|
+
Spike trains are binary matrices of shape `(samples, motor units)`. The example below builds two synthetic motor units, computes their firing properties and compares them with a second (shifted) decomposition:
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import numpy as np
|
|
49
|
+
|
|
50
|
+
from motor_unit_toolbox import props, spike_comp, utils
|
|
51
|
+
|
|
52
|
+
fs = 2048 # sampling frequency (Hz)
|
|
53
|
+
n_samples = 10 * fs # 10 s recording
|
|
54
|
+
timestamps = np.arange(n_samples) / fs
|
|
55
|
+
|
|
56
|
+
# Spike times (in samples) of two motor units firing at ~10 Hz and ~15 Hz
|
|
57
|
+
rng = np.random.default_rng(0)
|
|
58
|
+
firings = [
|
|
59
|
+
np.cumsum(rng.normal(fs / 10, 10, size=95)).astype(int),
|
|
60
|
+
np.cumsum(rng.normal(fs / 15, 10, size=140)).astype(int),
|
|
61
|
+
]
|
|
62
|
+
spike_trains = utils.firings_to_binary(firings, n_samples) # (samples, units)
|
|
63
|
+
|
|
64
|
+
# Firing properties per motor unit
|
|
65
|
+
props.get_discharge_rate(spike_trains, timestamps) # array([10.05, 15.18]) Hz
|
|
66
|
+
props.get_coefficient_of_variation(spike_trains, timestamps) # array([0.047, 0.074])
|
|
67
|
+
|
|
68
|
+
# Agreement with a second decomposition of the same units (here: shifted by 2 samples)
|
|
69
|
+
roa, pairs, lags = spike_comp.rate_of_agreement_paired(
|
|
70
|
+
spike_trains, np.roll(spike_trains, 2, axis=0), fs=fs
|
|
71
|
+
)
|
|
72
|
+
roa # array([1., 1.])
|
|
73
|
+
```
|
|
74
|
+
<!-- --8<-- [end:quickstart] -->
|
|
75
|
+
|
|
76
|
+
## Documentation
|
|
77
|
+
The full API reference, with every function and its arguments, is at
|
|
78
|
+
[imendezguerra.github.io/motor_unit_toolbox](https://imendezguerra.github.io/motor_unit_toolbox/).
|
|
79
|
+
|
|
80
|
+
## Contributing
|
|
81
|
+
Contributions are welcome! [CONTRIBUTING.md](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/CONTRIBUTING.md) explains how to set up a development environment, run the tests, preview the docs, and what the automated checks (pre-commit and CI) do.
|
|
82
|
+
|
|
83
|
+
## License
|
|
84
|
+
This project is licensed under the [MIT License](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/LICENSE).
|
|
85
|
+
|
|
86
|
+
## Citation
|
|
87
|
+
|
|
88
|
+
If you use this code in your research, please cite it. On GitHub, the **Cite this repository** button (from [`CITATION.cff`](https://github.com/imendezguerra/motor_unit_toolbox/blob/main/CITATION.cff)) gives APA and BibTeX formats, or use:
|
|
89
|
+
|
|
90
|
+
```bibtex
|
|
91
|
+
@software{Mendez_Guerra_Motor_Unit_Toolbox,
|
|
92
|
+
author = {Mendez Guerra, Irene},
|
|
93
|
+
title = {{Motor Unit Toolbox}},
|
|
94
|
+
url = {https://github.com/imendezguerra/motor_unit_toolbox}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Contact
|
|
99
|
+
|
|
100
|
+
For any questions or inquiries, please contact:
|
|
101
|
+
```
|
|
102
|
+
Irene Mendez Guerra
|
|
103
|
+
irene.mendez17@imperial.ac.uk
|
|
104
|
+
```
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "1.2.0"
|