Using RespMech

Overview

RespMech analyses respiratory-physiology recordings — airflow, lung volume, oesophageal (Poes), gastric (Pgas) and transdiaphragmatic (Pdi) pressures, and one or more diaphragm-EMG channels — exported from your acquisition system. It splits each recording into individual breaths and, for every breath, computes a full set of respiratory-mechanics, work-of-breathing, EMG and signal-complexity descriptors, each carried with its own physical unit.

You drive it two ways. The desktop app (respmech-gui) walks you through Setup → Preview & QC, with Run & results as a drawer inside the second tab; the command line runs a batch headless from a TOML settings file. The out-of-the-box defaults reproduce the validated reference pipeline. Three documented differences from RespMech 1.x remain — the PTP baseline window, the sample-entropy indexing fix and SciPy's change to Simpson integration — see Changes from RespMech 1.x.

respmech run settings.toml

What RespMech computes

RespMech produces four families of analysis. Each owns its own section below — this page is the map.

• Respiratory mechanics — breath timing (inspiratory time Ti, expiratory time Te, total cycle time Ttot and the duty cycle Ti/Ttot), tidal volume (VT), breathing frequency (bf) and minute ventilation (VE), plus oesophageal, gastric and transdiaphragmatic pressure descriptors, their pressure–time products (PTP), an isovolume inspiratory lung-resistance estimate and the gastric/oesophageal pressure ratio.
• Work of breathing — the mechanical work the respiratory muscles perform, read from the Campbell (pressure–volume) diagram and split into inspiratory elastic, inspiratory resistive and expiratory components, reported as a per-minute power in J·min⁻¹.
• Diaphragm EMG — a per-breath RMS amplitude and integrated EMG for each EMG channel (whole breath, inspiration and expiration), with optional cardiac-artefact (ECG) removal, spectral noise reduction, a cardiac-gated peak, and per-file amplitude normalisation.
• Sample entropy — a dimensionless measure of how irregular or complex a signal is, computed per breath on any column you tick as an entropy channel (typically the diaphragm EMG).

The breath-by-breath & averaged model

Everything RespMech reports rests on one model: the recording is cut into whole breaths, every descriptor is measured on each breath, and the breaths are then summarised. In detail:

• Trim, then segment. RespMech first trims the recording to whole breaths, then splits it into individual breaths. By default a breath boundary is a flow zero-crossing; you can instead detect breaths from volume peaks (see Splitting the record into breaths). A breath is one inspiration plus the expiration that follows it.
• Per breath, then averaged. Every descriptor is computed for each breath and again as a per-file average across the breaths you keep. You can mark artefactual breaths (coughs, swallows, sighs) in Preview & QC so they are dropped from the average.
• Rates are scaled from the file's own duration. Breathing frequency and minute ventilation come from the trimmed recording length and the detected breath count.

where T_file is the trimmed recording length in seconds and bcnt the detected breath count. This same per-minute factor turns each breath's pressure–time product and work into a rate, which is why those columns carry a ·min⁻¹ in their unit.

Units at a glance

Every output column carries an explicit physical unit. Use this table to orient yourself before diving into a section:

Scope and limitations

RespMech is analysis software: it turns signals you have already recorded into breath-by-breath descriptors. It does not, and cannot, verify that the recording itself is a valid measurement of the physiology it is labelled as. This section states the assumptions the analysis rests on, none of which the program checks for you.

Oesophageal pressure measurement

Every Poes-derived descriptor — both inspiratory pressure–time products, the isovolume lung-resistance estimate, the gastric/oesophageal ratio, and the whole Campbell-diagram work calculation — assumes that the oesophageal balloon signal is a valid surrogate for pleural pressure. That assumption is a property of the measurement, not of the software, and RespMech has no way to test it from the recorded trace alone. Two things make it more or less true:

• Balloon position and volume. An oesophageal balloon reads pleural pressure faithfully only over a limited range of positions and fill volumes, and only in some body positions; deviations are largest supine (Baydur, Behrakis, Zin, Jaeger & Milic-Emili, Am Rev Respir Dis 1982;126:788–791). The conventional check is the occlusion test — comparing swings in Poes to swings in mouth (or airway-opening) pressure during a brief airway occlusion, which should track 1:1 if the balloon is well positioned (Milic-Emili, Mead, Turner & Glauser, J Appl Physiol 1964;19:207–211).
• Catheter and technique in general. RespMech does not describe balloon placement, calibration or the occlusion test itself — that is measurement technique, not software, and is covered by the ATS/ERS statements: ATS/ERS statement on respiratory muscle testing (2002) and Laveneziana et al., ERS statement on respiratory muscle testing at rest and during exercise (2019).

Validate the balloon before you trust any Poes-, tlr_insp- or work-of-breathing-derived number; RespMech will compute all of them from an invalid trace exactly as readily as from a valid one, with no warning either way.

A stable, representative epoch

The per-file average, the averaged Campbell loop and the per-file EMG reference all assume the exported window is a stable, representative stretch of a single condition. Breathing frequency and minute ventilation are computed from that window's own duration and its full detected breath count (see The breath-by-breath & averaged model), so an epoch that spans a transition — onset of exercise, a change in load, recovery — returns the average of two states and reports it as one. Export a settled period per condition rather than one long file. Excluding breaths in Preview & QC removes them from the averages but not from the per-minute scaling, so it cannot repair an epoch that mixes conditions.

Units are assumed, never checked

RespMech reads flow as L·s⁻¹, volume as L, and Poes, Pgas and Pdi as cmH₂O. Nothing in the program verifies this: the loader checks only that each column is numeric, free of NaN, and the same length as the others (see Supported file formats). A recording exported in mL·s⁻¹, mbar, kPa or raw transducer volts will load, run and produce a full set of results with no error at all — and the numbers are not simply your numbers in another unit: work of breathing and the pressure–time products carry the conversion factor of two signals at once, and any setting expressed in signal units (the breath-detection minimum peak height, the legacy absolute trend anchor in litres) stops meaning what it says. It is the same failure mode as a wrong sampling frequency, and just as invisible. Confirm the export units in your acquisition system before the first run, and sanity-check one file's tidal volume and peak Poes against what you expect physiologically.

Getting started

RespMech turns raw respiratory recordings — flow, volume, oesophageal / gastric / transdiaphragmatic pressures, and optional diaphragm EMG — into breath-by-breath mechanics: tidal volume and ventilation, work of breathing from the Campbell (pressure–volume) diagram, pressure–time products, and EMG amplitudes. You can drive it two ways from the same analysis engine:

• The desktop app (respmech-gui) — two tabs and a drawer: Setup (choose recordings, map channels, pick outputs) → Preview & QC (see the signals and tune breath detection and EMG conditioning while everything recomputes live), with Run & results a drawer under the file list (batch-process every file and write the workbooks). The workflow deliberately loops — tune, re-run — rather than running once.
• The command-line tool (respmech) and Python library — the identical engine, driven headlessly from a plain-text settings file so a whole batch is scriptable and reproducible (ideal for pipelines and CI).

A single settings file holds every knob for one batch of recordings. Throughout the app this file is always called an analysis (the underlying format is TOML, but the UI never says so).

Install

Desktop app (recommended for most users). Download the installer for your platform from the project's latest release. It is fully self-contained — it bundles its own Python and every dependency, so there is nothing else to install.

• macOS — RespMech-<version>.dmg (signed and notarised); open it and drag RespMech to Applications. The bundle is built for Apple silicon and requires macOS 12 or later. On an Intel Mac, install the Python package instead (pip install "respmech[gui]").
• Windows — RespMech-<version>.msi (signed); run the installer.

See what's new in the latest release →

Python package (for the CLI or library). Requires Python 3.11 or newer (the settings loader uses the standard-library tomllib). Runs on macOS, Windows and Linux; the desktop installers above are built only for macOS and Windows, but the Python package runs anywhere Python does. The base install gives you the respmech command-line tool and the analysis core with no Qt or heavyweight audio stack; add extras for more:

pip install respmech                     # CLI + core analysis engine
pip install "respmech[gui,emg,plots]"    # + the desktop app, the built-in sample and diagnostic PDF figures

• gui — the desktop app (PySide6, pyqtgraph, matplotlib); needed to launch respmech-gui.
• emg — EMG spectral noise reduction (librosa).
• plots — diagnostic PDF figures (matplotlib).

Confirm the install and see the available commands:

respmech --version
respmech --help

Your first analysis (sample data)

The fastest way to see the whole pipeline is the built-in sample recording — synthetic data with a deliberate ECG artefact and EMG noise, so every stage (including EMG conditioning) has something to do. It contains no patient data, so you can experiment freely.

1. Launch the app. Open RespMech from Applications / the Start menu, or from a terminal:

   respmech-gui

   A brand splash appears, then the window opens maximised and shows the start chooser.

2. Choose “Explore with sample data.” The chooser offers New analysis (guided, step by step), New from last rig (reuses your last channel mapping and sampling rate, shown only if one exists), Open analysis… (a saved analysis or a legacy 1.x .py file, which is migrated for you), Explore with sample data, and up to five recent analyses. Pick Explore with sample data.

   

3. Setup — review what will be analysed. For the sample, the Input, Output and Channels cards are already filled in. The Input card names the recordings folder and file mask and shows a live read-out of the detected column count and delimiter of the first matching file; the Channels card shows the flow, volume, pressure and EMG columns assigned through the visual picker; the Output card lists what will be saved, with a live “You will get” summary. A pinned QC strip reports live cautions (channel collisions, EMG overlaps, a low sampling frequency) or an all-clear. Both tabs are reachable throughout — nothing to unlock; only the run itself waits for a valid setup, and says what is missing. The sample also arrives with its EMG conditioning pre-tuned, so both EMG tabs have something to show: ECG removal is on (capture channel EMG2, threshold 0.4) and spectral noise reduction is on, referenced to a quiet lead-in — both off by documented default. Your own analyses start from the documented defaults instead.

   

4. Preview & QC — look, then tune. Open the Preview tab and select the file (the ◀ / ▶ buttons, PageUp / PageDown, or Refresh). Selecting a file automatically fans every computation out onto worker threads, so the plots and the QC verdict update as you watch. The sub-tabs run in pipeline order: Mechanics (flow, volume and pressure on a shared time axis with breath boundaries and the trim window, a Campbell diagram and per-breath table below — click a numbered breath to include or exclude it), then, when EMG channels are present, › EMG – ECG reduction and › EMG – noise reduction. The Mechanics QC strip reads, for example, QC: N breaths used, M excluded · no flags. Tuning a parameter here recomputes only the affected panels — this live scoping affects the preview alone; the batch always uses the full settings.

5. Run & results — process and write. Open the Run & results ▸ drawer beneath the file list and click Run batch (or Dry run to compute without writing anything); starting a run opens the drawer for you. A pre-flight plan logs exactly what will be read and written, and a real run warns before overwriting an output folder that already contains results. A live log tracks the batch and each file's outcome is marked on the file list itself; on completion you get the averaged-metrics table, Re-run failed, and Open output folder.

   In the shipped v2.4.0 this toggle button's own label reads “Run  results ▸” below (the ampersand is swallowed as a keyboard mnemonic marker and the gap is underlined) — it is the same control, and the caption is fixed in the next release.

   

A run writes the workbooks into the output folder's data/ subfolder: data/Average breathdata.xlsx (the across-breath average, paired with a cohort summary), a per-file data/<file>.breathdata.xlsx, and an optional processed-signal CSV; the diagnostic figures you enabled go into a sibling diagnostics/ subfolder. It always also writes an analysis-used.toml snapshot of the exact settings and a run-report.txt in the output folder's root, so any result is reproducible.

The same run from the command line

Everything the app does in Run & results is available headlessly. The CLI reads the same analysis file and drives the same engine, so a batch can be scripted or dropped into CI. If you never open the desktop app, start from the annotated settings.toml further down — the same file also ships in the app repository as examples/settings.toml, already wired to a bundled sample recording, so respmech validate examples/settings.toml runs with nothing to edit. Copy it into your own study folder, set input.folder, input.files, input.format.sampling_frequency and the seven input.channels entries to match your export, then run respmech validate before anything else. Once you have an analysis file — the annotated example, one saved from the app, or hand-written — the typical end-to-end sequence is:

respmech validate settings.toml      # check the settings and count matching input files
respmech run settings.toml --dry-run # compute without writing anything (quick check)
respmech run settings.toml           # process the batch, write to <output.folder>/data/

There is also respmech migrate old_settings.py -o settings.toml, which converts a legacy 1.x settings file to the new format (without executing it) and prints a migration report — the same conversion the app runs when you open a .py file.

Preparing your recording

RespMech analyses breath-by-breath respiratory recordings exported from LabChart or a similar acquisition system. Before it can compute mechanics, three things must be true: the file must be in a format RespMech can read, each physiological signal must be mapped to the right data column, and the trace must follow RespMech's sign conventions and start and end in the right part of the breath. This section covers everything you set up before the analysis runs. Signal conditioning after loading — drift correction, breath segmentation, resampling, and per-breath exclusions — is covered in the sections that follow.

In the desktop app these settings live on the Setup screen (Input and Channels cards); CLI users edit the same keys directly in the analysis TOML.

