Free · Open source · Citeable

Human respiratory physiology analysis made easier

Respiratory mechanics · work of breathing · diaphragm EMG

A free, open-source desktop application for breath-by-breath analysis of time-series respiratory recordings, with a guided setup, a live preview and QC screen, and a batch runner that opens as a drawer right where you are working. Written by respiratory physiologists for their own research.

Version 2.4.0 GPL-3.0 macOS & Windows app Citeable DOI
RespMech signal-tile logo: a respiratory flow curve with a diaphragm-EMG burst
Validation studies (ERS 2022) A DOI per version Fully open source Desktop app, no coding Reproducible outputs

Why RespMech

Validated, citeable, free and transparent

Advanced calculation and analysis remain a considerable barrier to entry in respiratory physiology research. RespMech is written by researchers, for researchers, as a deliberate move away from black-box analysis.

It is intended to replace the fragile, manually maintained spreadsheet workflows that are so often handed between researchers, and the one-off analysis scripts that are difficult to share, reproduce or maintain.

The project follows an Open Science philosophy: methods should be freely available and fully transparent. RespMech is our contribution to that, and the software we use in our own work. We hope it proves useful in yours.

4
analysis domains in a single pass: mechanics, work of breathing, EMG, entropy
1 click
to exclude an artefactual breath, such as an IC manoeuvre or a cough
3
input formats: MATLAB, Excel and CSV/text
100%
of every calculation open and documented

What it computes

Four analyses from a single recording

RespMech detects each breath from the flow or volume signal and reports every measure both breath by breath and as a per-file average.

Respiratory mechanics

Timing (Ti, Te, Ttot, Ti/Ttot), tidal volume, breathing frequency and minute ventilation, plus oesophageal, gastric and transdiaphragmatic pressure descriptors and pressure–time products.

Work of breathing

Inspiratory elastic, inspiratory resistive and expiratory work of breathing from the Campbell diagram, in J·min⁻¹, per breath or from an averaged loop.

Diaphragm EMG

RMS envelope and integrated EMG per channel, with optional ECG-artefact removal and spectral noise reduction, reported per breath, per inspiration and per expiration.

Sample entropy

Sample entropy of selected channels (for example diaphragm EMG), computed per breath with configurable embedding (m) and tolerance (r), and averaged as for the other measures.

The desktop app

Two tabs, in the order you work

Version 2 is a desktop application with two tabs — a guided setup and a live preview and QC screen — and a batch runner that opens as a drawer under the file list rather than a screen you navigate to. Both tabs stay reachable at any time: only the run itself is ever disabled, and always with the reason beside it. Explore with sample data, offered on the start screen, loads a synthetic recording complete with a heartbeat artefact and volume drift, so each step has representative data to work on.

1

Setup

Select your recordings, map the data columns to channels, and choose what to save. Channels can also be assigned visually from the data. Settings are validated as you type, and the status bar flags any inconsistency before a run.

RespMech Setup tab in two columns: recordings folder, sampling frequency and a per-channel preview with waveform thumbnails on the left; output folder, tables, diagnostic figures and cohort summary on the right, above a green ‘Ready to run — no warnings’ status.
RespMech Preview & QC screen: stacked flow, volume and pressure channels with numbered breaths, a per-breath table and the Campbell diagram.
2

Preview & QC

Inspect the analysis for a single file before running the batch: breath segmentation, the Campbell loop and the per-breath table, with dedicated tabs to tune EMG – ECG reduction and EMG – noise reduction against the live signal; the finer processing settings sit behind an Advanced… button on each tab. Click a breath to exclude it.

3

Run & results — a drawer, not a third tab

Run the batch without leaving the file you are looking at: the drawer opens itself under the file list when a run starts, and each recording's outcome is marked on the file list itself. Read the run log and the averaged metrics there, then open the output folder. A dry run computes everything without writing any files, for a final check of the settings.

RespMech Preview & QC with the Run & results drawer opened beneath the file list: the run controls, a run log, and the averaged per-file metrics table.
Analyses are stored as declarative TOML files rather than executable .py scripts. Open, save and switch between analyses, including recent ones, from the Analysis menu on every screen; RespMech marks unsaved edits and prompts before discarding them.

