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.
- A recording no longer has to be flow, all three pressures and EMG. A new analysis starts with a choice of signal set: Flow only, Flow + Poes, the complete set, each with or without EMG, or EMG only. Setup, Preview & QC, the columns a run writes and the figures it draws follow the choice, and an analysis that does not use the new options is read, run and written as before. The pressure channels are only asked for when the chosen signal set needs them.
- 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 breath gives FVC, FEV1 and peak flow;
a file made up only of reference manoeuvres can serve the tidal files around it. A
mis-detected breath boundary can be repaired by hand in Preview & QC, by cutting or
joining at a click, and the new
respmech breathscommand lists every detected breath with its number. - References can come from another file. The IC, FVC, baseline and
maximal-effort references of a file can be taken from a typed breath in the same file or in
another one, and per-participant spirometry (TLC, VC, RV, FEV1, MVV) is applied
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. End-expiratory and end-inspiratory lung volume (EELV, EILV) 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 that runs at the flow ceiling, and the ventilatory capacity and breathing reserve that follow from it. A new flow-volume figure draws the loops inside the curve.
- Optional PEEPi and a modified Campbell diagram. Off by default: measures intrinsic PEEP from the oesophageal pressure deflection before inspiratory flow and reports the extra work it adds, in new columns beside the existing ones. Existing columns and the standard Campbell diagram are 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, expressed 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 placed by hand in Preview & QC, at the onset of every burst of inspiratory EMG found automatically, or in fixed windows. Every segment reports its own neural timing. The noise reference for the EMG noise reduction can be taken from the periods between the bursts. The automatic 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 now computed on the conditioned volume rather than the raw column, so the values of such an analysis change without anything else having been changed. A new option computes entropy on the integrated volume when the volume has no column of its own. Flow and pressure columns, and every analysis without entropy on volume, are unchanged.
- Saved analyses: an analysis that uses the new settings must not be opened and saved by a RespMech from before this release, which would drop the tables it does not know.
- Sample entropy’s default Template length (m + 1) has changed from 2 to 3. The previous default of 2 reported a sample entropy computed at m = 1, not the m = 2 that is the near-universal convention in the sample-entropy literature (Richman & Moorman 2000; Yentes et al. 2013). Any analysis that leaves this field unset will report a different sample entropy value once this reaches a release. Set the field to 2 to reproduce entropy values from an analysis run before this change; every other Setup field, and every other measurement, is unaffected. See The Sample-entropy card and How RespMech computes it for the full explanation, the corrected literature interval for the tolerance r, and the pyEntropy/Richman & Moorman credit.
- Two new checks catch a bad recording before you run it, instead of only
surfacing as a confusing downstream error. A recording whose time column has
duplicated or decreasing timestamps — the signature of more than one recording (for
example several LabChart blocks) exported into one file and merged row-by-row — is
now flagged by name, both in the Setup QC strip and in
respmech validate. So is an assigned channel (flow, Poes, Pgas, Pdi, an EMG channel, or an entropy channel) that never varies across the whole recording, most often a mis-assigned or unused column; a constant flow channel specifically now stops the file immediately with a named error, since breath segmentation cannot make progress on a flow signal that never changes. A degenerate-breath error in the middle of a recording no longer blames “the start or end” either — it names the breath’s own timestamp and the more likely causes instead. See the troubleshooting section for the full detail.
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 — and 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.