Supported file formats

RespMech chooses a loader by file extension:

• .mat — MATLAB export from LabChart. The input.format.matlab_variant setting selects the byte layout: windows reads a data_block1 structure, mac reads each variable in column order. Only simple LabChart .mat exports are supported; for anything more complex, export to CSV instead.
• .xlsx — Excel workbooks. The older binary .xls format is not supported; re-save it as .xlsx or export to CSV.
• .csv — comma- (or semicolon-) separated text.
• .txt — tab-separated text.

Text files are read tolerantly across encodings (UTF-16 "Unicode Text", UTF-8 with or without BOM, cp1252, latin-1), so exports from mixed instrument and operating-system chains usually load without manual conversion.

The first row is read as a header row. For .csv, .txt and Excel inputs RespMech treats row 1 as channel names and does not analyse it. Most instrument exports carry one, but if yours starts straight at the first sample, that sample is silently dropped — add a header row before analysing. .mat inputs have no header row and are unaffected.

For delimited text (.csv and .txt), the input.format.decimal setting tells RespMech which character marks the decimal point. Setting it to , for a European export also switches CSV parsing to semicolon-separated columns, matching how those files are written. The decimal setting is ignored for Excel and MATLAB, which carry their numbers natively.

Mapping columns to signals

RespMech identifies each physiological signal by its column number in the recording. Columns are numbered from 1, matching the LabChart export exactly. Column 1 is normally the time axis, so pointing a required signal at column 1 is flagged as an error, as are leaving a required channel unassigned, colliding two channels on the same column, or referencing a column beyond the file's width.

In the desktop app you do not count columns by hand. Click Assign channels from data… to open the visual picker: it plots every column so you can see which is flow, which is a pressure, and so on, then assign each role from a dropdown and tick any EMG and Entropy columns. On OK it also auto-detects the sampling frequency and (for .txt) the decimal separator from the data. A live QC strip flags unassigned, colliding or time-axis channels and EMG overlaps.

Flow, Poes (oesophageal pressure), Pgas (gastric pressure) and Pdi (transdiaphragmatic pressure) are always required. Volume is optional — but only if you let RespMech integrate it from flow (see the conventions below). EMG and entropy are optional lists of columns. Entropy is non-exclusive: a column already carrying flow, a pressure or EMG can also be selected for sample-entropy analysis, and when the same column is also an EMG channel, entropy is computed on the processed EMG rather than the raw trace.

Flow and volume conventions

RespMech expects two sign conventions:

• Inspiration reads negative flow. Trimming and flow-based segmentation both depend on this.
• Inspired volume is positive.

If your rig records the opposite polarity, do not edit the data — fix it at load time with the invert toggles. RespMech applies these steps in a fixed order when it loads each file: invert flow (if requested), integrate volume from flow (if no volume channel), invert volume (if requested), then validate.

When you have no recorded volume channel, RespMech derives volume by integrating flow. Because integration uses the file's true sampling rate (even when pre-analysis resampling is active), it stays accurate regardless of the analysis rate you later choose:

The leading minus sign is what turns an inspiration recorded as negative flow into a positive inspired volume — the second convention above.

What a valid recording looks like

RespMech works on whole breaths, so it needs a clean epoch to slice. The recording must start in late expiration and end in early inspiration. RespMech then trims it automatically to whole breaths: it finds the first inspiration sample (the first point where flow goes negative) and the last sample where flow is still non-negative, and slices every channel to that range. The leading partial expiration and the trailing partial inspiration are discarded, leaving a run of complete breaths.

If flow never crosses zero — usually because the polarity is inverted or the wrong column is mapped to flow — or the trimmed range comes out empty, RespMech raises a trim error naming the flow channel and the invert-flow setting, and the file is not analysed.

Once a file loads, maps cleanly to channels, follows the sign conventions and trims to whole breaths, it is ready for the conditioning and segmentation steps described next.

The app — Setup

Setup is the first of the desktop app's two tabs (Setup → Preview & QC, with Run & results a drawer inside the second). It answers three questions and nothing else: which recordings to analyse, which data column carries which signal, and what to save. Everything you set here is stored in one analysis — a single settings file that holds every knob for one batch of recordings. The interface always says “analysis”; the word “TOML” never appears on screen, but that is what the file is, and CLI users edit the same dotted keys directly.

The tab is laid out in two columns of cards: Input and Channels on the left, Output and — only when you assign an entropy column — Sample entropy on the right. Every card is visible from the start, and both tabs stay reachable whether or not the analysis validates yet: only the run itself is gated, and the reason is written beside it. A menu bar (File, View, Help) sits above the tabs.

The Input card

The Input card points RespMech at your recordings and tells it how they are timed. RespMech reads breath-by-breath recordings exported from LabChart or a similar system in MATLAB (.mat), Excel (.xlsx), comma-separated (.csv) or tab-separated (.txt) form; the loader dispatches on the file extension.

A Browse… button picks the folder, and a live read-out underneath reports what was detected in the first matching file — how many files matched the mask, the column count, and the delimiter — so a mis-picked folder or a wrong mask is obvious before you go further.

Time is derived, not read: for sample n, RespMech uses

The Channels card

RespMech needs to know which raw data column carries each physiological signal. Columns are numbered from 1, matching the LabChart export, and column 1 is normally the time axis. Rather than typing column numbers, you assign them visually: the Assign channels from data… button opens a picker that plots every column on a shared time axis so you can see which trace is flow, which is a pressure, and which is EMG, then pick each column's role from a dropdown.

Single roles are mutually exclusive — a column is Flow or Poes, not both — but the Entropy tickbox is independent, so a column can carry a role and be an entropy column. The required roles (Flow, Poes, Pgas, Pdi) gate the picker's OK button, and the chosen mapping applies to every file in the batch. When you click OK the picker also auto-detects the sampling frequency and (for .txt) the decimal separator from the data, and narrows a multi-pattern file mask to a single extension.

Back on the card, a read-only summary shows the assignments (and reads “Volume: derived from flow” when volume is integrated rather than recorded), while the pinned QC strip flags live cautions — an unassigned required channel, two channels colliding on one column, a required channel pointed at the time axis, or an EMG column overlapping a pressure/flow column.

The Output card

The Output card decides where results are written and which of them to write. Numeric tables are saved into a data subfolder inside the output folder, diagnostic figures into a diagnostics subfolder, and a settings snapshot (analysis-used.toml) and a run-report.txt are written at the top of the output folder itself; a full run always writes both. A live “You will get” line lists the exact deliverables before you run, and a real run warns before overwriting an output folder that already contains results.

The Sample-entropy card

This card appears only when you have assigned at least one entropy column in the picker; otherwise it stays hidden. It exposes the two parameters of the sample-entropy statistic

computed on each ticked entropy column. When a column is also an EMG channel, entropy is computed on the processed (conditioned) EMG rather than the raw trace.

With Input, Channels and Output valid and the QC strip clear, the run is ready to start. Continue to Preview & QC to tune breath detection and EMG conditioning on a real file, then open the Run & results drawer there to process the batch.

The app — Preview & QC

Preview & QC is the second of the desktop app's two tabs (respmech-gui) and the one where you spend most of your time. You work on one recording at a time, watch every plot redraw as you tune a parameter, read the quality-control verdict, and exclude any breath that should not count — all before you commit the whole batch to a run. Setup decides what to analyse; Preview decides how; Run does it to every file with the exact settings you tuned here.

How the Preview screen works

Selecting a file kicks off every computation the current settings allow. Independent jobs run concurrently on worker threads (capped at two at once so the window stays responsive), and edits are debounced by 300 ms and collapsed into a single re-dispatch, so dragging a value redraws smoothly rather than in a stutter. A dependency map scopes which panels recompute for a given change — editing an EMG control does not re-run the mechanics preview and vice-versa.

A file list on the left (the same list Run & results marks outcomes on) holds one row per file matched by your Setup mask, with a Filter files… box above it. Click a row to preview it, or step with the ◀ / ▶ buttons, Ctrl+[ / Ctrl+] (⌘[ / ⌘] on macOS), Alt+← / Alt+→, or PageUp / PageDown while the list has focus. Refresh recomputes every preview panel for the current file (its tooltip: “Recompute all preview panels for the current file.”). Nothing is watched in the background, but the per-file caches are keyed on the file's modification time and size, so pressing Refresh after editing a recording on disk picks up the new data. The mouse wheel scrolls the list and the page; over a spin box it is passed on to the page rather than changing the value, because every such change would dirty the analysis and schedule a recompute.

Below the file list, sub-tabs run in fixed pipeline order, the two EMG tabs carrying a leading chevron to signal the flow: Mechanics, › EMG – ECG reduction, › EMG – noise reduction. The two EMG tabs appear only when you have assigned EMG channels on Setup; with no EMG channels, Mechanics is the whole screen.

The Mechanics tab

The Mechanics tab stacks flow, volume and the pressure channels (Poes, Pgas, Pdi) on a shared time axis, already trimmed to whole breaths, with the detected breath boundaries drawn on top. A crosshair read-out reports the value under the cursor. Below the traces sit a Campbell (pressure–volume) diagram and a per-breath table of the computed metrics, so you can see the loop and the numbers change together.

Excluding a breath. Every detected breath is numbered on the traces. Click a breath to toggle it in or out of the analysis; excluded breaths are shaded out. This is your main QC lever: drop a cough, a swallow, a movement artefact or a mis-segmented boundary and every downstream average updates immediately.

A QC overview strip summarises the file at a glance — for example QC: 14 breaths used, 2 excluded — followed by any warning flags (such as vt≤0 or wobtotal NaN) or · no flags when the file is clean. Two buttons let you act on the single file without leaving Preview: Export Campbell… saves the current loop as an image, and Process & write this file runs and writes just this recording so you can inspect one full output before committing the batch.

Mechanics — Advanced settings

Only the handful of controls anyone reaches for sit on the tab itself; everything that shapes segmentation, work-of-breathing and volume conditioning lives behind the Advanced… button. Edits in the modal are staged — nothing reaches the analysis (and nothing recomputes) until you click OK, and OK without a change neither dirties the file nor triggers a recompute.

EMG — ECG reduction

Raw diaphragm EMG is uncalibrated (a.u.) and, on chest recordings, contaminated by the heartbeat. The › EMG – ECG reduction tab removes that cardiac artefact by detecting each R-wave on one capture channel, averaging a heartbeat template, and subtracting it from every EMG channel. It is the first EMG conditioning stage and the prerequisite for the two features that follow.

Workflow. Pick the Capture channel — the one with the clearest heartbeat and weakest EMG, often the middle electrode. Optionally click Auto-suggest settings to analyse the raw EMG and fill the channel, height, gap, width and template automatically. Then tick Remove ECG and adjust Min height and Min gap while watching the detected-peak markers (▼) on the capture-channel plot; the ECG-processed channels render underneath so you can confirm the heartbeat is gone without eroding the EMG bursts.

Min gap is the refractory gap between beats, and it doubles as a ceiling: it implies the maximum heart rate the detector can resolve. On fast (exercise) files, lower it so real beats are not merged or missed.

RespMech reports a suppression figure per file — the drop in peak-window RMS around each R-peak, before versus after:

EMG — noise reduction

The › EMG – noise reduction tab is the second conditioning stage: it subtracts a shared spectral noise profile — built once from a rest reference and applied identically to every file — from every EMG channel. It removes a stationary broadband/electrical noise floor while preserving the true EMG band (roughly 20–250 Hz).

Workflow. Click Set noise profile to choose the rest reference. In that dialog you either tick Use the whole expiration of this recording — recommended, because every expiratory phase is diaphragm-quiet and yields a far more stable estimate (hundreds of STFT frames rather than a handful) — or untick it and drag a quiet rest span yourself. Then tick Reduce EMG noise. Leave Auto on — beside the on/off toggle and the reference picker it is the only noise control left on the strip. The fidelity target moved into Advanced… ▸ Noise suppression ▸ Fidelity target (Keep ≥); with Auto on, the app then picks, once per test, the strongest suppression that keeps every channel at or above that target. The Noise fidelity frontier (1 = untouched) panel plots one fidelity curve per EMG channel against suppression strength, with your target as a dotted horizontal line and the strength Auto chose as a dashed vertical one, so the chosen point is visible.

The reference itself is stored, not typed — the Set-noise-profile dialog writes processing.emg.noise.reference_file, processing.emg.noise.reference_intervals and processing.emg.noise.use_expiration for you. The gate builds its per-frequency threshold as:

Cardiac-gated peak (in this tab’s Advanced… modal)

Even after template subtraction, the plain maximum RMS of a breath often lands on a residual heartbeat rather than the diaphragm. Open Advanced… on this tab and tick Add gated-peak columns, under Gated peak (saved output) — available only when Remove ECG is on. It measures each breath's peak from only the heartbeat-free stretches: it blanks a window around every detected R-peak and takes the maximum of what survives. Set Blanked around each heartbeat to cover the heartbeat's footprint in the RMS envelope. It is output-only — it adds columns to the saved data and changes nothing you can see on this tab, which is why it sits behind Advanced… rather than on the strip.

EMG — Advanced settings