The science

Every calculation, out in the open

The version 2 engine is a faithful port of the original implementation, locked by characterisation tests. This is what happens between a raw recording and a spreadsheet of results.

Work of breathing

The Campbell diagram

Work of breathing is read from the oesophageal-pressure–volume loop. The faint loops are the individual breaths, the bold one their average, the diagonal the passive elastic-recoil line, and the shaded triangle the elastic component.

  • Inspiratory elastic: the triangle under the lung recoil line between end-expiratory and end-inspiratory lung volume (lung only, no chest-wall line).
  • Inspiratory resistive: the area between the pressure trace and the elastic-recoil line.
  • Expiratory: expiratory pressure above the end-expiratory level, integrated over volume.

Compute per breath and average, or build an averaged loop first and compute from that, which is more robust when breaths are irregular. Results are reported as a per-minute power, in J·min⁻¹ — divide by the breathing frequency for the work of a single breath.

A Campbell / pressure–volume loop for nine breaths: faint individual loops, a bold average breath, the elastic-recoil diagonal and a shaded elastic-work triangle.
Campbell / PV loop: oesophageal pressure versus inspired volume, nine breaths.
Three-panel diaphragm EMG conditioning: raw EMG with off-scale ECG R-waves, then ECG removed, then ECG removed plus spectral noise reduced, each with its RMS envelope overlaid.
Raw → ECG removed → noise reduced. The bold envelope is the RMS the analysis actually measures.

Diaphragm EMG

Conditioned, step by step

The heartbeat (ECG) R-wave is typically several times the diaphragm-EMG amplitude; left in place, it dominates the signal and inflates the RMS. RespMech detects it on the clearest channel and subtracts it first.

Spectral noise reduction, trained on a diaphragm-quiet reference, then cleans the residual noise floor while preserving the inspiratory burst. Both steps are tuned against the live signal on the Preview screen, and every stage is written to the diagnostic figures.

Removing the ECG and then reducing the noise drops the between-breath floor while preserving the bursts. On the recording shown here, the in-band (20–250 Hz) signal-to-noise ratio of the inspiratory pattern rises by about 1.4 dB from step 2 to step 3 — the suppression strength is chosen automatically as the strongest setting that still keeps every channel's inspiratory EMG power at or above the fidelity target (0.8 by default).

Built for real recordings

Segmentation, drift correction and artefact handling

Physiological recordings are rarely clean. RespMech automates the conditioning and documents every step, so the processing remains auditable.

Breath segmentation

Single-click breath exclusion

Breaths are segmented by joining each inspiration with the following expiration, using the flow signal to locate the transition. A breath-separation buffer absorbs low-amplitude flow fluctuation around zero. In Preview & QC, any breath (for example an IC manoeuvre or a cough) can be excluded from the analysis with a single click while remaining visible in the plots.

Flow and volume traces with nine numbered breaths; breath four is shaded red to show it has been excluded from the analysis.
Click a breath to exclude it; breath #4 is shaded red.
Four stacked panels showing volume-correction stages: flow, uncorrected volume, zeroed volume and linear drift-corrected volume returning each breath to baseline.
Volume-correction stages: each end-expiratory volume pulled back to baseline.

Volume drift

Corrected automatically

Volume must be inspired volume; it can be inverted, or integrated from the flow signal when no volume channel is recorded. Drift, which is common when integrating from flow, is corrected automatically, with an optional trend adjustment: whichever way the end-expiratory baseline drifts, the correction returns it to baseline.

MATLAB (.mat) Excel (.xlsx) CSV / text

The recording should start in late expiration and end in early inspiration; RespMech trims it to whole breaths. Flow is taken as negative on inspiration (invert it in Preview & QC if your convention differs).

Outputs you can publish

A results folder that documents itself

Excel workbooks

Across-file averages, optional per-file breath-by-breath values, and a cohort summary. The breath-data workbooks carry their own Units sheet, and every workbook carries Provenance and Version sheets.

Vector PDF diagnostics

Per file: Campbell/PV loops (averaged and per breath), the analysed and raw signals, the staged volume correction, and per-channel EMG overviews at each conditioning stage. Optional EMG as WAV.

