Changelog
What's new in RespMech
Every release from v2.0.0 onward, newest first: the PySide6 desktop rewrite is where RespMech's current release line begins. For what changed between the legacy v1.x line and v2, see Changes from RespMech 1.x in the docs. Installers for every release live on GitHub Releases; this page mirrors the same log kept as CHANGELOG.md in the repository, trimmed here to what a user of the app sees.
Coming next unreleased
Built and merged, not yet in a tagged release or an installer.
- ECG removal aligns on the R-wave again. Since 2.5.0 the R-peak detector chose, heartbeat by heartbeat, whichever lobe of the QRS complex was taller, so on recordings whose R and S lobes are about the same size less ECG was removed, and an occasional heartbeat was missed. A channel now uses one polarity for every beat: the upright R-wave, unless the channel's R-wave is clearly inverted, judged in the frequency band of the QRS complex so that a T-wave cannot pass for it, and a single large artefact cannot switch it. On the validation recordings this gives the same R-peaks as before 2.5.0, so ECG-removed EMG can differ from an analysis made with 2.5.0. With ECG removal off, Preview & QC now marks the same R-peaks a run would subtract the template at. See ECG removal.
- Auto strength says when the fidelity target is out of reach. When no noise-reduction strength keeps every EMG channel at the fidelity target, RespMech still uses the gentlest one, and now says so in the run log, the run summary and Preview & QC instead of presenting it as if the target had been met.
- The average Campbell loop as numbers. Tick Average Campbell loop CSV (per file) in Setup and a run writes the points of the average breath (phase, point, volume and, with Poes, oesophageal pressure) to a CSV per file, and with two or more files one table for all of them, so conditions can be compared directly instead of by eye. Preview & QC can save the same table for the file on screen. It is off unless ticked, so an analysis that does not use it writes what it wrote before. See Average Campbell loop CSV.
v2.5.0
RespMech 2.5 analyses what you recorded, and a companion app, Adichtion, gets LabChart recordings out faster, without LabChart. Until now RespMech would not run without flow and all three pressures, and treated every breath as tidal. An analysis now starts from a signal set, from flow alone to the complete set, or EMG alone, and RespMech knows what a manoeuvre is: any breath can be typed as IC, FVC, maximal inspiratory effort or sniff. A typed FVC gives FVC, FEV1 and PEF, and an IC reference, even from another file, gives operating lung volumes once a VC or TLC is known. Adichtion is a free, open-source viewer and reader for macOS, Windows and Linux: it opens .adicht files, exports CSV that RespMech reads, and one command cuts an interval between two comments. Its Python library, on PyPI, reads a channel into numpy. Every new analysis feature is off until asked for, and the release notes name the few defaults and numbers that change.
- A recording no longer has to be flow, all three pressures and EMG. A new analysis starts with a choice of signal set, from Flow only to the complete set or EMG only, and Setup, Preview & QC and the columns a run writes follow it. An analysis that does not use the new options is read, run and written as before.
- Breaths can be typed, and manoeuvres are extracted from them. Mark any
breath as an inspiratory capacity (IC), a forced vital capacity (FVC), a maximal
inspiratory effort or a sniff; a typed FVC gives FVC, FEV1 and peak flow. A
mis-detected breath boundary can be cut or joined at a click, and the new
respmech breathscommand lists every detected breath. - References can come from another file. A file’s IC, FVC, baseline
and maximal-effort references can be a typed breath in the same or another file, and
per-participant spirometry (TLC, VC, RV, FEV1, MVV) applies to every file of
that participant.
respmech validatereports a link that will not resolve before the batch is run. - Operating lung volumes and expiratory flow limitation. Once a file has an IC reference, end-expiratory and end-inspiratory lung volume and inspiratory reserve volume are reported per tidal breath. With a forced expiration in the same file, each tidal loop is placed inside the file’s own maximal flow-volume curve, which gives the share of the breath at the flow ceiling and the ventilatory capacity and breathing reserve that follow from it.
- Optional PEEPi and a modified Campbell diagram. Off by default: it measures intrinsic PEEP from the oesophageal pressure deflection before inspiratory flow and reports the extra work it adds in new columns, leaving the existing columns and the standard Campbell diagram unchanged. The detection thresholds are starting values that have not yet been tuned on real recordings.
- Pressure and EMG against a maximal effort. Also off by default: each breath’s oesophageal and transdiaphragmatic pressure, and EMG, as a percentage of the same person’s own maximal inspiratory effort, with tension-time indices and a neural respiratory drive index.
- EMG-only recordings can be analysed. Without a flow signal, each file is cut into segments by separators you place, at the onset of every burst found automatically, or in fixed windows, and each segment reports its own neural timing. The burst thresholds are starting values checked on synthetic recordings only, so look at the shaded segments before trusting them on real ones.
- Sample entropy on the volume RespMech analyses, and on derived volume. When the volume column is also an entropy column, its sample entropy is computed on the conditioned volume instead of the raw column, so the values of such an analysis change. A new option computes entropy on the integrated volume when the volume has no column of its own.
- Saved analyses: settings this version does not recognise now survive a save instead of being silently dropped. An analysis that uses the new settings must not be opened and saved by a RespMech older than 2.5, which would delete the tables it does not know for good.
- Sample entropy’s default Template length (m + 1) has changed from 2 to 3. The old default of 2 computed sample entropy at m = 1, not the m = 2 of the literature, so an analysis that leaves the field unset reports different values; set it to 2 to reproduce earlier results. See The Sample-entropy card and How RespMech computes it.
- Two new checks catch a bad recording before you run it. A time column
with duplicated or decreasing timestamps (several recordings merged into one file) and an
assigned channel that never varies are flagged by name in Setup and in
respmech validate. A flow channel flat at exactly zero stops the file with a named error; see the troubleshooting section. - Setup has a new Subjects card. It holds each participant’s TLC, VC, RV, FEV1, MVV, sex, age and height and is always shown. Add subject, Add from recordings and Remove selected manage the rows without editing the settings file, and a value that cannot be used is refused in place with a note.
- A normal range behind the maximal flow-volume loop. With a participant’s sex, age and height given, the maximal flow-volume figure shades the normal range behind the participant’s own curve and draws the expected curve dashed. The size comes from the GLI 2022 race-neutral equations and the shape from ECCS 1993 (an adult reference), so the shape is indicative; a note in the figure names the sources.
- Opt-in VT/Ti breathing-pattern columns and variability. Two switches, both off by default (Mechanics › Advanced… › Breathing pattern), add per-breath mean flows, phase volumes, rate and time to peak flow, and each file’s coefficient of variation of VT, Ti, Te, Ttot and Ti/Ttot. They need only flow and volume, so they work for a Flow-only analysis too.
- Noise reduction no longer inflates the EMG it leaves alone, so every noise-reduced EMG number changes. The spectral reconstruction now scales each bin’s magnitude and keeps its original phase, where before the retained in-band power could exceed 100 % even at strength 0. Re-run an analysis that used noise reduction if you need numbers comparable with one from before.
- The ECG R-wave detector finds an inverted R-wave and agrees with Auto-suggest. It now runs on the same median-removed signal Auto-suggest uses and searches both polarities, so a channel with a DC offset or an inverted R-wave works; this can move the detected peaks, and so the ECG-removed EMG, of an existing analysis.
- The EMG noise profile is built from the breaths the analysis runs on. It now follows the analysis’s own segmentation method and volume trend correction instead of always segmenting by flow without trend correction. Numbers change only for an analysis that has noise reduction on and either segments by volume or has trend correction on.
- A shared EMG-amplitude reference across files. The ‘% of peak/mean
breath’ normalisation puts every file’s own peak at 100 %, so the
percentages are not comparable across files or subjects. Setting
processing.emg.normalization_reference_fileto a maximal manoeuvre in the batch normalises every file against that file’s own maximum or mean; off by default. - New and extended command-line commands.
respmech initwrites a commented starting settings file for the chosen signal set,respmech breathslists every detected breath of a file with its number, onset and kind, andrespmech validateandrun --dry-runreport more of what a run will do. - Results and the run report record more of how they were made. The
Provenance sheet and
run-report.txtname the Python, numpy, scipy, pandas and librosa versions, and the run report also names breath-count overrides, excluded breaths, the PTP baseline window, the work-of-breathing source and the cohort grouping. A batch in which a file failed marks Average breathdata and Cohort summary as incomplete and names the files. - Poes, Pgas and Pdi are no longer required. A settings file needs only Flow or EMG, and an analysis with no pressure channel simply computes fewer columns; asking for a pressure signal without Flow is refused.
- Breaking: EMG noise reduction now requires ECG removal.
processing.emg.noise.enabledwith ECG removal off is refused byrespmech validateandrespmech runwith an error naming both keys, since that combination modelled the heartbeats as steady noise. Turn ECG removal on first to keep running it. - Mistakes in a settings file are named before a run. A misspelled or
renamed key is no longer silently ignored, and
respmech validatealso checks that the output folder is writable and the EMG detection channel is in range. A skipped diagnostic figure prints a warning as it happens, and the final line of a run counts files against the output folder. - Three crashes now end in a result or a named error. An all-integer pressure or flow column, volume-based segmentation that cannot pair every inspiratory peak with an expiratory one, and EMG outlier filtering on an analysis with no EMG channels no longer end in a raw error.
- The File menu is locked while a run is going, and the ECG reference is tracked by folder. The menu’s actions could swap the settings out from under a running batch. The ECG reference is now folder-tracked like the noise reference, so opening an analysis against a different recordings folder shows the Keep/Clear banner; the new EMG-normalisation reference is tracked the same way.
- A recording cut mid-breath at either end is flagged instead of analysed
silently. A truncated boundary breath tilted the volume baseline of every other
breath when drift correction was on; RespMech now raises a quality notice in Preview
& QC, the Run log and
run-report.txtnaming the end that looks truncated. It is a heuristic, the threshold can be changed per analysis, and no computed number changes. - A single click on a breath marks it; right-click types or excludes it. A click paints the breath green on every plot and in its table row and never changes the analysis. To exclude, include or type a breath, right-click it or use the new controls next to Refresh; a typed or excluded breath also says so in text under its number.
- Small corrections. The Units sheet and the output writers use the dot
form (L·s−1, L·min−1), the shaded area on
Preview’s Campbell diagram is labelled ‘inspiratory resistive work’, the
‘Run & results’ button now reads ‘Run & results’ (it shipped in 2.4.0 as
‘Run _results’), axis labels no longer run into each other on a short panel,
and
.xlsis no longer offered as an input format, since it could not be read.
v2.4.0
The desktop app's workspace has been rebuilt around two tabs instead of three: Setup and Preview & QC, with Run & results folded into a drawer under a shared, searchable file list instead of living as a separate tab. Every screen and action stays reachable at all times; only the action itself is ever blocked, and always with a full-sentence reason next to it. Nothing in the analysis changed: a settings file run before and after this release produces identical output.
- Two tabs, not three. Setup and Preview & QC, with Run & results folded into a drawer under a shared, searchable file list that opens itself the moment a run starts. Every screen stays reachable at all times — only the action itself is ever disabled, and always with a plain-language reason beside it.
- Setup redesigned: two columns instead of one long stack, a real File/View/Help menu bar with an offline About box, a startup chooser (New analysis, Open, Explore with sample data), and “Duplicate for another recordings folder…” for the next subject in a multi-subject study.
- A batch is read as a batch. Column count, sampling frequency and LabChart header warnings are checked across the whole folder instead of assumed from the first file, and a file that disagrees is named rather than silently dropped. The channel dialog suggests roles from the file’s own column headers and handles European comma decimals on its own.
- Your choices follow the recordings folder, not the filename. Breath exclusions, breath-count overrides and the EMG rest reference are remembered per folder, so pointing the same analysis at a new subject who reuses a LabChart export name no longer inherits the previous subject’s decisions, and anything carried over is flagged rather than applied quietly.
- Errors explain themselves, and nothing overstates what happened. Plain-language diagnoses with the technical detail behind a Details toggle, an unreadable file named and skipped instead of aborting the batch, and progress, the output-folder confirmation and the pre-run plan all reflecting exactly what was and will be written.
- Preview & QC keeps up. The mechanics stack no longer freezes the interface while redrawing, fits a short screen, and labels its channels, units, crosshair and analysis window. The Campbell preview matches the orientation of the figure RespMech actually writes. The EMG tabs show the live signal instead of a stale one and say plainly whether a panel is raw or processed.
- Smaller things that add up: drag-and-drop of recordings folders and analysis files, double-clicking a .toml analysis in packaged builds, file-navigation shortcuts that no longer fight a focused table, visible focus rings and higher-contrast disabled fields, a round of layout fixes for Windows’ wider fonts, and long sessions that no longer build up memory.
- Fixes found while testing this release: the noise-reduction tab’s row of controls no longer resizes and reshuffles itself without settling, and a test run with both Remove ECG and auto-detect switched on no longer stops with a settings error.
- A few labels changed to match what they actually do. The Setup tab’s blocking message now reads “Setup incomplete” (was “Settings incomplete”), the noise tab’s bare “Auto” checkbox is “Auto strength”, the ECG tab’s “Auto (whole batch)” is “Auto-detect for the batch”, and the mechanics “Breath-separation buffer” is “Breath-separation debounce”. Same field, same behaviour in every case: an older screenshot or note naming the old label is talking about the same control.
v2.3.4
An interface release: every window now fits every screen, both themes paint correctly on Windows, and the Preview screens give their space back to the graphs. Nothing in the analysis changed: a settings file run before and after this release produces identical output.
- The Advanced… windows no longer open taller than the screen with their buttons out of reach. Reported on a 1080p Windows laptop at 150% scaling, where the Mechanics window asked for more height than the screen had and put OK and Cancel in the part you could not get to. The settings are now grouped into titled cards, laid out in one to three columns depending on how much width there is, with the buttons pinned outside the scrolling area so they are always reachable. Every window is also sized to the screen it opens on.
- Fixed windows and dialogs rendering black in a light-mode session on Windows.
- Fixed Enter throwing away your edits: Cancel was the default button on every dialog, so the one keyboard action anyone tries first discarded the changes. Enter now confirms and Esc cancels.
- Preview & QC now scrolls on a short screen instead of squeezing the graphs into unreadable slivers, and each stacked channel keeps a minimum height of its own. On a screen with room to spare, nothing scrolls.
- Fixed several controls forcing the whole app to be wider than a laptop screen: the Run screen's row of buttons now wraps, the noise-profile window scrolls per channel, and the channel setup window opens sized to its content.
- Fixed the colours that only worked in one theme: the Campbell diagram accent and the EMG envelope stayed light-mode red on the dark background, tickboxes, the error card and the resize grip could all but disappear. A Campbell diagram exported from dark mode is now rendered light, so a figure for a paper does not come out near-black.
- The EMG screens give the space back to the graphs: each panel's title and its channel picker now sit in the top edge of the graph instead of taking a row of their own, the gated-peak settings moved into Advanced… (they change nothing you can see; they only add columns to the saved data), and the Campbell diagram keeps a margin instead of running into the edge of its panel.
- The EMG – noise reduction tab now divides into roughly equal thirds (controls, the two working views, and the three reference panels) instead of giving the two working views half the window and leaving the raw channels, the fidelity frontier and the detail spectrum a sliver each.
- Fixed the Campbell diagram panel cutting off its own labels: on a laptop the heading was drawn half outside the panel and the rotated axis caption was clipped. The heading now sits in the panel's own title bar, the axis caption shortens to fit and returns in full on a taller panel, and the key no longer covers the loops it names when there is no room for it. A diagram exported for a report still carries its title.
- Fixed the graphs becoming unreadable at those compact sizes: axis numbers printed through one another, axis captions were cut off, and the legends covered the very traces they named. Axis numbers now thin out and come back as a panel grows, captions shorten to the longest wording that fits, the trace names moved out of the graph into the panel's top edge, and the two small diagnostic figures drop what they have no room for and get it back when you drag them larger.
v2.3.3
Batch-mode ECG auto-detection, a volume-trend correction that scales to the recording, and a set of interface fixes, since v2.3.2.
- ECG auto-detection can now drive batch and command-line runs, not just the Preview screen's Auto-suggest button: the detector is fitted once on a reference recording and applied to every file in the batch. Off by default, so existing analyses are unchanged. Each file reports a detection-quality warning if the shared settings look like they are missing beats, so an unsupervised batch still leaves a visible trail.
- The same option in the app, as an Auto (whole batch) tickbox on the ECG tab.
- End-expiratory trend correction now scales to the recording. The troughs that anchor the trend envelope were chosen by an absolute depth threshold inherited from RespMech 1.x, which matches nothing on ordinary tidal breathing, so on many recordings the correction quietly did nothing or failed. The new criterion is a fraction of each recording's own volume range, so it works at any tidal volume and in any volume unit, and it is now editable in Mechanics ‣ Advanced… rather than being reachable only from the analysis file. An analysis that set the old threshold deliberately keeps it and reproduces exactly.
- A recording that cannot support a trend fit, or in which no breaths can be separated, is now refused by name and with the reason, instead of surfacing as an internal error. The rest of the batch still runs.
- Fixed the main window becoming wider than the screen on Preview & QC. This was still happening on Windows after the first fix, where the wider system font pushed the window's minimum width past a 13″ laptop screen.
- In the Mechanics Advanced… dialog, detail fields such as Resample to and Trend interpolation now grey out when their own tickbox is cleared, instead of looking editable while having no effect.
- Fixed an analysis file that stored ECG auto-detection switched on while Remove ECG was switched off. Opening it left Auto (whole batch) ticked and greyed at the same time, every preview was refused as Settings incomplete, and there was no way to clear the tickbox without turning Remove ECG back on first. Such a file now opens with the pair corrected, says so in the status line, and keeps the correction when the analysis is saved. The command-line tool still reports the combination as an error, because in a hand-written settings file it is one.
- The control strips on Preview & QC now line their captions, tickboxes, fields and buttons up on a shared centre line rather than hanging from a shared top edge, so one taller control no longer leaves the rest of the row sitting high.
v2.3.2
A performance pass across the analysis pipeline and the Preview screen.
- Faster batch runs: the file load and ECG removal are now cached per run instead of repeated.
- Faster diaphragm-EMG processing (RMS, entropy and ECG-template matching all sped up).
- Smoother Preview plots at high sample counts (decimation and view clipping).
- Faster app startup.
- The progress bar now advances correctly during the results-write phase, instead of appearing stuck near the end of a run.
v2.3.1
- Fixed the packaged desktop app occasionally relaunching itself while writing batch diagnostic figures.
- More realistic bundled sample EMG data for the onboarding walkthrough.
v2.3.0
A UI reorganisation across Setup and Preview.
- Setup is leaner; settings that used to crowd it now live behind Advanced… panels on the Mechanics and EMG tabs of Preview.
- A data column can now carry a channel role and be selected for sample entropy at the same time: previously it was either/or.
- The channels list on Setup is now a read-only readout; the channel picker is the only place that assigns a role.
- Noise reduction now explains in the UI that it waits for ECG removal first.
- New opt-in Gated peak statistic on the EMG tab of Preview & QC, available once Remove ECG is on: each breath's peak EMG is measured a second time from the heartbeat-free stretches only, and written as extra gated columns beside the existing ones, so a leftover heartbeat is no longer reported as the loudest moment of the breath. The existing columns are unchanged.
- The faint respiration silhouette behind the EMG traces is now centred on zero flow instead of on the middle of the EMG's own range. It used to sit at a different height in every recording, which made two files impossible to compare by eye.
- Fixed three settings that could change without being asked. A channel left unassigned was silently analysed as the recording's last column instead of reporting an error; opening the channel picker and pressing OK could drop the EMG role and switch the EMG analysis off; and rolling the mouse wheel over a form could alter the setting under the pointer, including the EMG RMS window length, which changes every reported EMG value. Results produced on an earlier 2.x build are worth re-checking.
- Various cross-platform polish (Windows spin-box arrows, plot styling consistency).
- Releases are now published as full GitHub releases rather than pre-releases.
v2.2.2
Packaging fix only (the PyPI publish step needed a retry after v2.2.1); no functional change to RespMech itself.
v2.2.1
- First PyPI release:
pip install respmechnow works. - More realistic bundled sample data (a proper open Campbell loop, a heartbeat artefact that dwarfs the EMG as in a real recording, and EMG bursts confined to inspiration).
- Refreshed README screenshots and feature graphics.
v2.2.0
A broad audit pass across trust, settings and outputs.
- Pre-analysis resampling now actually runs (previously configurable but silently inert).
- Trend correction is applied in the mechanics preview.
- Diagnostic PDF output restored and upgraded.
- Settings that had no UI control before are now surfaced in an Advanced panel.
- New EMG – ECG reduction tab on the Preview screen, next to the signal it tunes.
- Fixed clipped breath-number labels on the mechanics plots and a few blank glyph-only buttons.
v2.1.1
- A missing noise reference now shows a clear message instead of a raw error.
- Installers are now signed: the macOS app is notarised and the Windows installer is Authenticode-signed.
v2.1.0
Preview screen redesign: switching files or tuning a setting now recomputes only what actually depends on the change, results are cached, and a running batch preview can be cancelled cleanly instead of blocking the app.
v2.0.0
The first release of the RespMech v2 desktop application: a complete rewrite of the v1 scripts into a guided app.
- Three-screen guided workflow: Setup → Preview & QC → Run & results.
- A companion command-line tool (
respmech run/validate/migrate) and declarative TOML settings, replacing hand-written.pysettings files, with a migrator for old ones. - Live tuning on the Preview screen against the real signal, before running the batch.
- The underlying calculation is a faithful port of the original v1 code: breath timing, volumes, ventilation, the pressure descriptors and the elastic work-of-breathing component are pinned byte-for-byte by golden tests. Two results differ from 1.x on purpose: the PTP baseline (now a 50 ms end-expiratory window mean) and a fixed sample-entropy indexing bug. The Simpson-integrated columns differ further because of a SciPy rule change. The golden reference is the current engine's own output, not v1's: see Changes from RespMech 1.x before comparing values across versions.
- Dark mode throughout, and packaged installers for Windows and macOS.