| Badges | |
|---|---|
| Repository |  |
| License |  |
| Citation |  |
| GitHub Actions |    |
| Python support |   |
| Linting |  |
M3Resp is a Python package for the analysis of respiratory recordings from three modalities: electrical impedance tomography (EIT), electromyography of the respiratory muscles (EMG) and ventilator signals (airway pressure, flow and volume). It puts the recordings on one shared clock, processes each modality, finds the breaths, and matches each breath across the modalities. Each analysis is a workflow file that lists every step and every setting. You can run the same file again and get the same results.
- Documentation: docs/
- Source code: https://github.com/M3RESP/m3resp
- Bug reports and questions: https://github.com/M3RESP/m3resp/issues
- Contributing: CONTRIBUTING.md
- Citation: CITATION.cff
- One
M3Sessionobject that holds the recordings, signals, breaths, parameters, quality flags and processing history of one analysis. - Loaders for EIT files (for example Dräger
.bin), EMG files (.Poly5and Biopac.txt) and ventilator files. - EMG processing: filters, ECG removal, envelope, baseline and breath detection.
- EIT processing: filters, global impedance, breath detection, tidal impedance variation (TIV), end-expiratory lung impedance (EELI) and pixel maps.
- Ventilator processing: breath detection and occlusion manoeuvres (Pocc).
- Synchronization of recordings with an offset that you enter, interpolation of a signal onto the time points of another signal, and matching of breaths across modalities.
- Workflows in YAML or JSON, with a command-line tool to list the steps and run a workflow.
- Three presets for a fast start: EIT only, EMG only and multimodal.
- Export of breaths, parameters, quality flags and figures to CSV, JSON and PNG files, with a record of each processing step.
The repository has synthetic EIT, EMG and ventilator recordings in tests/data. This command runs a full multimodal workflow on them:
m3resp run examples/multimodal_example/multimodal.workflow.yamlThe workflow loads the three recordings and synchronizes them. Then it finds the breaths in each modality and calculates the parameters. The results go to a new folder in output/multimodal-summary/, with one CSV file for each breath list, a parameters.csv file, a summary.json file and figures.
You can do the same analysis step by step in Python:
import os
from m3resp import M3Session
data = os.path.join("tests", "data")
session = M3Session()
session.load_eit(os.path.join(data, "m3resp_multimodal_1_eit_draeger.bin"), vendor="draeger")
session.load_emg(os.path.join(data, "m3resp_multimodal_1_emg.Poly5"))
# The EMG recording started 2 s before the EIT recording.
session.synchronize_raw_modalities(offset_seconds={"emg": -2.0})
session.preprocess_eit()
session.preprocess_emg(channel=1)
session.detect_eit_breaths()
baseline = session.emg_moving_baseline() # the quiet level of the EMG envelope
session.detect_emg_breaths(baseline=baseline)
session.export_summary(os.path.join("output", "my-first-analysis"))To see all workflow steps, run m3resp steps. If you installed M3Resp with uv, put uv run in front of each command, for example uv run m3resp steps.
M3Resp is not on PyPI yet. Install it from this repository, in a new virtual environment (see the guides for venv or conda).
The example recordings in tests/data are stored with Git LFS. Install git-lfs and run git lfs install once, before you clone the repository. If you cloned the repository before you installed git-lfs, run git lfs pull in the repository folder to download the recordings.
git clone https://github.com/M3RESP/m3resp.git
cd m3resp
python -m pip install -e ".[all]" # or: uv sync --extra allThe [all] option installs the EIT and EMG packages. To install only the part that you need, use one of these options:
| Command | Adds | Use it for |
|---|---|---|
python -m pip install -e . |
nothing | the data objects, workflows, synchronization, export, and ventilator data in Biopac .txt files |
python -m pip install -e ".[eit]" |
eitprocessing |
EIT recordings, and the ventilator data in EIT .bin files |
python -m pip install -e ".[emg]" |
resurfemg |
EMG processing, and EMG or ventilator recordings in .Poly5 files |
python -m pip install -e ".[all]" |
both | all of the above |
With uv, use uv sync, uv sync --extra eit, uv sync --extra emg or uv sync --extra all. uv sync installs only the extras in the command and removes all other extras. So name each extra that you need, for example uv sync --extra all --extra dev.
To change the code or run the tests, install the development tools too:
python -m pip install -e ".[all,dev]"
pre-commit installWith uv:
uv sync --extra all --extra dev
uv run pre-commit installM3Resp needs Python 3.12 or newer. The tests run on Python 3.12, 3.13 and 3.14.
The base package needs:
The EIT and EMG options also need:
- eitprocessing, for EIT
- ReSurfEMG, for EMG
The options install both packages from their m3resp-integration branch. pyproject.toml gives the exact sources.
The documentation website is https://m3resp.github.io/m3resp/. Its source is in the docs folder:
- Getting started: installation and a first workflow.
- Tutorials: EIT only, EMG only, and EIT, EMG and ventilator together. Each tutorial is a Python script that you can run.
- How-to guides: the processing settings, synchronization, breath timing and export of results.
- Concepts: the scientific data objects, their units and time axes, and a glossary.
- Workflows: the workflow file format and the list of steps.
- API reference: the Python functions and classes.
- Migration guide: how to move from
eitprocessingorresurfemgcode to M3Resp.
To build the website on your computer, see CONTRIBUTING.md.
M3Resp is part of the M3RESP project, together with two packages for one modality each:
M3RESP/
├── eitprocessing EIT methods
├── ReSurfEMG respiratory EMG methods
└── m3resp synchronization, multimodal analysis and workflows
M3Resp uses eitprocessing for EIT and resurfemg for EMG. Both packages are independent: you can install and use them without M3Resp. Some processing functions in M3Resp come from eitprocessing and ReSurfEMG code; NOTICE.md lists them.
New methods for one modality go into eitprocessing or resurfemg. Synchronization, the shared data objects, workflows and export go into M3Resp.
We welcome contributions, questions and suggestions. Read the contribution guide and the Code of Conduct before you start.
To run the tests and the code checks:
pytest
pre-commit run --all-filesWith uv: uv run pytest and uv run pre-commit run --all-files.
If you use M3Resp in your research, cite the software with the data in CITATION.cff. Also cite eitprocessing and resurfemg if your analysis uses EIT or EMG.
M3Resp is released under the Apache License 2.0. NOTICE.md lists the third-party code in M3Resp and its licenses.