The exact recipe

analysis-used.toml and run-report.txt record the exact settings and a log of what was read, kept, excluded and written, so an analysis can be reproduced exactly at any later date.

output/
├─ data/ # Excel: averages, per-breath, cohort
│   ├─ Average breathdata.xlsx
│   ├─ sample_recording.csv.breathdata.xlsx
│   └─ Cohort summary.xlsx
├─ diagnostics/ # vector PDF figures
│   ├─ sample_recording.csv – Campbell (average).pdf
│   ├─ sample_recording.csv – EMG (ECG removed).pdf
│   └─ sample_recording.csv – volume correction.pdf
├─ analysis-used.toml # the exact settings
└─ run-report.txt # read · kept · excluded · written

Prefer the command line?

Scriptable, headless, reproducible

The same engine drives a command-line tool. Point it at a TOML analysis file to process a batch, validate settings and inputs, or migrate a legacy version 1 settings file; no version 1 code is executed.

  • run — process a batch (--dry-run computes without writing).
  • validate — check the settings and the input files.
  • migrate — convert a v1 .py setup, with a report of every field moved, renamed or dropped.
Terminal
# install from source (developers / CLI)
$ git clone https://github.com/emilwalsted/respmech && cd respmech
$ pip install -e ".[dev,gui]"

# process a batch
$ respmech run settings.toml

# check settings + inputs before a run
$ respmech validate settings.toml

# compute without writing anything
$ respmech run settings.toml --dry-run

# bring a v1 setup into the new format
$ respmech migrate old_settings.py -o settings.toml

# or just launch the desktop app
$ respmech-gui

Correctness & Open Science

Transparent by construction

No black boxes: the calculations are readable, the outputs are reproducible, and every version is citeable.

Golden tests

The version 2 engine is a port of the original implementation, kept frozen in the repository as the oracle. Characterisation tests pin breath timing, volumes, ventilation, the pressure descriptors and the elastic work-of-breathing component byte-for-byte against that reference. Two deviations from 1.x are deliberate — the PTP baseline window and a fixed sample-entropy indexing bug — and a third, a SciPy Simpson-integration change, is a library version difference rather than a RespMech choice; all three affected columns are instead pinned to within 1 part in 10⁹ (rtol 1e-9, atol 1e-12) and are documented.

A DOI per version

Every released version has its own DOI, so a paper can cite the exact code that produced its results, with no ambiguity about which version was used.

GPL-3.0, on GitHub

Free to use and to modify. The full source is on GitHub, so every formula can be read and every change tracked between versions.

Cite it like this. The concept DOI below always resolves to the latest archived version; a specific version can be cited with its own DOI from the same Zenodo record.

…were calculated using the Python package RespMech (E Walsted, RespMech v2.4.0, 2026, github.com/emilwalsted/respmech, DOI: 10.5281/zenodo.3270825)…

Two validation studies, one for respiratory mechanics and one for diaphragm EMG, were presented at the European Respiratory Society International Congress 2022 in Barcelona.

Liu A, Molgat-Seon Y, Yuen NYW, Dominelli PB, James MD, O'Donnell DE, Domnik NJ, Walsted ES. Validating RespMech: an automated, free and open-source platform for respiratory mechanics analysis at rest and in exercise. Eur Respir J 2022; abstract 2737. doi: 10.1183/13993003.congress-2022.2737
Liu A, Yuen NYW, Molgat-Seon Y, James MD, O'Donnell DE, Domnik NJ, Walsted ES. Validating RespMech: an automated, free and open-source platform for diaphragmatic electromyography analysis at rest and in exercise. Eur Respir J 2022; abstract 2801. doi: 10.1183/13993003.congress-2022.2801

Get RespMech

Installing RespMech

The desktop application bundles its own Python interpreter; nothing else is required. Python users can install it from PyPI with pip, and developers can run from source with the command-line tool. The desktop installers are built for macOS and Windows; on Linux, install the Python package with pip.

Recommended

Desktop app