The Advanced… button on the noise tab holds the spectral-gate internals, the RMS/normalisation settings that define the reported EMG number, and the gated-peak quality guards. A live read-out shows what each STFT sample count means in milliseconds at the current sampling rate — 256 samples is a different duration at 1000 versus 2000 Hz.

The RMS window length defines every reported EMG amplitude. Each breath reports the largest value of a sliding-window RMS:

The Analysis menu

Which analysis is open is a window-level concern, so New / Open / Save live in the header Analysis menu and are reachable from every tab. An analysis is one settings file holding every knob for one batch of recordings.

The menu offers New analysis, Open analysis…, Save, Save as…, Get started… (re-opens the start chooser), Explore with sample data (loads the built-in sample again at any time), Duplicate for another recordings folder…, and up to five recent analyses as one-click entries.

Duplicate for another recordings folder… keeps your settings, asks for a new recordings folder, suggests a sibling output folder you can edit, clears the ECG reference file (it could only ever name a file in the old folder) and opens Save as… so the copy is written to a new file rather than over the template. It is the intended route for the next subject in a multi-subject study, and the intended way to turn a tuned sample analysis into a real one.

Opening a legacy 1.x .py settings file runs the migrator and shows a copyable migration report. The window title names the open analysis and marks unsaved edits with * (modified); switching away with unsaved changes prompts Save / Discard / Cancel first. The same commands also sit in the menu bar's File menu, which adds Open Recent, Open output folder and Close Window (Ctrl+W); View switches tabs (Ctrl+1 Setup, Ctrl+2 Preview & QC) and Help opens the documentation, the website, the issue tracker and the offline About box. Shortcuts: Ctrl+N, Ctrl+O, Ctrl+S, Ctrl+Shift+S. On macOS the menu bar is merged into the system menu bar and About RespMech moves into the application menu. The header Analysis button locks during a batch run; the same commands remain reachable from the File menu and its shortcuts, so avoid opening or creating an analysis while a run is in flight.

Because Preview recomputes live, this is the natural loop: open or switch an analysis, tune on one representative file until the QC strip is clean and the conditioning looks right, save, then move to Run & results to process the whole batch with exactly these settings.

respmech run settings.toml

The same analysis file drives the headless CLI, so anything you tune here reproduces identically in a scripted batch.

The app — Run & results

Run & results is a collapsible drawer under Preview & QC's file list, not a screen you navigate to — so you can dry-run, run and read the run report without leaving the file you are looking at, and starting a run opens it for you. It processes every recording in the batch — applying exactly the settings you tuned — and writes the workbooks, diagnostic figures and provenance files to your output folder. Everything runs on a background worker thread, so the log updates live and the window never freezes. The drawer is always reachable; it is the Run batch button alone that waits for a valid setup, and it names what is missing.

Because the real workflow loops rather than runs once, you will often return here after adjusting a parameter — the results row for any file drills back into Preview & QC on a double-click, so tune → re-run is a single continuous cycle.

Run batch vs. Dry run

Two buttons start a run:

• Run batch — processes every matching recording and writes all enabled outputs to the output folder (workbooks under data/, diagnostic PDFs under diagnostics/, and the provenance files at the top).
• Dry run (no files written) — runs the identical computation but writes nothing to disk. Use it to confirm the batch computes cleanly, check breath counts per file, and read the pre-flight plan before you commit any files.

Both buttons are disabled while the setup is incomplete: the status line reads “Setup incomplete: …”, the summary above the buttons lists the reason as a full sentence, and each button's tooltip repeats it. They are disabled the same way while a run is already in flight. When a run starts, Cancel becomes active. Setup's controls grey out and the header Analysis menu locks, so the settings cannot change underneath the running batch; on Preview & QC the two write actions lock too, so clicking a breath answers “Breath selection is locked while a run is in progress.” and “Process & write this file” greys out with the tooltip “Locked while a run is in progress.” Browsing, zooming and switching files stay available throughout.

Pre-flight plan & overwrite guard

Every run — real or dry — logs a pre-flight plan first, so a run is never a black box. The plan names the mode, lists every input file that matched, and lists every output file that will (real run) or would (dry run) be written:

── RUN — writing output. ──
Input:  3 files matching '*.csv' in /study/input
    • P03_120W.csv
    • P03_rest.csv
    • P07_120W.csv
Grouping: 3 files → 2 groups · P03 (2) · P07 (1)
Output: Will write up to 29 files into /study/output:
    • data/P03_120W.csv.breathdata.xlsx
    • …
    • data/Average breathdata.xlsx
    • data/Cohort summary.xlsx
    • diagnostics/P03_120W.csv – Campbell (average).pdf
    • …
    • diagnostics/All files – Campbell (average).pdf
    • run-report.txt
    • analysis-used.toml

The planned list is built from your Setup output tickboxes, in this order: a per-file <file>.breathdata.xlsx when the breath-by-breath workbook is on, a <file> – Processed data.csv when the processed CSV is on, Average breathdata.xlsx together with Cohort summary.xlsx when the average workbook is on, every diagnostic figure the ticked figure boxes imply (including the cohort-wide All files – Campbell (average).pdf, which follows the “Campbell / PV diagram — individual breaths” box and only for a batch of more than one file), any EMG WAV exports, and finally run-report.txt and analysis-used.toml, which are always emitted. The Grouping line is shown only when the average workbook is on. The count is a ceiling (“up to N”), not a promise: a file can fail, and some figures depend on the data (the volume-trend figure is only drawn when trend correction actually finds anchors; EMG stage figures need the stage to have been computed). Up to ten input files every path is listed; beyond that the log summarises the plan by category and Show full output plan… opens the complete list.

Progress & live log

While the batch computes, the progress bar fills once across the whole batch and the status line reads e.g. “File 2 of 12 — P03_120W.csv: breath 14/22”. Once the analysis is done and writing starts, Cancel greys out (writing cannot be interrupted) and the status line ticks “Writing output… 23s, cannot be interrupted” and then “Writing diagnostic figures — 3 of 12 files (P03_120W.csv) · 1m 04s elapsed · ~40s left”. The scrolling log records each file starting, each processing stage, and a per-file done line, then a summary (Finished: N ok, M failed, the chosen noise prop_decrease against its fidelity target, each failed file, and each file's breath count and ECG suppression), and finally what was written by category.

The status line reports the outcome distinctly. Besides the ordinary “Finished: N ok, M failed — wrote K files to <folder> in <time>.” and “Dry run complete — nothing written.”, you may see:

• No file processed — “Finished — no file could be processed; nothing usable was written.” The batch ran to the end but every file failed; open the error log for the reason per file.
• Cancelled — “Run cancelled — no output written.”
• Cancelled too late — “Finished writing; the cancel arrived after the analysis, so the output is complete.” The write phase cannot be interrupted; a cancel that lands inside it is acknowledged, not obeyed.
• Write failed — “Analysis complete, but writing failed — …” The numbers computed correctly; only the file write failed (e.g. a permissions or disk problem on the output folder).
• Run failed — “Run failed — …” The batch stopped before completing.

Cancelling leaves earlier results untouched, with one exception: if you ticked “Clear previous results first” in the overwrite prompt, everything then in the output folder's data/ and diagnostics/ subfolders was already deleted before the run started.

If any individual file fails, or the run fails outright, a separate copyable error-log window opens with the full detail for each failed file, so you can paste it into a bug report or a note to a colleague.

Results: per-file & averaged tables

On completion, each recording's outcome is marked on the shared file list and the averaged metrics fill in below.

Per-file outcomes live on the file list, not in a separate results table. Each row carries a glyph — ✓ processed, ✗ failed, • not yet run — plus a [N excl] badge when breaths were manually excluded, marked ↺ when those exclusions were carried over from a different recordings folder. Hovering a row gives the breath count, or the full error for a failed file. Selecting a row opens that recording in Preview & QC, which is where you were already looking. One list, filterable and sortable: a single failed file in a 25-file batch never means scrolling past every success to find it.

The averaged-metrics table below it shows the across-breath average — one row per recording, each cell the mean over that file's non-excluded breaths. It is the on-screen view of Average breathdata.xlsx, carrying the same mechanics, work-of-breathing, EMG and entropy columns in their native units — pressures in cmH₂O, tidal volume in L, flows in L·s⁻¹, work of breathing in J·min⁻¹, pressure–time products in cmH₂O·s·min⁻¹, and EMG amplitudes in a.u. (uncalibrated). Excluded breaths never enter these means.

Open output folder & Re-run failed

A summary line above the buttons states the file count, the planned output count and any blocking reason. Eight buttons act on the run:

• Run batch, Dry run (no files written) and Cancel — described above.
• Open output folder — opens the output folder in your system file browser. It is enabled only after a real write run has completed cleanly (a dry run writes nothing, so it stays disabled).
• Re-run failed — re-processes only the files that failed in the last run, in the same mode (write or dry) as that run. It is enabled only when the previous run had failures. Use it after fixing the cause — a corrupt file, a wrong channel map — without re-processing the whole batch.
• Show full output plan… — opens the complete pre-flight plan when it was too long to log in full.
• Write results to another folder… — available when the analysis finished but writing its results failed; writes the same, already-computed results to a folder you choose, with no re-analysis. The one recovery path after a failed write.
• Show run report — available once a run has written its own run-report.txt; opens it in a plain-English, copyable window.

Keyboard shortcuts

The desktop app's most-used actions have keyboard shortcuts, gathered here in one place:

Running headless (CLI)

The Run & results drawer mirrors the command-line batch runner, which is handy for scripted or server-side processing. Given a saved analysis (a .toml settings file):

respmech run settings.toml

processes the batch and writes all enabled outputs, printing Wrote N file(s) to <output.folder>/data. Add --dry-run to compute without writing anything: it prints the same output plan the desktop app's Dry run button shows (one line per output category with its file count and destination folder, plus a total), then one <file>: <N> breaths line per file. Unlike the app, the CLI's plan does not list the individual matched input files or the full list of output paths:

respmech run settings.toml --dry-run

A non-zero exit code from run means one or more files failed; the failures are listed on standard error — the CLI equivalent of the Re-run failed list and the error-log window.

Command line & scripting

RespMech is driven by a plain-text settings file (TOML) and a small command-line tool, respmech, with three subcommands: run (process a batch), validate (check the settings and count the input files), and migrate (convert a legacy v1 .py settings file to TOML). Batch processing is first-class and scriptable — you never edit Python to launch a run — and respmech run returns a non-zero exit code if any file fails, so it drops cleanly into shell scripts and CI. The same settings file also underpins the desktop app, so anything you build on the command line opens unchanged in the GUI and vice versa.

Installing the CLI

RespMech requires Python 3.11 or newer (the loader uses the standard-library tomllib). Install from PyPI:

pip install respmech             # CLI + analysis engine
pip install "respmech[emg]"      # + spectral EMG noise reduction (librosa)
pip install "respmech[plots]"    # + diagnostic PDF figures (matplotlib)
respmech --version               # prints: respmech <version>

The base install computes every numeric result and writes the Excel/CSV workbooks. The two extras are only needed for optional stages: [emg] enables spectral EMG noise reduction (processing.emg.noise.enabled = true), and [plots] enables the diagnostic PDF figures (the Campbell diagrams, raw/trimmed/drift overviews, EMG overviews).

The three commands

A subcommand is always required. Run respmech --help or respmech <cmd> --help for the argparse usage summary.

The recommended end-to-end sequence is: migrate (if you have a legacy file), validate, dry-run, then a real run.

respmech migrate old_settings.py -o settings.toml   # 1. convert legacy .py → TOML
respmech validate settings.toml                      # 2. check settings + file count
respmech run settings.toml --dry-run                 # 3. compute, write nothing
respmech run settings.toml                           # 4. process + write workbooks

A real run writes into output.folder: data/Average breathdata.xlsx, one data/<file>.breathdata.xlsx per input, an optional data/<file> – Processed data.csv, data/Cohort summary.xlsx, plus a run-report.txt and an analysis-used.toml in the folder root. The data/ subfolder is created automatically.

Exit codes for scripting

Every command returns a POSIX exit code so RespMech composes with shell scripts and CI pipelines. There are three, and codes 1 and 2 differ in kind — a script that only tests != 0 conflates them.

The settings file (TOML)

A settings file has a top-level schema_version tag and nested tables under [input], [processing], and [output]. The structural keys the run depends on — where to read, what the columns mean, and where to write — live in [input] and [output]; the processing depth (mechanics, EMG, PTP) is documented in its own sections and shown in the annotated example below.

Two conventions worth remembering

An annotated settings.toml

A realistic file covering the common keys. Comments explain each block; defaults are shown so you can see what you are (or are not) overriding. Note the use of a TOML literal string (single quotes) for the regex so backslashes are not escaped.

schema_version = 2

[input]
folder = "input"            # recordings to analyse; relative → resolved against THIS file's folder
files  = "RIU_*.txt"        # case-insensitive glob; may carry a subfolder, e.g. "raw/*.csv"

[input.format]
sampling_frequency = 2000   # Hz — REQUIRED, integer; every time window is derived from this
matlab_variant     = "mac"  # "windows" | "mac"; only affects .mat inputs
decimal            = "."    # use "," for European-locale text/CSV

[input.channels]            # 1-based column numbers (LabChart convention);
                            # column 1 is the time axis, so signals start at 2
flow    = 2                 # REQUIRED
volume  = 3                 # REQUIRED unless processing.volume.integrate_from_flow = true
poes    = 4                 # REQUIRED — oesophageal pressure
pgas    = 5                 # REQUIRED — gastric pressure
pdi     = 6                 # REQUIRED — transdiaphragmatic pressure
emg     = [7, 8, 9]         # EMG channels; [] disables all EMG processing
entropy = [7, 8, 9]         # sample-entropy channels; [] disables entropy

[processing.segmentation]
method = "flow"             # "flow" | "volume" — which signal detects breath boundaries
buffer = 800                # samples averaged for cycle detection (scale with fs)

[processing.segmentation.peak]
height     = 0.1            # min peak height, in the segmentation signal's units
distance_s = 0.1            # s — min time between peaks
width_s    = 0.5            # s — min peak width

[processing.volume]
integrate_from_flow = false # true → derive volume from flow (volume channel becomes optional)
correct_drift       = true  # remove slow baseline drift (ON by default)
correct_trend       = false # also remove a between-breath trend in end-expiratory volume
trend_method        = "linear"  # scipy interp1d kind for the trend envelope
trend_peak_min_prominence_frac = 0.05  # trough depth to anchor on, as a fraction of
                                       # THIS recording's volume range (scale-free)
trend_peak_min_distance_s      = 0.4   # s — min time between two anchors
# trend_peak_min_height        = 0.8   # legacy ABSOLUTE depth below the recording's
                                       # highest volume. Omit it (recommended): a fixed
                                       # value larger than the volume range finds no
                                       # troughs and the correction cannot run.

[processing.wob]
calc_from          = "average"  # "average" (classic Campbell) | "individual" (per breath)
avg_resampling_obs = 500        # samples each phase is resampled to for P–V averaging (~ fs ÷ 8–10)

[processing.emg]
rms_window_s  = 0.050            # s — sliding RMS window (effective length fs·rms_window_s − 1 samples, trailing, not centred)
remove_ecg    = false           # subtract cardiac contamination before RMS
detect_channel = 0              # 0-based INDEX into the emg list above (not a column number)
normalization = "per_file_max"  # "none" | "per_file_max" | "per_file_mean" (adds a normalised sheet)

[processing.emg.noise]
enabled = false                 # spectral STFT noise reduction; needs the [emg] extra (librosa)

[processing.ptp]
baseline_window_s = 0.05        # s — window whose mean is the pressure–time-product baseline

# --- Per-file overrides (zero or more of each) ---
[[processing.exclude_breaths]]
file    = "RIU_H1_120W.txt"
breaths = [1, 2]                # 1-based breath numbers; always dropped from averages/workbooks

[[processing.breath_counts]]
file  = "RIU_H1_120W.txt"
count = 12                      # override the auto-detected breath count for this file

[output]
folder      = "output"          # workbooks land in <folder>/data
group_regex = '^(P\d+)'         # first capture group = cohort key; omit → leading filename token

[output.data]
save_average          = true
save_breath_by_breath = true
save_processed        = false   # large per-file processed-signal CSV; off by default

[output.diagnostics]
save_pv_average = true          # averaged Campbell diagram; needs the [plots] extra
save_emg        = true          # per-channel EMG overviews (raw / ECG-removed / noise-reduced)

Migrating a legacy .py

RespMech v1 configured runs by editing a Python .py file that assigned a settings = {…} dictionary. respmech migrate converts one to a v2 TOML:

respmech migrate old_settings.py -o settings.toml

Migration does three things and reports each under its own heading: it prints Wrote <path>, then a report with Mapped (keys renamed / re-homed), Normalised (genuine legacy bugs fixed), and Dropped (keys that were defined but never actually read by the v1 code). Representative renames:

• input.inputfolder → input.folder; output.outputfolder → output.folder
• input.data.column_* → input.channels.*
• format.matlabfileformat (1|2) → matlab_variant ("windows"|"mac"); format.samplingfrequency → sampling_frequency
• mechanics.separateby → segmentation.method; breathseparationbuffer → segmentation.buffer
• emg.rms_s → emg.rms_window_s; emg.column_detect → emg.detect_channel; emg.windowsize → emg.ecg_window_s
• excludebreaths and breathcounts (lists of pairs) → the [[processing.exclude_breaths]] / [[processing.breath_counts]] tables

Two normalisations fix silent v1 bugs. First, calcwobfromaverage / avgresamplingobs were read by the code under wob.* but placed under [mechanics] in the example files, so they were quietly ignored — the migrator maps them to wob.calc_from / wob.avg_resampling_obs where they take effect. Second, the legacy per-file noise profiles are consolidated into one shared processing.emg.noise profile with a fixed n_fft = 256, dropping the old n_fft = len(noise)**2 bug.

Breath segmentation & volume

Before any mechanics are computed, RespMech turns a raw recording into a clean sequence of whole breaths. It trims the record so it starts and ends on breath boundaries, conditions the volume trace (zeroing, drift and optional trend removal), and then walks the signal to mark where each breath begins and ends. This page covers those steps, the settings that control them, and how you drop individual breaths or override the breath count used for per-minute scaling. Every step here runs on the signed, conditioned signals and assumes RespMech's two sign conventions: inspiration reads negative flow, and inspired volume is positive.

Trimming to whole breaths

A recording almost never starts and ends exactly on a breath boundary. RespMech discards the leading partial expiration and the trailing partial inspiration so the analysis window contains only complete breaths. It finds the first inspiration onset and the last end of expiration in the flow signal, then slices every channel (flow, volume, all pressures, EMG, entropy) to that window so they stay sample-aligned.

This imposes a precondition on the raw file: it must start in late expiration and end in early inspiration. If the flow signal never crosses zero — or the computed window is empty — RespMech raises a TrimError that names the flow channel and the inverse_flow setting, because a wrong flow sign is by far the most common cause.

Splitting the record into breaths

Once trimmed, the record is divided into individual breaths. A breath is always one inspiration plus the expiration that follows it. RespMech offers two detection methods — flow (the robust default) and volume (for noisy flow with clean volume peaks) — selected by processing.segmentation.method.

By flow (default)

Walking the trimmed signal, an inspiration is the run where flow is negative, and the following expiration is the run where flow is positive. To stop brief zero-crossing wobble from chopping one breath into several, a phase is allowed to continue as long as the forward mean of flow over the next buffer samples keeps the phase's sign:

By volume

With method = "volume", RespMech instead runs scipy.signal.find_peaks on the inspired volume to locate end-inspiration, and on the inverted volume to locate end-expiration. Detection is gated by three thresholds — a minimum peak height (in litres), a minimum time between peaks and a minimum peak width (both in seconds, converted internally to seconds · fs samples). This method relies entirely on the peak.* settings and usually needs tuning per recording; the flow method needs only the buffer.

Volume: reading it or integrating from flow

Volume can come from a recorded channel or, when none exists, be derived by integrating flow. With integrate_from_flow on, RespMech computes the negative cumulative trapezoidal integral of flow using the file's true sampling rate (even when pre-analysis resampling is active), so the sign convention "inspired volume positive" holds:

Sign flips are applied at load time in a fixed order: invert flow (if set) → integrate volume from flow (if no volume channel) → invert volume (if set). Because inversion of flow happens first, it also flips the sign of any flow-derived volume. At analysis time the volume trace is then zeroed to its first sample before drift and trend correction:

Drift and end-expiratory trend correction

Integrated and thermally-sensitive volume traces wander over time. RespMech applies up to two corrections to the zeroed volume, in order: a linear drift removal (on by default) and an optional between-breath trend removal.

Linear drift correction

correct_drift removes a straight-line baseline slope. It measures the slope from the first and last samples and subtracts a matching ramp, which leaves the very last sample pinned at zero — a deliberate boundary behaviour preserved for byte-for-byte reproducibility of the validated reference results:

End-expiratory trend correction

When the operating volume itself wanders across a run (for example during exercise, as end-expiratory lung volume shifts), a single straight line is not enough. correct_trend detects the end-expiratory points breath by breath, interpolates an envelope through them, and subtracts it so every breath is referenced to a common end-expiratory level.

A sample anchors the envelope when it is a local minimum of the volume, is at least trend_peak_min_distance_s from the previous anchor, and is deep enough: its prominence — the smaller of the two inspiratory excursions on either side of it, which for a normal breath is about one tidal volume — must be at least trend_peak_min_prominence_frac of the recording's own volume range. Because the threshold is a fraction of that range rather than a fixed number of litres, the same setting works for quiet tidal breathing and for maximal exercise, and in any volume unit. The recording's own first and last samples are considered as anchors too — an edge is never a local maximum, so the peak search can never return one, and including them stops the envelope extrapolating past the outermost detected trough. They are accepted only when they really sit at an end-expiratory level: trimming ends the window at the last sample where flow is still outward, which is in expiration rather than at end-expiration, so a recording stopped mid-breath has an end part way up a breath. Anchoring there would invent a trend and distort that breath, so such an end is dropped.

All of these live under Preview & QC → Mechanics → Advanced…, where the dialog also reports how many troughs the current settings find in the previewed file. If a recording yields too few anchors for the chosen interpolation, RespMech stops on that file and says so, rather than writing numbers derived from an undefined envelope.

Optional pre-analysis resampling

When you switch it on, RespMech brings every loaded channel — the 1-D signals and the 2-D EMG/entropy matrices — onto one common sample rate before trimming, segmentation and compute. It uses anti-aliased polyphase resampling, with the up/down ratio reduced to lowest terms:

The file is always loaded at its true rate first — so flow-to-volume integration still uses the real sampling frequency — and only then resampled; all downstream computation, including the shared EMG-noise profile, runs at the new rate. Keeping a single common rate preserves one time base, so flow-based segmentation and the sample-indexed EMG stay consistent. The EMG-noise STFT window is auto-scaled to preserve its time extent at the new rate.

Excluding breaths & breath-count overrides

Two related controls let you clean up the averages and correct per-minute scaling. They serve different purposes and are easy to confuse.

Excluding breaths

exclude_breaths marks named breaths in a named file as ignored: they remain drawn and numbered in the diagnostic plots but are dropped from the per-file average and per-breath workbooks. In the desktop app you exclude a breath by clicking its shaded region in the Mechanics preview (it turns red, as in the figure above under Splitting the record into breaths). Use it to drop swallows, coughs, sighs and other artefactual breaths. Excluded breaths appear in the processed-signal CSV only when output.data.include_ignored_breaths is on.

Breath-count overrides & per-minute scaling

Every per-minute quantity is scaled by a factor derived from the file's trimmed duration and the breath count:

By default count is the number of detected breaths — and that count includes breaths you marked as ignored. If you exclude breaths and care about absolute per-minute values (bf, VE, and the breaths·min⁻¹ factor on every PTP and WOB), set breath_counts to the true number of breaths in the epoch. It changes only the scaling factor, not which breaths are averaged.

respmech validate settings.toml
respmech run settings.toml

Respiratory mechanics

For every breath it detects, RespMech computes the classic respiratory-mechanics descriptors: breath timing (inspiratory time, expiratory time, total cycle time and the duty cycle), tidal volume, breathing frequency and minute ventilation, plus a full set of oesophageal (Poes), gastric (Pgas) and transdiaphragmatic (Pdi) pressure descriptors. From these it derives the pressure–time products (PTP), an isovolume inspiratory lung-resistance estimate (tlr_insp) and a gastric/oesophageal pressure ratio (vmr). Results are reported breath-by-breath and as a per-file average, each number carried with its physical unit. The defaults reproduce the validated reference pipeline; the PTP columns differ from 1.x by the documented baseline change (see Changes from RespMech 1.x).

How a breath is defined

Everything on this page is computed on the signed, trimmed and conditioned signals. A single breath is one inspiration followed by the next expiration. The recording is first trimmed to whole breaths — the first sample where flow goes negative (onset of the first inspiration) to the last sample where flow is still positive (end of the last expiration) — so, provided the export window brackets whole breaths, the analysis begins and ends on a phase boundary.

Breath timing

Timing is read straight off the sample counts of each phase. With n_insp, n_exp and n_total the number of samples in the inspiratory phase, the expiratory phase and the whole breath:

The duty cycle Ti/Ttot is the fraction of the cycle spent inspiring: the timing component of the classical drive-and-timing decomposition of ventilation, V̇E = (VT/Ti) × (Ti/Ttot), i.e. mean inspiratory flow scaled by the duty cycle (× 60 for the L·min⁻¹ RespMech reports), whose other factor VT/Ti (available from the vt and ti columns) is the drive component (Milic-Emili & Grunstein, Chest 1976;70:131–133). It is also the timing factor of the diaphragm tension–time index, TTdi = (Pdi/Pdi,max) × (Ti/Ttot) (Bellemare & Grassino, J Appl Physiol Respir Environ Exerc Physiol 1982;53:1190–1195). Because every timing number divides a sample count by fs, an incorrect sampling frequency rescales all of them; confirm fs before you trust any timing output.

Tidal volume, frequency & ventilation

Tidal volume is the peak-to-trough swing of the conditioned volume trace over the breath:

Breathing frequency and minute ventilation are put on a per-minute footing with a single scaling factor derived from the trimmed file duration. With N_trimmed the trimmed flow length and bcnt the number of detected breaths in the file:

Pressures & tidal swings

From the oesophageal, gastric and transdiaphragmatic pressure channels, RespMech reports end-inspiratory, end-expiratory, maximum and minimum values, the mid-tidal-volume Poes points, and the phase rises and whole-breath tidal swings. Pdi is read as a supplied channel (Pdi = Pgas − Poes on the acquisition system); RespMech does not recompute it. All are in cmH₂O.

The mid-tidal-volume points (poes_midvolinsp, poes_midvolexp, and the matching flows) are sampled where each phase reaches half its tidal volume; they feed the isovolume resistance estimate below. See the full list in the output columns.

Pressure–time products (PTP)

The pressure–time product measures the area under a phase's pressure trace relative to a baseline at the phase start — the standard surrogate for respiratory-muscle energy expenditure that work of breathing (which needs volume) cannot capture during, for example, ineffective efforts. RespMech computes three: inspiratory oesophageal, inspiratory transdiaphragmatic and expiratory gastric.

For a phase pressure signal p, the baseline is the mean of a short window at the phase start (end-expiratory for the inspiratory phases), the signal is shifted onto that baseline, and the area is integrated over time with Simpson's rule:

The integral is signed: any part of the phase where the shifted pressure lies below the baseline is subtracted, not clipped. For the inspiratory Poes and Pdi products this rarely matters, but the expiratory gastric product is referenced to Pgas at the start of expiration, so a passive expiration in which Pgas falls back towards its end-expiratory level gives a negative int_pgasexp / ptp_pgasexp; it turns positive only when expiratory abdominal recruitment holds Pgas above its end-inspiratory level. A negative value is a finding about the breath, not an error.

• int_oesinsp / ptp_oesinsp — from −Poes over inspiration (Poes is negated so inspiratory effort is positive).
• int_pdiinsp / ptp_pdiinsp — from Pdi over inspiration.
• int_pgasexp / ptp_pgasexp — from Pgas over expiration.

Resistance & the gastric/oesophageal ratio

Lung resistance is estimated by the isovolume method (Mead & Whittenberger, J Appl Physiol 1953;5:779–96): the change in oesophageal pressure divided by the change in flow between the inspiratory and expiratory points at the same lung volume, so that the elastic recoil term cancels:

The gastric/oesophageal pressure ratio compares the end-tidal gastric swing to the end-tidal oesophageal swing — an index of the abdominal versus pleural pressure contribution to the breath:

A division by zero in vmr is guarded and returns 0.

Settings this section uses

The pressure descriptors come directly from the channels you assign to Poes, Pgas and Pdi; the time base, the PTP baseline and the per-minute scaling are governed by the settings below. Breath detection and volume conditioning are covered under signal conditioning.

Assign channels and set the sampling frequency on the Setup screen; tune the PTP baseline and breath-count overrides in the Preview & QC advanced panel. Then run the batch:

respmech run settings.toml

Output columns — respiratory mechanics

The per-breath table (<file>.breathdata, Data sheet) and the per-file Average breathdata row carry the columns below, keyed by breath_no (per breath) or file (average row). The same tables also hold work-of-breathing and, when configured, EMG/entropy columns, which are documented in their own sections.

Work of breathing & the Campbell diagram

Work of breathing (WOB) is the mechanical work the respiratory muscles perform to move air in and out of the lungs. RespMech quantifies it the classic way — from a Campbell diagram, a loop of oesophageal pressure (Poes, cmH₂O) plotted against lung volume (Volume, L) over a breath, the pressure–volume framework set out by Otis, Fenn & Rahn (1950) and Campbell (1958) — see References › Respiratory mechanics. The inspiratory work is the area between the inspiratory pressure trace and the end-expiratory pressure level, computed as ∫ P dV; the elastic-recoil line joining EELV and EILV splits it into an elastic triangle and a resistive bulge, and any expiratory pressure above the end-expiratory level adds expiratory work. RespMech reports these three components as a per-minute power in J·min⁻¹.

WOB is the most conditioning-sensitive number in the pipeline: it depends entirely on a correctly signed, drift-corrected Poes and Volume signal. Get the sign conventions or drift correction wrong and RespMech will still produce a WOB number — just a wrong one, with no error. See Conventions & gotchas before trusting any value.

The Campbell diagram

Each breath is reduced to two endpoints on the pressure–volume plane:

• EELV — the end-expiratory lung volume point [V_endexp, Poes_endexp] (last sample of expiration), the relaxed baseline.
• EILV — the end-inspiratory lung volume point [V_endinsp, Poes_endinsp] (last sample of inspiration), the top of the tidal excursion.

The straight line joining these two zero-flow points is the lung's elastic-recoil line: at zero flow the alveolar pressure is atmospheric, so Poes equals minus the elastic recoil pressure of the lung, and the chord is that breath's dynamic lung-compliance line. It is the pressure the lung alone would demand at each volume if there were no flow resistance. The bulge of the real inspiratory Poes trace beyond this line is resistive work; the triangle bounded by the line, the constant-Poes level through EELV and the end-inspiratory volume is the elastic work RespMech reports.

The three work components

Every area starts as a pressure×volume quantity in cmH₂O·L and is multiplied by the unit-change factor (see below) to become Joules per breath.

1. Inspiratory elastic WOB (wob_in_ela) — the triangle between EELV, EILV and the recoil line: the energy stored stretching the lung over the tidal volume (equivalently ½·VT²/C_L,dyn). The chest wall is not included — see the note below.

2. Inspiratory resistive WOB (wob_in_res) — the area between the inspiratory Poes trace and a straight line fitted between the first and last inspiratory samples. This is not quite the recoil line drawn in the figure above: the figure's line starts at the breath's own end-expiratory point (EELV), while the line used here starts wherever that breath's inspiration begins, which is the end of the previous breath's expiration. The two coincide only when end-expiratory volume and pressure are stable from breath to breath; its intercept is also taken at V = 0 rather than at the inspiration's own starting volume (an inherited 1.x quirk), so on a breath whose inspiration does not start at V = 0 — for example because end-expiratory volume wanders between breaths — wob_in_res is shifted by an amount with no physiological meaning. Keep processing.volume.correct_drift on, and enable processing.volume.correct_trend when EELV wanders, so that every breath starts at V = 0. Only the positive (effort) part of the excess is kept, and it is integrated over volume with Simpson's rule.

3. Expiratory WOB (wob_ex_total) — the expiratory Poes rising above the end-expiratory level, positive part integrated over volume: active expiratory effort or expiratory resistance above the relaxed baseline.

The totals then combine:

From cmH₂O·L to J·min⁻¹

Two conversions turn a raw loop area into the reported number.

Pressure×volume to Joules. Since 1 cmH₂O = 98.0638 Pa, 1 L = 10⁻³ m³, and Pa·m³ = J:

Per breath to per minute. Each per-breath Joule quantity is then scaled to a per-minute rate by the breathing frequency, so the reported value is "the work of this breath sustained for one minute":

Here bcnt · vefactor is the breathing frequency in min⁻¹ (breath count over the file duration, scaled to 60 s).

Output columns — work of breathing

All five WOB columns appear in both the Average breath-data workbook and the per-file breath-by-breath workbook. Units are attached automatically (any column beginning wob is J·min⁻¹) and are not baked into the column names.

• wobtotal — total work of breathing (inspiratory + expiratory). J·min⁻¹ ⚠ Differs from 1.x (Simpson rule change, negligible)
• wob_in_total — total inspiratory WOB (wob_in_ela + wob_in_res). J·min⁻¹ ⚠ Differs from 1.x (Simpson rule change, negligible)
• wob_ex_total — expiratory WOB. J·min⁻¹ ⚠ Differs from 1.x (Simpson rule change, negligible)
• wob_in_ela — inspiratory elastic WOB (the recoil triangle). J·min⁻¹ — analytic, no Simpson integration: bit-identical to 1.x.
• wob_in_res — inspiratory resistive WOB (area to the recoil line). J·min⁻¹ ⚠ Differs from 1.x (Simpson rule change, negligible)

Average vs individual breaths

You choose whether WOB — and the Campbell loop it is read from — is measured once from a single averaged breath or breath-by-breath and then averaged. In "average" mode, every non-ignored breath is resampled to avg_resampling_obs points and mean-averaged; the resulting loop is robust to irregular or noisy breaths and is also what the plotted average Campbell figure is drawn from. In "individual" mode, WOB is computed from each breath's own trace, which is more faithful to breath-to-breath variability but sensitive to atypical breaths.

Campbell diagnostic figures

RespMech can render the Campbell loops as diagnostic PDFs into <output>/diagnostics/ — an averaged loop per file with the WOB polygon shaded, and a paginated grid of every breath. Use them to visually confirm the loops look physiological and to spot mis-segmented or atypical breaths worth excluding.

respmech run settings.toml

The batch computes WOB per breath, writes the five WOB columns into the workbooks, and — where the output.diagnostics.* keys are enabled — renders the Campbell PDFs. Use respmech validate settings.toml first to catch invalid values (calc_from must be "average" or "individual"; avg_resampling_obs must be an integer).

Conventions & gotchas

Diaphragm EMG

RespMech turns each EMG channel — typically diaphragm EMG (EMGdi) — into two numbers per breath: the RMS amplitude (the loudest short window of muscle activity) and the integrated EMG (the area under the rectified signal). Both are computed for the whole breath and separately for inspiration and expiration, for every channel, plus the across-channel maximum and mean.

Raw EMG is uncalibrated, so its absolute value carries no physical meaning — only comparisons against the same signal do. Two things follow. First, RespMech can re-express every RMS column as a percentage of that same column's own peak (or mean) value across the file's breaths (see Amplitude normalisation), which removes the electrode- and gain-dependent scale and lets the within-file pattern — breath-to-breath modulation, inspiratory versus expiratory activity — be compared across subjects and electrodes. Because every file's own maximum becomes 100% by construction, this does not on its own make absolute activation levels comparable across files, conditions or subjects — that needs a shared reference (a maximal-manoeuvre file recorded once per subject, or an external calibration), which processing.emg.normalization_reference_file supports (see Amplitude normalisation). Second, any signal conditioning must be applied identically to every file in a test, or the comparison breaks.

RMS and integrated EMG

For each channel the signal is scanned with a sliding window of length L = int(rms_window_s · fs) samples. Each window's root-mean-square is computed, and the breath's reported RMS is the maximum of that rolling value across the phase:

The integrated EMG is the area under the rectified signal over the phase, evaluated by Simpson's rule with time in seconds:

Amplitude normalisation

Because raw amplitude is in a.u., comparing EMGdi across subjects or electrodes requires expressing each file against a reference. When enabled, RespMech re-expresses every RMS column as a percentage:

ref is computed separately for every RMS column: by default, the largest (per_file_max) or the mean (per_file_mean) value of that same column across the file's own kept breaths — so each column, including the inspiratory, expiratory, gated and across-channel columns, reaches 100% in whichever breath that particular column peaks, not necessarily the file's overall peak breath. This is written to a separate EMG normalised sheet — the raw RMS columns are never touched.

Because every file's own maximum becomes 100% by construction, the per-file default does not by itself make amplitudes comparable across files, conditions or subjects — it only makes a column's within-file pattern comparable. Set processing.emg.normalization_reference_file to another file already in the batch (typically a maximal inspiratory/expiratory manoeuvre recorded once per subject) to normalise every file's RMS columns against that one file's own reference instead, so a percentage means the same thing across the whole study; the reference file itself still reads 100% at its own peak, and every other file's peak reads below 100% unless it happens to match the manoeuvre. Settings-file only, off by default — existing analyses are unaffected until it is set.

The conditioning pipeline

Two optional stages clean each EMG channel before RMS and integrated EMG are measured, always in this fixed order:

1. ECG removal — subtract an averaged heartbeat template so the cardiac artefact does not inflate the EMG.
2. Spectral noise reduction — subtract a shared spectral noise profile, built once from a rest reference and applied identically to every file.

Both are off by default; with both off, the RMS and integrated EMG are measured on the raw signal and the output is byte-identical to an unconditioned run.

ECG (cardiac artefact) removal

When enabled, ECG removal works in three steps:

1. R-peak detection on the chosen capture channel, using find_peaks with the height, refractory-distance and width guards below. The same heartbeat train is reused for every EMG channel.
2. Averaged template. Windows of half-width ecg_window_s/2 either side of each R-peak (total span ≈ ecg_window_s) are time-aligned within ±0.2 s and averaged into one ECG template per channel.
3. Per-beat subtraction. For each beat the template is time-shifted (±0.2 s) and amplitude-scaled (within ±1.25×) to best fit that beat, then subtracted.

RespMech reports how well this worked as a suppression figure — the peak-window RMS within ±40 ms of each R-peak, before versus after:

Spectral noise reduction

This is stationary spectral gating driven by a fixed per-frequency threshold. The threshold is built once per test from an EMG-free rest reference and applied identically to every file — the same design constraint that governs ECG removal, so the transformation stays comparable across the test.

For each frequency bin the threshold is the mean noise level plus a margin in standard deviations:

To apply it, RespMech STFTs the signal, masks bins that fall below T(f), smooths the mask, and attenuates the masked energy by prop_decrease towards the spectral floor before inverse-STFT.

Two in-band metrics (20–250 Hz, Welch PSD) judge the result. Fidelity is the fraction of true inspiratory EMG power retained — the over-subtraction guard — and the in-band SNR contrasts inspiration against expiration:

With Auto on, RespMech picks — once per test — the strongest prop_decrease on a 0.1–1.0 grid whose worst-channel fidelity still meets the target; if none qualify, it uses the gentlest. Auto measures the fidelity frontier on a capped sample of the test, not on every file: it walks the sorted file list and stops as soon as it has gathered 40,000 inspiratory samples (20 s of inspiration at 2 kHz, 40 s at 1 kHz), which is often the first file alone, and uses the matching expiratory samples as the quiet reference. The strength it picks is then applied identically to every file, so put a representative recording first in the sort order, and check the per-channel fidelity printed in run-report.txt whenever the batch mixes very different signal levels.

Cardiac-gated peak EMG

Even after template subtraction, a residual heartbeat often remains, and the plain RMS maximum tends to land on it rather than on diaphragm activity. The cardiac-gated peak reads the maximum from only the heartbeat-free stretches of each breath: RespMech computes the rolling RMS envelope, blanks ± gate_half_width_s around every detected R-peak, and takes the maximum of what survives — per breath, inspiration and expiration. It reuses the R-peaks that ECG removal already found, so it requires remove_ecg = true.

Losing samples costs nothing here: every breath — and the normalising maximum — undergoes the same blanking, so the loss cancels in the relative measure. When the guards below cannot trust a result, RespMech reports NaN rather than a wrong number.

The detector's ceiling is set entirely by the ECG refractory gap:

RMS outlier handling

An optional filter suppresses a single artefactual breath's RMS from distorting the file average. For each breath RespMech forms the ratio rms_poes = rms_max / poes_mininsp. If a breath's ratio lies more than outlier_rms_sd_limit standard deviations from the mean of the other breaths, its rms_max and rms_mean are replaced with the other breaths' means. It only fires when the limit is above 0.

Output columns — diaphragm EMG

The RMS and integrated-EMG columns appear on the main breath tables for every file. The gated columns are added only when the gated peak is enabled, and the normalised _pct columns live on a separate EMG normalised sheet, added only when normalisation is not none. Neither ever alters the raw RMS.

Sample entropy

Sample entropy (SampEn) is a single dimensionless number that measures how irregular or unpredictable a signal is. A highly repetitive, self-similar trace gives a low value; a noisy, complex trace gives a high value. In RespMech it is most often applied to the diaphragm EMG to quantify the complexity of neural drive breath by breath, but you can compute it on any recorded column you tick as an Entropy channel. It has only two tunable knobs — the template length m (Embedding) and the matching tolerance r (Tolerance) — and both default to conventional values, so most users never touch them.

What it measures

Sample entropy is the negative natural logarithm of the conditional probability that two sub-sequences (templates) which match for m consecutive samples will still match when each is extended by one more sample. In plain terms it asks: when a pattern repeats, how reliably does it keep repeating?

• Low SampEn — the signal is regular and self-repeating; neural drive is rhythmic and stereotyped.
• High SampEn — the signal is irregular and complex; drive is variable or noise-like.

The statistic is dimensionless (reported unit —). EMG amplitude in this pipeline is uncalibrated, but SampEn is a shape/complexity measure, not an amplitude measure: the tolerance is defined relative to the signal's own standard deviation, which cancels the amplitude scale and makes SampEn scale-invariant. That is what lets you compare complexity across breaths, channels and recordings even though the raw EMG has arbitrary units. It does not make every comparison valid, though: sample entropy is also sensitive to sampling frequency (via the number of samples in the segment) and to the choice of m and r, so only compare values computed at the same sampling frequency (and the same resampling setting, if used) and with the same m and r.

How RespMech computes it

For a channel segment x, using the Chebyshev (maximum) norm, RespMech counts template-vector pairs at two lengths and takes:

where B is the number of template pairs that match at the shorter length and A is the number that still match when each template is extended by one sample. Two points count as a match when they differ by less than the tolerance r — that is, |x_j − x_k| < r across every element of the template (the Chebyshev norm takes the largest per-element difference).

The tolerance you enter is a fraction. RespMech converts it to an absolute tolerance separately for each segment it analyses, scaling by that segment's own standard deviation:

SampEn is computed independently for every entropy channel and three times per breath — over the whole breath, over inspiration only, and over expiration only. After the per-channel numbers, RespMech appends the max, min and mean across the entropy channels for each of the three phases.

The statistic follows Richman and Moorman (Am J Physiol Heart Circ Physiol 2000;278:H2039–49, PMID 10843903, doi:10.1152/ajpheart.2000.278.6.H2039), the consistency-corrected successor to Pincus's approximate entropy (Proc Natl Acad Sci USA 1991;88:2297–301, PMID 11607165, doi:10.1073/pnas.88.6.2297). The routine itself is the pyEntropy implementation, vendored into the package and distributed under its own Apache-2.0 licence alongside RespMech's GPL-3.0 — see References › Third-party code.

Parameters

Sample entropy owns the channel-selection role plus two numeric knobs. All three keep conventional defaults, so a typical run only needs you to pick the entropy channel(s).

Assigning entropy channels

In the channel picker, tick the Entropy tickbox on any column you want SampEn for — including a column that already has another role such as EMG. The tooltip reads: "Also compute sample entropy on this column. Independent of the role above — a column can be both."

On the Setup tab a Sample entropy card appears only when at least one column is actually assigned to entropy. It holds the Template length (m + 1) and Tolerance (r), × SD spin boxes plus a hint: "Computed on the columns ticked as Entropy in the channel picker."

To configure it directly in the analysis TOML:

[input.channels]
entropy = [6]          # 1-based column number(s); non-exclusive

[processing.entropy]
epochs = 3             # template length = m + 1 (3 gives m = 2; use 2 for m = 1)
tolerance = 0.1        # Tolerance (r), as a fraction of the channel SD

Then run the analysis:

respmech run settings.toml

Omitting [processing.entropy] uses the defaults; an empty entropy = [] disables entropy entirely.

Output columns — sample entropy

Entropy columns appear only when at least one entropy channel is assigned; otherwise none are written. When present, they appear in both the per-file breath-by-breath sheet and, averaged, in the Average breathdata sheet. All resolve to the dimensionless unit —. Here <c> is the 1-based column number of the entropy channel.

With a single entropy channel the max, min and mean columns all equal the per-channel value; they become useful when you assign several entropy channels and want a one-number summary per phase.

Changes from RespMech 1.x

A controlled comparison between RespMech 1.0.0 and 2.3.2, run without EMG channels, established what changed between the legacy 1.x line and the current 2.x engine, and why. Most of the columns the two versions have in common are bit-identical; the rest differ for three isolated and confirmed causes, each explained below. The affected columns also carry an inline ⚠ note where they are documented (mechanics output columns, WOB output columns, entropy output columns). EMG amplitude columns were outside this comparison — see EMG conditioning below for how they differ when noise reduction is used.

The mechanical core is unchanged

Breath timing (ti, te, ttot, ti_ttot), volumes (vt, vol_endinsp, vol_endexp), ventilation (bf, ve), the pressure descriptors, resistance/ratio outputs (tlr_insp, vmr) and every work-of-breathing component except the Simpson-integrated ones (see below) are bit-identical between 1.x and 2.x. Breath detection, trimming and exclusion also segment the same breaths in both versions. If you are migrating a pipeline from 1.x, these columns need no adjustment at all.

PTP baseline: deliberate, robust form of the same definition

Affects: ptp_oesinsp, ptp_pdiinsp, ptp_pgasexp and the paired integrals int_oesinsp, int_pdiinsp, int_pgasexp (see Pressure–time products).

The PTP baseline changed from a single sample at the phase start to the mean over a short (50 ms) window (processing.ptp.baseline_window_s, default 0.05). This is the robust form of the same definition, not a new one — a single sample sits where the pressure is moving steeply and is noise-sensitive. Old and new PTP values are therefore not directly comparable. Legacy behaviour is exactly reproducible with baseline_window_s = 0.0005 (= 1 sample) if strictly needed, but this is not recommended.

Sample entropy: bug fix, old inspiratory/expiratory values invalid

Affects: sample_entropy_insp_* and sample_entropy_exp_* (including the per-channel sample_entropy_insp_col_<c> / sample_entropy_exp_col_<c> and the _max/_min/_mean reductions), and to a lesser degree sample_entropy_col_<c> (see Sample entropy output columns).

In 1.x the entropy windows were mis-indexed: the entropy matrix was left untrimmed but indexed with trimmed coordinates, so every window was read too early by the recording's trim offset. That offset can amount to a substantial fraction of an inspiration, so the "inspiration" window in practice captured the end of the preceding expiration plus only the start of the inspiration — a phase-mixed window, read using the wrong offset rather than the phase it claims to measure. Consequently the old inspiratory and expiratory values are invalid; how far off a given value is depends on the recording and the size of the trim offset, so there is no fixed direction to the error.

Simpson integration: library drift, not a RespMech change

Affects: int_oesinsp, int_pdiinsp, int_pgasexp, ptp_oesinsp, ptp_pdiinsp, ptp_pgasexp, wob_in_res, wob_ex_total and their sums wob_in_total, wobtotal (see mechanics output columns and WOB output columns), and the integrated-EMG columns integral_emg_col_<n>, integral_emg_insp_col_<n>, integral_emg_exp_col_<n> with their _max/_mean reductions.

SciPy dropped the even='avg' convention (the pre-1.11 default) for an even number of samples. This is not a RespMech change; it is documented only so that anyone failing to reproduce an old spreadsheet bit-exactly knows why. The size of the shift depends on the recording and is not the same for every column — the integrated-EMG columns move more than the pressure–time integrals and the work-of-breathing totals, because their integrand is broadband and noise-like, and wob_in_res/wob_ex_total can move by as much or more on a recording where that component is itself close to zero — so no single bound is quoted here. Run RespMech on SciPy 1.11 or later, the version floor in pyproject.toml, so the numbers match the validated reference. wob_in_ela (analytic area, no Simpson) and the volume/flow columns (trapezoidal) are unaffected.

EMG conditioning: a redesign, not a drift

Affects: rms_* and integral_emg_* (and their per-channel and reduction variants) — but only when EMG noise reduction was used; ECG removal itself is unchanged from 1.x.

RespMech 1.x re-estimated the noise spectrum inside every call and derived the FFT length from the noise clip itself, so the same settings filtered different files differently. 2.x builds one fixed, shared noise profile per test (band-limited, with a fidelity gate) and applies it identically to every file. EMG amplitude columns from a 1.x run with noise reduction on are therefore not comparable with 2.x, and they were outside the controlled comparison above, which was run without EMG channels.

Parameter reference

Every setting RespMech accepts, grouped by area, with its exact TOML key, default and unit. In the desktop app these live on the Setup cards and behind the Advanced… buttons on the Preview tabs; in a settings file they are the dotted keys below. Defaults reproduce the validated reference pipeline.

Input

Where the recordings are and how their columns map to signals. See: Preparing your recording · Setup – Channels

Pre-analysis resampling

Optional resampling of every channel to one common rate before analysis. See: Resampling

Breath segmentation

How the recording is cut into individual breaths. See: Breath segmentation

Volume & drift

Volume sign, integration from flow, and drift/trend correction. See: Volume, drift & trend · Integrating from flow

Work of breathing

How work of breathing is read from the Campbell diagram. See: Work of breathing · Average vs individual

Diaphragm EMG

The diaphragm-EMG amplitude measures and ECG-artefact removal. See: Diaphragm EMG · ECG removal

EMG spectral noise reduction

Spectral noise reduction, trained on a shared rest reference. See: Spectral noise reduction

Cardiac-gated peak EMG

Optional cardiac-gated peak EMG for strongly heart-coupled recordings. See: Cardiac-gated peak EMG

Sample entropy

Sample entropy of the ticked channels. See: Sample entropy

Pressure–time product (PTP)

The baseline window for the pressure–time products. See: Pressure–time product

Exclusions & breath-count overrides

Dropping specific breaths and overriding per-file breath counts. See: Excluding breaths

Output

Which workbooks, sheets and diagnostic plots are written. See: Outputs

Outputs

When a batch finishes, RespMech writes a self-contained, publication-ready result folder. The compute core itself writes nothing to disk — a separate writer turns the finished result into files, so what you see on disk is a faithful snapshot of what was computed. Everything lands under one output folder you choose: numeric tables in a data/ subfolder, diagnostic figures in a diagnostics/ subfolder, and two provenance files at the top so a result is never orphaned from the exact settings that produced it.

You control what is written with a set of tickboxes on the Setup screen's Output card, plus a few EMG-output controls on the Preview & QC screen. The run report then records exactly what was read, kept, excluded and written.

The results folder

For an output folder named output (the default), a completed run produces this layout:

• output/
  • analysis-used.toml — the exact settings that produced this run, reloadable to reproduce it.
  • run-report.txt — a plain-text log of what was read, kept, excluded, written, plus ECG/noise diagnostics.
  • data/
    • Average breathdata.xlsx — one row per recording (mean across each file's kept breaths).
    • <file>.breathdata.xlsx — one workbook per recording, one row per breath.
    • Cohort summary.xlsx — mean ± SD, n and CV% across the batch, with a by-group breakdown.
    • <file> – Processed data.csv — optional per-sample trimmed signals (one CSV per recording).
  • diagnostics/
    • *.pdf — the diagnostic figures (Campbell, raw/trimmed signals, volume correction, EMG overviews).
    • *.wav — optional EMG audio, one file per channel per conditioning stage.

Choosing what gets written

The Setup screen's Output card holds the output folder, a Tables checklist, a Diagnostic figures checklist, and a Group files by box for cohort grouping. A live "You will get" line lists the exact deliverables the current ticks will write, so you can confirm before running.

From the command line, the same choices are read from the settings file:

respmech run settings.toml

This processes the batch and writes all enabled outputs to <output.folder>/data plus diagnostics and provenance, printing "Wrote N file(s)". Two variants are useful when setting up: respmech run settings.toml --dry-run computes but writes nothing (it prints the same output plan the desktop app's Dry run button shows, then per-file breath counts), and respmech validate settings.toml checks the settings and reports how many input files match. A non-zero exit from run means one or more files failed; the failures are listed on stderr.

Inside every workbook

Both breath-data workbooks (Average breathdata.xlsx and <file>.breathdata.xlsx) carry the same set of sheets, in this order:

• Data — the result table itself (the numbers). This is the only load-bearing sheet.
• Units — Column/Unit/Note columns giving the physical unit of each Data column. The Note column is blank except on the wob* columns, where it records the work-of-breathing source ("Work of breathing from: averaged breath" or "… individual breaths"), so a reader can see that in averaged-breath mode those values are one whole-file value repeated on every breath of the breath-by-breath workbook.
• EMG normalised — breath workbook only, present when EMG normalisation is on and EMG channels exist (see the normalised-EMG sheet).
• Provenance — Key/Value rows: RespMech version, the Python and library versions used (see Provenance: settings snapshot and run report), generation timestamp, input folder and pattern, sampling frequency (Hz), breath-separation method and buffer, the work-of-breathing source (averaged breath or individual breaths), drift correction, EMG normalisation, the sample-entropy parameters ("m = …, r = … × SD", only when entropy channels are assigned), and the settings-snapshot filename. Average breathdata.xlsx and Cohort summary.xlsx get one more, leading row — INCOMPLETE, naming how many files failed and were excluded — whenever the batch had at least one failed file.
• Version — a "Created with RespMech v…" line and a clickable link to the GitHub repository.

A column only appears on the Units sheet when its unit is unambiguous. A handful of ratios that are intentionally left unlabelled — vmr and tlr_insp — are simply absent from the Units sheet rather than mislabelled.

The Data sheet: result columns

The two breath-data workbooks share one column set. The breath-by-breath sheet leads with breath_no and gives one row per breath; the average sheet leads with file, drops breath_no, and reports every value meaned across that file's kept breaths. Both then carry the respiratory-mechanics and work-of-breathing columns, plus EMG and sample-entropy columns when those channels are configured.

Respiratory mechanics

Work of breathing

EMG (one set per configured EMG channel)

Sample entropy (one set per configured entropy channel)

EMG columns that edit the written numbers

Two EMG controls change the values written to these tables rather than merely adding sheets — worth knowing when you audit a result.

Cohort summary and grouping

Cohort summary.xlsx is written automatically whenever the average workbook is — the two are paired, and there is no separate switch for it. It aggregates the finished average table across files, and never touches the per-file or per-breath tables, so it is purely additive.

• Summary sheet — one row per numeric variable (column variable), with n, mean, sd (sample SD, ddof = 1) and cv_pct (coefficient of variation, %). sd and cv_pct are NaN whenever fewer than two files contribute a value, so a one-file group on the By group sheet always shows NaN.
• By group sheet — the same statistics per group, with leading group and n_files columns. Written only when files fall into more than one group.

Grouping. By default the group key is the leading filename token — everything up to the first space, underscore or hyphen — so P03_120W.csv groups as P03. Override this with a regular expression whose first capture group becomes the key, for filenames that don't front-load the grouping token or when you want to group by condition rather than subject.

The normalised-EMG sheet

EMG amplitude is uncalibrated and electrode-dependent, so raw RMS values (in a.u.) cannot be compared across subjects or electrode placements. To help with that, the breath workbook can carry an extra EMG normalised sheet that re-expresses every RMS column as a percentage of a reference — by default that same column's own peak or mean breath within the file, which makes the within-file pattern comparable but still leaves each file's own peak at 100%; set normalization_reference_file to a shared manoeuvre file (see Amplitude normalisation) for amplitudes genuinely comparable across files.

The sheet's columns are breath_no plus one <rms column>_pct column for each RMS column, in % of the per-file reference. The raw RMS on the Data sheet is never changed — normalisation only adds a sheet.

Processed-signal CSV

When output.data.save_processed is on, RespMech writes <file> – Processed data.csv for each recording: the trimmed, per-sample conditioned signals, for re-plotting or re-analysing the waveforms outside RespMech. Columns are:

Diagnostic PDFs

The diagnostic figures are paginated vector PDFs written to the diagnostics/ subfolder. Each is optional and independently toggled. They always render in the light theme even when the GUI is dark, so exported PDFs are print-ready and reproducible. A figure that fails to draw is skipped and recorded in the run report — it never aborts the run.

EMG audio export (WAV)

As a diagnostic aid, RespMech can export each EMG channel — at each conditioning stage — as a normalised 16-bit WAV file at the analysis sample rate, dropped into the diagnostics/ folder. Listening to the EMG is a fast way to judge ECG contamination and noise-reduction quality.

Provenance: settings snapshot and run report

Two provenance files are written to the top of the output folder on every run, regardless of which output tickboxes are ticked, so a result folder always carries its own recipe.

• analysis-used.toml — the exact settings that produced the run. Reload it to reproduce the analysis byte-for-byte.
• run-report.txt — a plain-text log covering the RespMech version and the Python/numpy/scipy/pandas/librosa versions the run used; the input folder and pattern; the files processed and failed (with excluded → used breath counts); the processing flags in effect; EMG diagnostics (R-peaks detected, suppression, ΔSNR); and the list of outputs actually written. If figures are skipped (for example because matplotlib is unavailable), they are recorded under a "FIGURES SKIPPED" heading and the run still completes with all tables written.

Every written workbook's Provenance sheet carries the same RespMech version and library-version line, alongside the run's settings summary, so a numeric mismatch against an older result can be checked against a library upgrade before it is treated as a regression.

Troubleshooting & FAQ

Most problems in RespMech come from a handful of load-time settings that are silent when wrong: the recording is rescaled, mislabelled or trimmed away without an error message, and only the numbers look off. This section collects the failures reported most often, the symptom that gives each one away, and the exact setting that fixes it. Every fix here is a setting change, not a data edit — RespMech is designed so you never touch the raw recording.

"No breaths were detected", or the file refuses to load

Before it measures anything, RespMech trims the recording down to whole breaths. It scans the flow signal for the first sample where flow < 0 (the onset of the first inspiration) and the last sample where flow ≥ 0 (the end of the last expiration), and keeps only what lies between. If flow never crosses zero — or the computed window is empty — it stops with a TrimError that names the flow channel and the inverse_flow setting.

Work through these causes in order:

• Wrong flow channel. Columns are 1-based and column 1 is usually the time axis (see A channel shows the wrong signal). A flow channel pointed at a flat or monotonic column never crosses zero.
• Flow sign reversed. If your rig records inspiration as positive flow, the trim logic looks for the wrong phase. Fix it with processing.volume.inverse_flow, not by editing data — see Breaths look upside-down.
• Volume-based segmentation with thresholds set too high. When processing.segmentation.method = "volume", breaths are found by peak detection; a peak.height (default 0.1 L) or peak.width_s higher than your actual breaths yields zero peaks and therefore zero breaths. Lower the thresholds, or switch back to method = "flow", which is more robust for most recordings.
• Every breath excluded. Breaths you have clicked out in Preview & QC (or listed under processing.exclude_breaths) are still detected but not analysed. Excluding all of them leaves nothing to measure, and RespMech says so separately from "none detected" — re-include at least one.

A file that reaches the run with nothing to analyse fails with a NoBreathsError naming the file and the setting to change, and the rest of the batch continues. Before v2.3.3 the same situation surfaced as an internal pandas message ('list' object has no attribute 'mean') that named neither.

A single breath, rather than the whole file, can also fail on its own: if a breath's inspiration and expiration phases cannot be joined into one pair, RespMech raises a DegenerateBreathError naming the breath number and the file, and stops that one file with exit code 1 — the rest of the batch is unaffected. The explanation depends on where the breath sits: an actual first or last detected breath is blamed on an incomplete breath at the start or end of the recording, exactly as before; a breath in the middle of a recording gets a different message instead, naming the breath's own timestamp and pointing at noise around zero flow, a mis-assigned flow channel, or more than one recording merged into the file (see the next section) — a truncated recording is not a plausible cause for a breath nowhere near either end of it, and the message no longer suggests one. Either way, exclude the breath in Preview & QC, or check the breath-separation settings under Preview & QC → Mechanics → Advanced… → Breath detection.

With method = "volume", a whole file can also fail with a VolumeSegmentationError when peak detection finds fewer expiratory than inspiratory peaks, so at least one breath cannot be paired with its expiration — slow, quiet breathing with pauses at zero flow between phases is the usual cause. The message names the file and the peak counts found. Loosen the peak.height / peak.width_s thresholds, or switch back to method = "flow".

With the default method = "flow", a file fails immediately with a ConstantFlowError if the flow channel is flat at exactly zero — either across the whole recording, or across a stretch reached partway through (a genuine pause with no flow at all is enough): segmentation walks the signal looking for a sign change between inspiration and expiration, and a flat-zero flow satisfies neither, so there is nothing to split on at that point. This is almost always a mis-assigned or unused/grounded flow column — check the channel assignment in Setup, or switch to method = "volume" if there genuinely is no flow channel for this recording.

A file fails to load with a data or format error

Before trimming ever runs, RespMech checks that every assigned column actually holds the data it claims to. Each of the following stops only the one file: the message names the exact channel and file, the run reports it as a failure, the rest of the batch is still processed, and the command exits 1 (see the exit codes).

• Column number out of range. "<channel> is set to column <n>, but columns are numbered from 1." for zero or a negative number, and "<channel> is set to column <n>, but <file> has only <n> column(s)." for a number past the end of the file. Recheck the channel against the column count, especially after switching between recordings with a different layout.
• Text in a numeric column. "<channel> column contains text values – all values must be numeric." A stray label, unit or comment cell sitting in an otherwise numeric column — often a header row exported as if it were data.
• Missing (NaN) cells. "<channel> column contains NaN values." A dropped sample or a blank cell in the export. RespMech does not interpolate across a gap in the raw data; re-export the recording, or restrict the epoch to a stretch without gaps.
• Columns of different lengths. "Data column lengths differ. All columns must have the same number of observations." Only reachable from a .mat file, where each channel is read independently; a CSV, tab-text or Excel export is always rectangular and cannot trigger this one.
• Unsupported file type. "Unsupported input file type: <.ext>" RespMech reads .csv, .txt, .xlsx and .mat only; anything else — including an export simply renamed to one of these extensions, or the older binary .xls format — fails with this message before RespMech even tries to read it.
• A .mat file RespMech cannot parse. "Cannot load MATLAB file – verify the MATLAB file format setting (windows/mac). Only simple LabChart exports are supported; otherwise export to CSV." Set MATLAB file format to match the machine that wrote the file, or re-export to CSV.

A recording looks like more than one export merged together, or an assigned channel never varies

Two further checks run before any of the above, over the recording as RespMech first sees it — in the desktop app's Setup QC strip, and in respmech validate, so a bad file is visible before you spend time running it:

• Merged multi-block export. If a file's time column otherwise looks like a regular sample clock but has duplicated or decreasing timestamps, RespMech flags it as looking like more than one recording (for example several separate LabChart blocks) exported into a single file and merged row-by-row by timestamp. Analysing a file like this is not merely risky — it makes the flow signal jump between different recordings from sample to sample, which can surface much later as an unrelated-looking DegenerateBreathError on one breath in the middle of the file. Re-export each block to its own file instead.
• A constant assigned channel. If flow, Poes, Pgas, Pdi, an EMG channel or an entropy channel never varies across the whole recording — most often a mis-assigned column, or a genuinely unused/grounded input on the acquisition system — it is flagged by name and column number. A constant flow channel is additionally a hard failure at run time (see the ConstantFlowError above); a constant channel of any other role is a caution, not a failure, since it does not stop segmentation, only makes that one channel's own numbers meaningless.

Both checks read only a bounded sample of the file (the first several thousand rows) for cost reasons, so a channel that is constant only for part of a very long recording, or a merge that only begins well into the file, may not be caught here — the checks are a fast first pass, not a substitute for looking at the data.

The breaths look upside-down, or inspiration reads positive

RespMech has one fixed sign convention, and every inspiratory/expiratory quantity depends on it:

If the Campbell loop is mirrored, inspiration and expiration are swapped, or the flow trace points the wrong way, your acquisition uses the opposite polarity. Correct it at load time with the two invert toggles — getting them wrong does not error, it silently mislabels every phase-dependent number.

"Could not correct the end-expiratory trend"

The trend correction fits an envelope through the end-expiratory trough of each breath. It refuses in two distinct ways, both on the file only, and the rest of the batch still runs. If the volume signal itself is unusable — it contains a NaN or infinite sample, typically an unset volume channel or a broken flow-to-volume integration — it stops immediately with "Could not correct the end-expiratory trend: the volume signal contains missing or infinite samples.", before it ever looks for troughs; check the volume channel under Setup, or Calculate volume from flow under Mechanics → Advanced…. Otherwise, the run stops on a file when too few troughs are found to fit an envelope — two for the default linear interpolation, three for quadratic, four for cubic. That second message reports how many troughs were found and against which threshold, and the file is skipped rather than given numbers derived from an undefined envelope.

• The message names trend_peak_min_height. That is the legacy absolute rule: a trough must lie that many litres below the highest volume in the whole recording. On ordinary tidal breathing the entire volume range is often smaller than the threshold, so nothing qualifies. Set Trend anchor — absolute threshold (legacy) back to Auto under Preview & QC → Mechanics → Advanced…, or remove trend_peak_min_height from the TOML. Analyses saved before v2.3.3 that merely inherited the old 0.8 default are switched to Auto for you on load, and RespMech says so.
• The message names the breath depth. The recording has genuinely shallow breaths relative to its own volume range — usually quiet breathing recorded alongside a large manoeuvre (an inspiratory capacity, a sigh, a cough), which inflates the range. Lower Trend anchor — minimum breath depth; the Advanced dialog shows how many troughs the current value finds in the previewed file, so you can watch the count as you change it.
• Too few breaths for the interpolation. A short recording cannot support cubic (four anchors) or quadratic (three). Use linear.
• You do not need the correction. If end-expiratory volume is stable across the recording, untick Correct end-expiratory trend — drift correction alone is enough, and it is on by default.

Timing, bf, VE and the per-breath integrals look wrong by a constant factor

The sampling frequency is the time base of the whole analysis, and nothing checks it against the data at run time. Declaring a rate that is k times too low (k = true fs / declared fs) multiplies Ti, Te, Ttot and the per-breath integrals (int_*) by k, divides bf, VE and the per-minute work of breathing by k, and leaves ti_ttot, VT, every pressure descriptor, tlr_insp and vmr unchanged.

The ptp_* rates are essentially unchanged too, because the k in the integral and the 1/k in the breaths-per-minute factor cancel — so a plausible PTP does not prove the rate is right. When volume is integrated from flow the pattern shifts: VT itself scales by k, while VE and the per-minute work of breathing come out unchanged. Anything defined in seconds rather than samples moves as well: with segmentation.method = "volume" the peak-distance and width thresholds are converted with fs, so a wrong rate changes which breaths are detected at all, and the same holds for the EMG RMS window, the ECG refractory gap, the cardiac-gated blanking window and pre-analysis resampling. If a whole batch of results is off by a pattern like this, suspect the sampling frequency first.

A channel shows the wrong signal (off-by-one column mapping)

Channel columns are numbered from 1, matching the LabChart export, and column 1 is normally the time axis. Assigning a required channel to column 1, leaving one unassigned, or pointing two roles at the same column are all flagged in the QC strip; a zero, negative or out-of-range column number is a hard load error. The safest way to map them is the visual Assign channels from data… picker, which plots every column so you match it to its physiological role rather than counting.

Volume drifts, or VT and the Campbell loop look wrong

Flow-integrated volume accumulates baseline drift, which is why drift correction is on by default. It removes a linear baseline slope from the zeroed volume trace (a de-trend with one deliberate quirk: the very last sample is pinned to 0 — that is expected, not a bug). If you turned drift correction off while integrating volume from flow, VT and the pressure–volume loop distort as the baseline wanders.

• Volume still trends across the run (end-expiratory lung volume wanders, e.g. during exercise): enable processing.volume.correct_trend, which subtracts an interpolated envelope through the end-expiratory points. It anchors on each breath's end-expiratory trough, judged relative to the recording's own volume range, and emits its own diagnostic figure. See "Could not correct the end-expiratory trend" if it stops on a file.
• Volume decreases on inspiration: enable processing.volume.inverse_volume (see the sign conventions above).
• Inspecting raw drift: turn correct_drift off only to see the untouched trace; leave it on for analysis.

The ECG detector will not lock onto the heartbeats

ECG removal first detects R-peaks on one capture channel, then averages a template and subtracts it beat-by-beat. If detection is unstable, the whole stage misbehaves. The EMG – ECG reduction tab plots the capture channel with a marker on every detected beat, so you can tune the two critical thresholds while watching them land.

Three things determine whether it locks:

• Capture channel. Pick the EMG channel with the clearest R-wave and the weakest EMG — often the middle electrode. Detection runs on that one channel and the same beat train is applied to every EMG channel.
• Min height. The R-wave height threshold must sit between the EMG burst amplitude and the R-wave amplitude. Set it too low and the detector locks onto EMG bursts; too high and it misses real beats. It is in the same uncalibrated units (a.u.) as the raw EMG, so it is electrode- and recording-specific.
• Min gap. The refractory gap sets the maximum detectable heart rate. For fast (exercise) recordings, a gap that is too long merges or drops real beats.

The cardiac-gated peak columns come out blank (NaN)

The cardiac-gated peak reads the per-breath peak from only the heartbeat-free stretches of each breath, blanking a window around every detected R-peak and taking the maximum of what survives. It deliberately reports NaN rather than a wrong number when it cannot trust the result, so blank gated columns are a normal, honest outcome — not a failure.

Check these, in order:

• ECG removal must be on. The gated peak reuses the R-peaks that processing.emg.remove_ecg = true found. With no beats detected, there is nothing to gate around and every gated column is NaN.
• Heart rate near the detector ceiling. If the detected rate approaches 60 / ecg_min_distance_s, the guard refuses to gate because the detector is about to start missing beats. The fix is to lower Min gap (ecg_min_distance_s) on the ECG tab, not to raise hr_ceiling_margin.
• Too little cardiac-free signal. A phase goes NaN when less than min_survival (default 0.40) of it survives the gates, or its longest cardiac-free run is shorter than min_island_s (default 0.20 s) — a gap too short to hold a full RMS window.
• Missed beats. If more than max_long_rr_frac (default 0.02) of R-R intervals exceed long_rr_factor × the median, detection is distrusted for the whole file and every gated column is blanked.

Noise reduction removes too much EMG — or does nothing at all

Spectral noise reduction subtracts one shared spectral profile, built from a rest reference and applied identically to every file. Two failure modes dominate.

It does nothing. Noise reduction requires ECG removal to be on and a reference file to be set. A ticked processing.emg.noise.enabled with no reference_file runs nothing in the app and raises an error in a batch run. The reference must be a proper rest recording with several seconds of EMG-free signal; the default use_expiration = true builds the profile from every expiration of that file (hundreds of stable STFT frames), which is far better than a single short quiet gap.

It refuses to build a profile at all. The reference needs at least one full FFT window (n_fft, default 256 samples) of EMG-free signal. Shorter than that, the run stops before processing a single file with "Noise reference is too short (<N> samples) for a stable estimate at n_fft=<n_fft>. Provide a longer EMG-free reference (≥ several STFT windows)." — exit code 2. A reference just above that floor (fewer than about 8 STFT frames) does not stop the run, but the per-frequency noise estimate is unstable: RespMech prints a UserWarning on stderr that is easy to miss and that never reaches run-report.txt. If fidelity looks noisy from channel to channel, lengthen the reference before tuning anything else.

It destroys real EMG. The over-subtraction guard is fidelity — the fraction of true inspiratory in-band (20–250 Hz) EMG power that survives removal:

Leave Auto (auto_prop) on: it picks, once per test, the strongest suppression (prop_decrease) that keeps every channel's fidelity at or above fidelity_target (default 0.8, i.e. retain ≥ 80 % of EMG power). With Auto on, any manual Strength value is ignored. The EMG – noise reduction tab plots the fidelity frontier — fidelity retained against suppression strength, one curve per EMG channel — so you can see the trade-off before committing. (ΔSNR is measured too, but it is reported in run-report.txt, not drawn on that panel.)

"Settings valid" but no files run, and what the exit codes mean

A common surprise is respmech validate printing Settings valid. and then WARNING: no input files match. before exiting with code 1. The settings really are valid — RespMech just found nothing to process. The usual causes:

• The input folder is relative to the settings file, not your shell. A relative input.folder / output.folder is resolved against the directory of the .toml file, not the working directory you ran the command from. This keeps a shared analysis portable, but it surprises anyone expecting shell-relative paths. Use an absolute path if in doubt.
• Mask typo or wrong extension. input.files is one glob (matching is case-insensitive on every OS). A multi-pattern mask like *.csv; *.txt is narrowed to a single extension by the app before a run; the core batch runner globs one pattern only.
• Leading-dot files are skipped unless the mask itself starts with a dot.

The exit codes form a script-facing contract worth distinguishing:

respmech validate settings.toml   # check settings + count matching files
respmech run settings.toml --dry-run   # compute without writing anything

The app won't open on first launch (macOS Gatekeeper / Windows SmartScreen)

On the first launch of a freshly downloaded desktop build, your operating system may hold it back until you confirm you trust it. This is a generic protection for downloaded applications, not a fault in RespMech, and it typically appears only once per install.

• macOS (Gatekeeper). If a double-click is blocked, Control-click (right-click) the RespMech app icon, choose Open, then confirm Open in the dialog. Alternatively open System Settings › Privacy & Security and click Open Anyway next to the RespMech entry.
• Windows (SmartScreen). If you see "Windows protected your PC", click More info, then Run anyway. SmartScreen may warn for a while on a brand-new release until it has built reputation, even for a signed installer.

Windows: a run fails on a deeply nested input or output folder

The packaged Windows build is subject to Windows' legacy 260-character path limit, and RespMech writes long, descriptive output names (for example diagnostics/<recording> – EMG (ECG removed + noise reduced).pdf). If a run fails on files whose full paths are very long, move the recordings and the output folder closer to the drive root (for example C:\RespMech\study1) and run again. Long-path awareness is not yet enabled in the installer.

Reference tables

Units of the result columns

Every number RespMech writes carries its unit on the workbook's Units sheet. The pipeline asserts a unit only where the physiology is unambiguous; EMG amplitude is reported in arbitrary units because this pipeline does not calibrate it, and sample entropy is dimensionless.

↑ Back to top

References

RespMech implements published methods. The list below gives the primary source for each method the manual describes, plus the third-party code the analysis engine builds on. Several in-text mentions elsewhere on this page link back to the matching entry here. Nothing here is a validation of RespMech itself; see Changes from RespMech 1.x for what has been verified about the engine, and the project's Zenodo record (linked in the footer) for how to cite the software.

Respiratory mechanics and work of breathing

1. Otis AB, Fenn WO, Rahn H. Mechanics of breathing in man. J Appl Physiol. 1950;2(11):592–607. doi:10.1152/jappl.1950.2.11.592
2. Mead J, Whittenberger JL. Physical properties of human lungs measured during spontaneous respiration. J Appl Physiol. 1953;5(12):779–796. doi:10.1152/jappl.1953.5.12.779
3. Campbell EJM. The Respiratory Muscles and the Mechanics of Breathing. London: Lloyd-Luke; 1958.
4. Milic-Emili J, Mead J, Turner JM, Glauser EM. Improved technique for estimating pleural pressure from esophageal balloons. J Appl Physiol. 1964;19:207–211. doi:10.1152/jappl.1964.19.2.207
5. Milic-Emili J, Grunstein MM. Drive and timing components of ventilation. Chest. 1976;70(1 Suppl):131–133. doi:10.1378/chest.70.1_supplement.131
6. Baydur A, Behrakis PK, Zin WA, Jaeger M, Milic-Emili J. A simple method for assessing the validity of the esophageal balloon technique. Am Rev Respir Dis. 1982;126(5):788–791. PMID 7149443, doi:10.1164/arrd.1982.126.5.788
7. Bellemare F, Grassino A. Effect of pressure and timing of contraction on human diaphragm fatigue. J Appl Physiol Respir Environ Exerc Physiol. 1982;53(5):1190–1195. doi:10.1152/jappl.1982.53.5.1190
8. Field S, Sanci S, Grassino A. Respiratory muscle oxygen consumption estimated by the diaphragm pressure–time index. J Appl Physiol Respir Environ Exerc Physiol. 1984;57(1):44–51. PMID 6469790, doi:10.1152/jappl.1984.57.1.44
9. Cabello B, Mancebo J. Work of breathing. Intensive Care Med. 2006;32(9):1311–1314. doi:10.1007/s00134-006-0278-3