Download the installer for your platform from the latest release. It bundles its own Python interpreter and all dependencies.

  • macOS: a signed, notarised .dmg; drag to Applications. Requires macOS 12 (Monterey) or later on an Apple silicon Mac; on an Intel Mac, install from PyPI instead (see the pip card).
  • Windows: an Authenticode-signed .msi installer. Because the certificate is new, SmartScreen may still show “unrecognised app” on the first run — choose More info ▸ Run anyway.
Python users

pip / PyPI

Have Python 3.11+? Install from PyPI. The [gui,emg,plots] extras pull the full package — desktop app, EMG noise reduction and PDF figures. pipx keeps it in its own isolated environment.

# everything, isolated (recommended)
$ pipx install "respmech[gui,emg,plots]"
$ respmech-gui

# …or into a virtual environment
$ pip install "respmech[gui,emg,plots]"
respmech-gui: the app respmech: the CLI
Developers & CLI

From source

Requires Python 3.11+. Clone the repository and install with the extras you need.

$ git clone https://github.com/emilwalsted/respmech
$ cd respmech
$ pip install -e ".[dev,gui]"
$ respmech-gui
gui: desktop app emg: noise reduction plots: PDF figures dev: test stack

Free and open source under the GNU General Public License v3.0 or later.

The story

Why I built RespMech, and why it stays open

A tool I wrote for myself, because I had no black box to inherit.

Before I studied medicine I was a programmer, and I suppose I never quite stopped thinking like one. During my PhD I spent time in England working on advanced analysis of respiratory-physiology data, learning from several people who knew the field far better than I did. What struck me, and frankly frustrated me, was how much of the work was still done by hand. Every manual step was another place for an error to creep in, quietly, without anyone noticing.

I also began to realise how these analyses are passed on. Many groups run their work on a setup handed down through several generations of researchers: numbers go in, analyses come out, and to varying degrees no one still in the room can say exactly what happens in between. The setup gets used largely because the group has published with it before. That is an understandable reason, but it was not one I could work from. I had no such inheritance of my own, so I built my analysis from scratch and, given my background, coded all of it into an automated setup.

It was never meant to be a product. But colleagues grew curious, asked to borrow the code and try it on their own data, and I shared it, because there was no reason not to. A couple of years later, at a conference, I met Nicolle Domnik from Canada, who told me she was already using it herself. Out of that conversation came a different idea: not code passed quietly between friends, but a genuinely public, open-source library that anyone could read, and where everyone gets the same updates.

That conversation became a collaboration. Over the following years we worked on validating and developing the library further, and Yannick Molgat-Seon became a central contributor and part of the group. With help from junior researchers Annie Liu and Nathaniel Yuen, we carried out a larger validation study, presented at the European Respiratory Society International Congress 2022. We are now preparing the full paper for publication, with the support of the Danish Respiratory Society (Dansk Lungemedicinsk Selskab); we will link it here when it appears.

None of us has been paid for any of this. RespMech is a con amore project, built in our spare time because we think it matters. The analyses are demanding, and anyone who takes them on deserves a tool that carries them over the hard part rather than another black box to trust on faith. That is the tool we set out to build, and the reason we keep it in the open.

RespMech is, and will remain, free, open source and freely available, because that is how science should be.

Emil Ingerslev Walsted, consultant in respiratory medicine and creator of RespMech

About us

Built by researchers, for researchers

RespMech is a loosely coupled network with an interest in respiratory and exercise physiology. Regardless of our different backgrounds, we are all passionate about Open Science.

Nicolle J. Domnik

Nicolle J. Domnik PhD

Assistant Professor, Dept. of Biomedical & Molecular Sciences, Queen’s University, Kingston (ON), Canada

Yannick Molgat-Seon

Yannick Molgat-Seon PhD

Associate Professor, Dept. of Kinesiology & Applied Health, University of Winnipeg, Winnipeg (MB), Canada

Annie Liu

Annie Liu

Physiology and Pharmacology, Western University, London (ON), Canada

Nathaniel Ying-Wai Yuen

Schulich School of Medicine & Dentistry, Western University, Windsor (ON), Canada

Questions or ideas?

If a feature would make RespMech more useful for your research, please get in touch.

emilwalstedgmail.com