MEP-CMAP Analyser

Version 1.3.3 | August 2026
Author: Justin Andrushko PhD, Northumbria University

Collaborators: David Cunningham PhD (TMS Analysis ToolBox) · Nicholas Holmes PhD · TMSMultiLab

PyPI: https://pypi.org/project/mep-cmap-analyser/
GitHub: https://github.com/jandrushko/mep-cmap-analyser
Bug reports: https://github.com/jandrushko/mep-cmap-analyser/issues

A BIDS-compliant, open-source, cross-platform desktop tool for processing, quantifying, and group-analysing TMS/EMG neurophysiology recordings. Built for researchers who need reproducible, auditable waveform analysis without writing custom scripts for every study — and extensible with community add-ons for analyses the core tool doesn't yet cover.

Overview

MEP-CMAP Analyser is a GUI pipeline for EMG data collected with transcranial magnetic stimulation (TMS) and peripheral nerve stimulation (PNS) paradigms. It is organised around a neuroimaging-style first-level / second-level workflow:

• Setup — open a dataset, manage the file queue, and (optionally) convert raw recordings into a BIDS-compliant layout.
• First Level: Single File — process individual recordings: filter, segment trials around stimulation events, detect and quantify response features, review per trial, and run optional analysis add-ons.
• Second Level: Group — merge all processed sessions into a single, statistics-ready table for mixed-effects modelling, and run optional group-level add-ons.

Every setting, decision, and manual edit is saved in a sidecar JSON so analyses are fully reproducible and can be re-run or audited at any time.

The tool is not limited to any single measure or paradigm. It handles motor evoked potentials (MEPs), compound muscle action potentials (CMAPs), cortical silent periods (cSPs), M-wave recruitment curves, paired-pulse protocols such as SICI and ICF, and any other time-locked EMG response measurable by peak-to-peak amplitude, onset latency, or area under the curve. It operates on continuous recordings, pre-epoched trial stacks, and EMG bursts recorded without stimulation.

What's New in 1.3.3

Important: reprocess if you use onset latency or AUC. This release fixes two faults that silently produced plausible-looking wrong numbers rather than failing. Onset latencies were clipped by the amplitude-measurement window, and MEP offset (and therefore AUC at rest) frequently failed to detect at all. Amplitude, cSP and normalisation measures are unaffected.

Onset detection no longer depends on the amplitude window. The onset search window was taken from the PTP window, which is a single per-file setting, while the latency profile is per stimulus type. A stimulus type whose profile began before the PTP window start had its onsets pinned to the window edge — measured on a deltoid-like case with a true onset of 8.9 ms, a profile of 8–16 ms and the default 10–50 ms window, every trial returned exactly 10.00 ms with a between-trial SD of zero. Implausibly consistent latencies are the signature, which makes this considerably more dangerous than a detector that returns nothing. The search window is now derived from the latency profile, widened by the PTP window, and the log warns whenever onsets collapse onto a search bound.

Four new onset detection methods, bringing the total to seven: an RMS envelope detector with SD-scaled threshold, a CUSUM change-point detector, optional Teager–Kaiser preconditioning, and a consensus method that takes the median across several detectors. See MEP Onset Detection.

MEP offset and duration are now detected and reported, giving MEP_Offset(ms) and MEP_Duration(ms). Where a cortical silent period is detected its start is the end of the MEP and is reported as the offset; where there is none, the return to baseline is detected instead. MEP_Offset_Source records which rule applied. This also gives AUC a principled endpoint in resting-state recordings, where there is no silent period to close the integration window and the endpoint previously had to be dragged by hand.

PTP window anchoring per stimulus type (opt-in). The amplitude window is one setting for the whole file, so a recording containing both M-waves and MEPs cannot be measured correctly by a single window. On a real mixed recording the M-wave conditions had the first 6 ms of every response excluded from the amplitude measurement, understating it by around 20%. Enable PTP Window Anchoring in Preferences → Detection to give each stimulus type a window placed on its own median onset; the 1c window end still applies as a ceiling.

Onset method agreement and comparison outputs. With Compare methods on every trial enabled, every consensus member runs on every trial and the spread between them is reported as Onset_Disagreement(ms) — a direct triage signal for which trials need manual review. The individual latencies are also written to two CSVs and five figure types, including Bland–Altman against a leave-one-out consensus. See Onset Method Comparison.

Analysis and review now use identical detection. The Data Inspector carried its own copy of the onset dispatch. It knew only four methods, so selecting a newer one silently fell through to peak-fraction, and it forwarded no amplitude gate, peak fraction or slope threshold — meaning a re-detection during review could use a different algorithm, and different settings, than the analysis it was reviewing. Both paths now share one implementation.

Preferences carry forward raised defaults. The Preferences dialog writes every field on the tab, so a value you never deliberately chose was stored and then shadowed any later change to that default. Detection settings are now version-stamped and migrated on load, but only where the stored value is still the default it superseded — anything you actually changed is left alone. A Restore detection defaults button covers the rest.

Smaller fixes. The amplitude window fields in 1c are relabelled and now state plainly that they do not constrain onset detection. min_peak_amplitude, peak_fraction and slope_threshold are honoured consistently across the pipeline and the Inspector. Detection defaults are defined in exactly one place, with a test that fails if any consumer drifts from it.

What's New in 1.3.2

Important: reprocess existing derivatives. This release fixes a column-alignment fault that affected every trial-level CSV written by earlier versions. Six columns held the wrong measurement and one was always empty. Any analysis that used the detrended amplitudes or the pooled z-score should be re-run after reprocessing. Peak-to-peak amplitude, latency, AUC, cSP measures and the raw waveforms were never affected.

• Fixed: trial-level columns were shifted by one place. The per-trial rows are built as positional lists, and the code that filled the z-score and detrended fields addressed them by literal index. Those literals were one lower than the column they named, so Z_PTP_Pooled received the detrended amplitude in millivolts, PTP_Detrended_WithinCond(mV) received a z-score, PTP_Detrended_WithinCond_Z received the session-detrended amplitude, PTP_Detrended_Session(mV) received a z-score, PTP_Detrended_Session_Z was never written at all, and Z_PreStimRMS was overwritten with the within-condition PTP z-score. The shift is easy to spot in an affected file: columns labelled (mV) hold values on a z-score scale and vice versa. Every such write now resolves its position from the column list by name, so the layout and the writers cannot disagree again.
• New measure: MEP RMS. Root-mean-square amplitude over the same window as peak-to-peak, written as MEP_RMS(mV) with matching summary columns. Peak-to-peak is determined by two extreme samples and is therefore sensitive to a single spike, while RMS integrates the whole response, so a broad low-amplitude MEP and a narrow spiky one of equal peak-to-peak amplitude are no longer indistinguishable.
• Fixed: two definitions of pre-stimulus RMS. detection.quantification is documented as the single source of truth for scalar trial metrics, but nothing in the codebase actually called it, and its compute_prestim_rms did not remove the DC offset while the pipeline's own version did. The two disagreed by around ten percent on a segment carrying a modest offset, so an add-on that followed the documentation got a value that silently contradicted the PreStimRMS column. compute_prestim_rms now takes demean=True, matching the pipeline and therefore the CSV, and the pipeline delegates to it so there is one implementation. The per-trial PTP, RMS and AUC that reach the trial CSV are now computed through these shared functions as well. Trial values are unchanged; only the standalone helper's default moved, and it moved onto the correct value. compute_rms is exported alongside the others.
• New format: pre-epoched MATLAB trial stacks. Files whose trials are already cut around the stimulus are read directly, rather than requiring a continuous recording with a trigger channel. The analysis windows are clamped to the extent the file actually contains, with the reduction reported in the log, and a warning is raised when the available post-stimulus window is too short for cortical silent period detection. The amplitude unit is confirmed once and saved to a sidecar when the file does not declare one.
• Variability and reliability add-ons — two new built-in add-ons quantifying how much a measure varies from trial to trial, and what that means for study design. variability (first level) reports the coefficient of variation four ways with confidence intervals, robust and log-scale z scores, the precision of a condition mean and how many trials would tighten it, autoregressive structure and within-session drift, single-trial limits of agreement, the typical error and RMSE family, contrasts between conditions, and correlations among trial-level measures. variability_group (second level) decomposes variance into between-participant, between-session, and trial-level components, then turns that into the reliability, SEM, and MDC95 of a measurement averaged over any number of trials and sessions.
• The dispersion family, not just the CV — MAD and IQR are reported alongside the coefficient of variation, each scaled so all three estimate the same quantity under normality and can be read against one another. Skewed amplitudes with occasional very large trials do not honour the assumptions the CV rests on, so the robust alternatives are there to be compared rather than assumed away.
• Raw or log scale, measured rather than assumed — the group add-on regresses log(SD) on log(mean) across recordings. A slope near zero means additive noise and the SD is the meaningful summary; a slope near one means noise scales with amplitude, so the CV is appropriate and the log scale is the natural one to analyse on. The verdict is read off the confidence interval, and reports honestly when the dataset cannot distinguish the two.
• Does the answer depend on the outliers, or on one trial? — every dispersion metric is reported with and without robust-z outliers, side by side with the percentage change, and a leave-one-out jackknife shows how far each single trial moves the estimate. A CV that collapses when one trial is dropped is describing that trial as much as the series, which a summary statistic cannot reveal on its own.
• Do the metrics agree? — the group add-on ranks recordings by each dispersion metric and reports whether the ranking survives the choice. If it does, the choice is a convention; if it does not, it is a finding that needs justifying.
• Reliability separated from change — the group add-on reads your Second Level design and classifies each factor by whether it varies within a participant. Between-participant factors (group, arm) can be split on, so between-session reliability survives inside each stratum; within-participant factors (timepoint) label the session axis instead, because splitting on one would leave a single session per participant. A session pair straddling an intervention is reported as measuring change, not test-retest reliability, since its limits reflect measurement error plus whatever really changed.
• Figure captions — figures now save a plain-language caption beside them, filled with that recording's own numbers, explaining what each panel shows and flagging traps only when the data triggers them (a drift that inflates the CV, or a typical error inflated by trial-to-trial alternation).
• An unusable MNE-Python install is now treated as absent. MNE loads its submodules lazily, so importing it can succeed while its readers cannot load at all, most often a version mismatch against SciPy. Such an install was previously reported as available and then failed at the moment a file was opened. It is now detected up front, so the formats it would have handled are simply not claimed and every native reader is unaffected.
• Dropdown settings for add-ons — ADDON_SETTINGS gained choices and choices_from. A measure to analyse is chosen from a list read from the columns your dataset actually contains rather than typed by hand, and settings declared "type": "bool" render as a checkbox instead of a text box expecting the word True.

What's New in 1.3

• Temporal MEP decomposition add-on — splits each MEP into successive bins from onset (2 ms by default) and aggregates them into an early and a late phase, following the approach used to dissociate fast-conducting corticospinal from slower, polysynaptic cortico-reticulospinal transmission. The analysis window is clamped to the detected MEP offset so the late phase cannot run into the silent period, background EMG is subtracted over each window, and per-condition diagnostic figures show the onset-aligned mean trace and bin profile. Bin width, window length, and the early/late boundary are all settings — the bin profile is the primary output and the boundary is a derived convenience, not a baked-in assumption.
• Add-on results reach the group table — Second Level ▸ Group Analysis now joins per-trial add-on outputs onto the merged table automatically. Any add-on writing File, StimType, and Segment alongside its measurements is picked up with no configuration. The join is additive: core measurements are never overwritten, and a column whose name clashes with an existing one is namespaced after its add-on (for example mepfeatx_Latency(ms)) rather than dropped. A sidecar whose keys match no trials is skipped with a note instead of appending a block of empty columns.
• MEPFeatX outputs are now joinable — the add-on emits a 1-based Segment key matching the core per-trial table, and reports the source file name in File rather than the BIDS prefix. The 0-based Trial index is retained.

What's New in 1.2

• Extensible add-ons framework — drop-in Python modules that run post-hoc on saved results and write their own new files, at two scopes: single-file (first level) and group-level (second level). Ships with a faithful port of MEPFeatX (morphological MEP features), a rectified-area example, and a group-summary example.
• Second Level add-ons tab — group-level add-ons operate on the merged group table.
• Reorganised interface — a clearer two-level tab structure (Setup / First Level / Second Level) with a persistent active-file header and step-by-step first-level sub-tabs (1a–1d + Add-ons).
• Check for updates — Settings → Check for updates queries GitHub Releases and offers an assisted update (pip upgrade, or a link to the download page for compiled builds).
• BIDS-ify — convert non-BIDS recordings into a BIDS-compliant rawdata/ layout with shared, per-file editable stimulation metadata (NIBS BEP037).
• Broader format support — added BIOPAC AcqKnowledge (.acq and .mat), Brainsight neuronavigation exports, BrainVision, and LabChart MATLAB exports.
• Cross-platform polish — readable coloured action buttons on macOS, Windows, and Linux, and consistent font scaling across the interface.

Point releases in the 1.2 series: EDF/BDF files (including BIDS-ify output) now load correctly, plus release-pipeline and repository cleanup.

The Interface

Setup                         First Level: Single File                  Second Level: Group
├── Dataset                   ├── 1a  Labels & Analysis Setup      ├── Group Analysis (LME)
└── BIDS-ify                  ├── 1b  Data Filtering                  └── Add-ons
                               ├── 1c  Feature Detection Setup
                               │       (+ ▶ Run Analysis)
                               ├── 1d  Normalisation (optional)
                               └── Add-ons

The active file, channel, and event marker are shown in a persistent header above the First-Level sub-tabs, so context stays visible as you move between steps.

Features at a Glance

Data Ingestion and Format Support

The tool auto-detects the file format on open (by extension, binary signature, or header sniff) and dispatches to the correct reader. Supported formats:

Spike-2 native (.smr) — requires neo

Native Spike-2 binary files read directly via the Neo library — no text-export step. On first open a dialog identifies the EMG channel and stim/trigger channel; the choice is saved to a sidecar (.smr_config.json) and not asked again. DigMark marker codes (A, B, C, …) are decoded from the event channel and each appears as a separate stimulus type. Neo is installed automatically with pip install mep-cmap-analyser.

Spike-2 text export (.txt)

Exported via File → Export → Text. Waveform channels are read along with DigMark event timestamps; any number of stimulus types and marker codes are supported. I/O is accelerated by the compiled Rust extension (mep_cmap_io).

LabChart text export (.txt)

Auto-detected from the Interval= header. Each recording block is treated as a pre-aligned trial; no trigger channel is required. Rust-accelerated.

LabChart MATLAB export (.mat)

LabChart's MATLAB export is detected by its signature variables and read natively — no LabChart installation required.

ADInstruments CFWB binary (.adibin)

Exported from LabChart via File → Export → ADInstruments Binary. The CFWB format is parsed natively in Rust. Stimulation times are derived from a trigger/TTL channel auto-detected by name (stim, trig, ttl). Rust-accelerated.

BIOPAC AcqKnowledge (.acq)

Native BIOPAC AcqKnowledge acquisition files, read via bioread. Channels and event markers are decoded directly from the file.

BIOPAC AcqKnowledge MATLAB export (.mat)

AcqKnowledge's MATLAB export, detected by its signature variables and read without a BIOPAC installation.

Pre-epoched MATLAB trial stack (.mat)

Recognised by its per-trial structure rather than a continuous time series: trials are already cut around the stimulus, so no trigger channel is needed and the stimulus sits at a fixed sample index within every epoch. Because the file contains data only inside its own epochs, the pre- and post-stimulus analysis windows are clamped to what actually exists and the reduction is reported in the log; a window that cannot support cortical silent period detection is flagged rather than silently producing unreliable values. Where the export does not declare an amplitude unit, it is confirmed once on first open and saved to a sidecar.

Brainsight neuronavigation export (.txt)

Brainsight TMS neuronavigation session exports are recognised by their header signature, with stimulation events taken from the navigation record.

BrainVision (.vhdr / .vmrk / .eeg)

The BrainVision Core Data Format, resolved via the sibling .vhdr header and .vmrk markers.

KinEMG / NI-DAQ CSV

NI-DAQ / KinEMG CSV exports; sampling rate and channel names (Dev1/ai0, …) are read from the file header.

Generic Format Wizard (.txt, .csv)

For any other tabular text file (tab, space, or comma delimited). A one-time, four-step wizard configures column-wise layouts (rows = samples, columns = channels) or row-wise layouts (rows = channels, e.g. Delsys Trigno with one continuous TTL row and one EMG row), auto-detecting header lines, channel-name rows, and embedded sampling-rate metadata. Per-channel roles (EMG / Stim-Trigger / Ignore) are assigned once and saved to a sidecar; subsequent opens load instantly.

Format detection summary

New formats are easy to add: a single formats/<name>.py module with three public functions, plus two lines in io.py.

Signal Processing

• Bandpass filter (default 20–450 Hz, adjustable) using Butterworth or Chebyshev Type I designs, with independent highpass and lowpass orders
• Notch filter at any frequency (e.g. 50 or 60 Hz) with adjustable Q factor
• Humbug-style mains-noise canceller with configurable harmonic count
• Real-time filter preview showing frequency response and a wavelet time-frequency decomposition of the raw signal
• A Confirm filter settings step advances the guided first-level workflow from filtering to feature detection

Trial Segmentation

• Configurable pre-stimulus and post-stimulus windows (ms)
• Per stimulus-type gap parameter to skip the TMS artefact period before onset search
• Multi-stimulus support within a single recording: every marker/event label gets its own settings, colour, and output columns
• Stim times sourced from DigMark timestamps (Spike-2), interval resets (LabChart), TTL/trigger rising edges (CFWB, generic TTL rows), event markers (BIOPAC, BrainVision, Brainsight), or manual entry

Response Quantification

MEP Onset Detection

Seven detection methods are available. The global default is set in Settings → Preferences → Detection and can be overridden per file in 1a without affecting the preference. All methods share the same physiological latency bounds (see Physiological Latency Profiles) and return None rather than a floor value when no confident onset is found, so ambiguous trials are flagged rather than silently mislabelled.

The latency profile governs onset detection, not the amplitude window. The search window is derived from each stimulus type's profile, widened by the amplitude window, and floored at the artefact blanking period. When most onsets in a condition land on a search bound the log says so — that pattern means the profile is wrong for the muscle, and the resulting latencies are a window edge rather than a measurement.

Derivative-based — Bigoni et al. 2022 (default) — onset is the start of the longest sustained positive-derivative run on the rising edge, with optional Savitzky–Golay pre-smoothing. It assumes nothing about background EMG level, so it suits both resting and active-contraction paradigms and biphasic waveforms of either polarity. Follows Bigoni et al. [6], adapted for variable sampling rates and muscle-group windows.

Derivative-based + walkback — as above, then walks the onset back to the point of departure from baseline. Use when the plain method lands mid-rise.

RMS envelope + SD threshold — a moving-window RMS envelope against a threshold of baseline mean + k × SD, with the minimum duration calibrated against the chance distribution of above-threshold run lengths rather than fixed by hand. The envelope crossing is treated as a coarse anchor and the onset is re-detected on a much shorter window, so the result is largely insensitive to the smoothing width — the usual criticism of this method class. Most precise on a quiet baseline; like every threshold method it degrades when background EMG is high.

CUSUM change-point — accumulates the running excess over the baseline mean and reports the point at which the mean changed, rather than the point at which the signal crossed a level. The change point is estimated by backtracking to where the accumulator was last zero, so it does not inherit the delay between the true change and the moment enough evidence had accrued. Tolerant of raised background EMG.

Teager–Kaiser preconditioning (option on the envelope and CUSUM methods) — applies the Teager–Kaiser energy operator before detection, amplifying components that are both large and fast-changing. Sharpens the contrast of the transition rather than the amplitude, which helps most at low signal-to-noise ratio.

Consensus — runs several detectors and reports the median of those that find an onset. Slower, but the spread between members is reported as Onset_Disagreement(ms), which flags the trials worth reviewing by hand. Members are chosen in Preferences.

Peak-fraction — finds the largest positive and negative peaks, then scans back from the dominant peak to where the signal first crosses a fraction of it (default 15%), with a minimum-amplitude guard. Best on clean, high-amplitude responses with a near-silent baseline.

Bootstrap threshold (legacy) — retained so analyses run on v1.3.x and earlier reproduce exactly. Its threshold is clipped to a multiple of the baseline mean, which overrides the SD scaling and places onsets systematically early; prefer the RMS envelope method for new work.

Amplitude and duration guards

The envelope and CUSUM detectors apply a width guard: a candidate onset is rejected unless the response stays elevated for a minimum duration. Smoothing widens a single-sample artefact — a cable transient, an electrical spike — into an excursion as wide as the smoothing window, which then satisfies any shorter run-length criterion. Amplitude- and energy-based detectors need this guard; derivative-based ones largely do not.

MEP Offset and Duration

MEP_Offset(ms) marks the end of the evoked response and MEP_Duration(ms) is the interval from onset to offset. One precedence rule is applied, and MEP_Offset_Source records which branch fired, so no value's provenance has to be inferred:

During voluntary contraction the end of the MEP and the start of the silent period are the same physical event, so they are reported as the same number rather than as two near-duplicate estimates. cSP_MEP_Offset(ms) is retained unchanged for backward compatibility; prefer MEP_Offset(ms) in new analyses, since it is also populated at rest.

The return threshold is the larger of a baseline-derived level and a fraction of the response's own peak envelope (default 12%). A purely baseline-derived threshold is an absolute level, and on a quiet resting recording it is a very low one: real EMG does not settle back to resting-quiet within tens of milliseconds after a large response, so such a threshold fails worse the cleaner the trial. Scaling the criterion to the response removes that.

Detecting the offset also gives AUC an endpoint in resting-state recordings. Where there is no silent period to close the integration window, AUC now runs from onset to the detected offset instead of requiring the endpoint to be dragged by hand.

PTP Window Anchoring

Off by default. The amplitude window in 1c is one setting for the whole file, but each stimulus type has its own latency profile. A recording containing both M-waves and MEPs cannot be measured correctly by a single window: with a 10 ms start, an M-wave beginning at 4 ms has most of its response excluded from the amplitude measurement, and an M-wave's entire biphasic deflection lasts only 5–15 ms.

With anchoring enabled, each stimulus type gets an amplitude window placed on its own median detected onset — not per trial, which would make amplitude a function of onset-detection error and leave trials without an onset with no amplitude at all. The condition median keeps the window identical for every trial in the condition, so within-condition amplitudes stay comparable. The 1c window end still applies as a ceiling, and stimulus types with too few detected onsets fall back to the file-wide window. The window chosen for each condition is printed to the log rather than changing silently.

Onset Method Comparison

With Compare methods on every trial enabled, every consensus member runs on every trial regardless of which method is selected — so a method choice can be justified while still running the one you trust. Beyond the per-trial agreement columns, this writes:

• <prefix>_onset_methods.csv — long format, one row per trial × method, including rows where a method failed, so detection rate stays recoverable
• <prefix>_onset_method_summary.csv — per stimulus type × method: detection rate, latency statistics, bias and 95% limits of agreement
• figures/<prefix>_onset_methods_figures/ — per condition, where each method's onset lands on the actual waveform with per-trial onsets beneath; latency by method across the file; Bland–Altman of each method against the others; and the distribution of disagreement

Bland–Altman uses a leave-one-out consensus: the method under test is excluded from the median it is compared against. Comparing a method with a composite that contains it is a part-whole comparison, which drags the bias toward zero and narrows the limits, flattering every method. On real data this understated the limits of agreement by around a quarter.

Agreement is not accuracy. Detectors that share an assumption can be wrong together, and the two derivative variants are not independent — the walkback starts from the plain method's answer. Read the spread as the practical consequence of a method choice; establishing which method is correct requires ground truth, not agreement.

Cortical Silent Period (cSP) Detection

A vectorised bootstrap method: a silence threshold is estimated from the pre-stimulus baseline and a search runs from a configurable offset after MEP onset. Configurable criteria include minimum silence duration (default 25 ms), minimum EMG-return window, bootstrap criterion (default 1.96 SD), significance level (default 99th percentile), search-window end, and maximum MEP-to-cSP offset. cSP detection can be enabled/disabled per stimulus type and overridden per trial in the Data Inspector. The 1c Feature Detection Setup tab exposes all of these with inline guidance.

M-wave Normalisation and Mmax

A separate Mmax file can be designated containing M-waves across a range of intensities. The plateau region is detected robustly for three scenarios: a full recruitment curve (averages the plateau within a tolerance band, default ±10%), a few supramaximal pulses (averages the largest similar-amplitude cluster), or a single M-wave (used directly). Normalised PTP is then reported for all MEP trials as a fraction of Mmax.

For designs where the background excitability of spinal motoneurones varies across trials, for example active-contraction paradigms, the tool also compensates evoked-potential magnitude for pre-stimulus excitability by quantile regression, following the method of Carson (2026) [9], as an alternative or complement to Mmax normalisation.

EMG Excitability Compensation (Carson 2026)

MEP amplitude covaries positively with the level of background EMG in the period immediately preceding the pulse, over a range far below any conventional rejection threshold. Rather than discarding trials, the amplitude is regressed on pre-stimulus r.m.s. EMG by median quantile regression within each sample (one participant, one stimulus type, one intensity, one block), and each trial's residual is re-expressed relative to an uncertainty-weighted reference value. The reference blends the regression intercept with the median of the fitted values, weighted by the relative standard error of the fitted ordinate at each point, so where no association is present the adjustment vanishes.

The implementation is verified against the author's own reference code and example data (annotated_QR_example_code.R, Zenodo 20037178); tests/test_carson_compensation.py locks the slope, intercept, intercept weighting and reference value to his published values.

Reported per trial:

Two points worth knowing when reading the output. First, adjusted amplitudes larger than unadjusted are expected, not a fault: within any sample the low-RMS trials always shift upward, and a whole sample shifts upward whenever EMGComp_Slope is negative (74 of Carson's 182 participants). Second, the per-trial shift is exactly reference - (intercept + slope * PreStimRMS), so plotting Adjusted_PTP_QR(mV) - PTP(mV) against PreStimRMS must give a straight line with slope -EMGComp_Slope. That is the quickest check that a suspicious file is behaving correctly. Before comparing adjusted values across conditions, check that the slopes and intercepts are comparable, as the paper recommends.

Background EMG is quantified as the r.m.s. of a prestim_ms window (default 100 ms) ending rms_guard_ms before the pulse (default 3 ms, matching the paper, and widened automatically if a stimulus type needs a longer artefact gap). The window's DC offset is removed first, since an offset is not motoneurone activity and carrying it into the r.m.s. adds between-trial variance that masks the association the method exists to remove.

Compensation is skipped for M-wave runs, which are direct muscle responses rather than spinally mediated, and typically span multiple intensities. Trials marked Removed or Excluded are left out of the fit and receive no compensation values; trials flagged by the z-screen but kept by the reviewer stay in, since retaining datapoints is one of the stated benefits of the method.

Paired-Pulse Protocols

Any stimulus type can be designated as a conditioned stimulus and paired with a reference in 1a. Conditioned/reference ratios (e.g. SICI at 2–6 ms ISI, ICF at 10–15 ms ISI) are produced as a standard output column, with multiple reference assignments supported within a single file.

Outlier Detection and Review

• Z-score flagging on PTP amplitude and RMS with a configurable threshold (default ±1.96)
• Interactive review dialog showing the flagged waveform in context, with include / exclude / note options
• Decisions persist across reruns — reviewed trials are not re-presented — and are recorded in the trial CSV's Outlier_Decision column

Data Inspector

Per-trial interactive review with a zoomed trial view plus a wider context window; draggable onset, cSP-start, and cSP-end markers; a drag-to-select AUC window; per-trial notes; and keyboard navigation. All edits are saved to the session JSON and applied on every subsequent run without re-review.

Add-ons (Extensible Analyses)

Add-ons are optional, drop-in Python modules that run after processing, read the saved results, and write their own new files — they never modify core outputs. They come in two scopes:

• First-level (single-file) add-ons run on each recording's saved waveform bundle (<prefix>_segments.npz) and appear on the First Level → Add-ons tab.
• Second-level (group-level) add-ons run on the merged group table (group_level_LME_ready.csv) and appear on the Second Level → Add-ons tab.

Built-in add-ons:

Add-ons can declare their own settings, which render as controls in the add-on's box — a checkbox, a numeric field, or a dropdown, according to what the add-on declares (for example, MEPFeatX exposes a tunable noise-gate ratio for handling MEPs recorded during voluntary contraction, and the variability add-ons offer a measure picked from the columns your dataset actually contains). Point the tool at your own add-ons folder in Settings → Preferences → Add-ons; place first-level add-ons in a single_file/ subfolder and group-level add-ons in a group_level/ subfolder. See Writing Add-ons.

BIDS-ify

The Setup → BIDS-ify tab converts non-BIDS recordings into a BIDS-compliant rawdata/ layout. Shared stimulation metadata (following the NIBS BEP037 proposal) is edited once and applied to every file, with per-file overrides where needed. Files are reviewed, accepted, and converted from a persistent, status-coloured worklist, so a whole study can be brought into BIDS in one pass.

Session Persistence and Reproducibility

Every setting the user touches — filter parameters, time windows, onset method, latency maps, cSP thresholds, normalisation references, Inspector edits, outlier decisions, analysis options — is saved in a per-file session JSON alongside the derivatives. Reloading restores the exact state; changing a setting and re-running produces a clean new result without losing manual review work. File paths in session JSONs are stored relative to the study root for portability across machines and cloud sync.

Dataset Queue

• Open a study folder or individual files; the tool auto-detects BIDS rawdata/ and derivatives/ subfolders
• A persistent queue tracks status (Not Started, In Progress, Needs Review, Complete, Stale)
• Excluded files are remembered and not re-added on refresh; a right-click menu restores them, marks files for reprocessing, or opens the derivatives folder
• Process a highlighted recording with Run selected
• Queue state is saved to dataset_session.json

Check for Updates

Settings → Check for updates queries GitHub Releases in the background, compares the latest version to the one you're running, and — if you're behind — shows the release notes and offers an assisted update: a pip install --upgrade for source/pip installs, or a link to the download page for compiled builds. It fails gracefully offline and falls back to version tags if no formal release is published.

Supported Use Cases

The tool handles any paradigm where a time-locked EMG response is expected within a defined post-stimulus window, including but not limited to:

• TMS MEP studies — single-pulse, paired-pulse (SICI, ICF, LICI, SAI), or multi-intensity recruitment curves; any accessible muscle
• Peripheral nerve stimulation CMAPs — M-wave recruitment curves for Mmax determination or peripheral conduction
• Corticospinal excitability assays — resting and active MEP series, pre/post intervention, crossover and parallel designs
• TMS-EMG silent period studies — cSP duration, cSP/MEP ratio, and derived inhibitory indices
• MEP waveform morphology — via the MEPFeatX add-on (turns, phases, thickness, T1/T2)
• Re-analysis of pre-epoched datasets — trial stacks exported from another pipeline or downloaded from a public repository, where no continuous recording is available
• Voluntary EMG bursts — files with no stimulation events can be loaded for waveform inspection, RMS quantification, and trial-level output

Installation

Option 1: pip (recommended for most users)

pip install mep-cmap-analyser
mep-cmap

Python 3.9 or later is required. Tkinter must be available:

• Windows / macOS — included with standard Python installers
• Linux (Ubuntu / Debian) — sudo apt install python3-tk

Option 2: Compiled binaries (no Python required)

Pre-built builds for each platform are on the Releases page. Download, unzip, and run.

Apple Silicon Macs are M1 and later; choose the Intel build for anything older. If you pick the wrong one macOS reports a "bad CPU type in executable" error — download the other file rather than anything else being wrong.

First launch on macOS

The macOS app is not notarized by Apple, so the first time you open it macOS will refuse and may claim the app is damaged. Nothing is damaged: this is Gatekeeper blocking any app downloaded from the internet that has not been through Apple's paid notarization service. Two ways past it, both one-time:

• Right-click (or Control-click) the app, choose Open, then Open again in the dialog. This records your consent and normal double-clicking works from then on.

• Or clear the download quarantine flag from Terminal:

  xattr -dr com.apple.quarantine "MEP-CMAP Analyser.app"
  

If neither works, macOS may have quarantined the zip's contents on extraction — move the app to /Applications first, then repeat.

Running from source (Option 3) or installing from PyPI (Option 1) avoids Gatekeeper entirely and is the simplest route on macOS.

Option 3: Run from source

git clone https://github.com/jandrushko/mep-cmap-analyser.git
cd mep-cmap-analyser
pip install -r requirements.txt
python -m mep_cmap

Workflow

1. Setup → Dataset

Open a study folder or an individual recording. The tool auto-detects a BIDS layout (rawdata/ beside derivatives/) or sets up a derivatives folder in the standard location. Files appear in the queue with their status; double-click any file to load it, or highlight one and click Run selected. Opening an unrecognised format launches the Format Wizard for a one-time configuration.

2. Setup → BIDS-ify (optional)

If your data isn't yet in BIDS, use BIDS-ify to set shared stimulation metadata and convert the ready files into a rawdata/ tree.

3. First Level → 1a Labels & Analysis Setup

For each stimulus type in the recording, configure the display label and colour, the artefact gap (ms), whether to run cSP detection, the stimulus category and target muscle (which set physiological latency bounds), and any normalisation/paired-pulse reference pairing. Click ✔ Confirm Setup when ready. Settings carry over between files.

4. First Level → 1b Data Filtering

Set bandpass, notch, and Humbug options, preview the filter, then click ✔ Confirm filter settings → Feature Detection.

5. First Level → 1c Feature Detection Setup

Set time windows, onset-detection parameters, cSP settings, outlier detection, and analysis options, then click ▶ Run Analysis. The tool extracts trials, quantifies all measures, flags outliers, optionally runs the Data Inspector, and writes results to the derivatives folder. Reloading a processed file offers to reuse the saved crop range, pick a new one, or use the full file, with all prior edits restored.

6. First Level → 1d Normalisation (optional) and Add-ons (optional)

Normalise processed results against a reference file, and/or run first-level add-ons (e.g. MEPFeatX) on the saved bundles.

7. Second Level → Group Analysis (LME)

The tool scans the derivatives folder and lists completed sessions. Assign study-design columns (Group, Condition, Timepoint, or any custom factor), configure stim roles, select sessions to include, and click ▶ Build group analysis file to produce group_level_LME_ready.csv.

8. Second Level → Add-ons (optional)

Run group-level add-ons (e.g. group_summary) on the merged group table.

Output Files

Results are written to a derivatives/ folder beside the raw data, following BIDS derivative conventions:

study/
├── rawdata/
│   └── sub-001/ses-01/sub-001_ses-01_recording.txt
└── derivatives/
    ├── dataset_session.json               ← file queue and processing status
    ├── study_design.json                  ← Second-Level design configuration
    ├── group_level_LME_ready.csv          ← merged group output (Second Level)
    ├── group_level_LME_ready_*.csv        ← group-level add-on outputs
    └── sub-001/
        └── ses-01/
            ├── sub-001_ses-01_session.json           ← full session state
            ├── results/
            │   ├── sub-001_ses-01_<StimType>_trials.csv   ← one per stim type
            │   ├── sub-001_ses-01_..._segments.npz        ← waveform bundle (add-on input)
            │   ├── sub-001_ses-01_..._variability.csv     ← per-trial add-on output (joins into the group table)
            │   ├── sub-001_ses-01_..._onset_methods.csv   ← per trial × method (agreement enabled)
            │   ├── sub-001_ses-01_..._onset_method_summary.csv
            │   └── ...                                    ← add-on outputs, e.g. *_mepfeatx.csv
            └── figures/                                   ← add-on figures, each saved with a *_caption.txt
                └── sub-001_ses-01_onset_methods_figures/  ← onset method comparison figures

Trial-level CSV columns

Each <prefix>_<StimType>_trials.csv contains the full column set below. Which columns are populated depends on what you enabled — cSP columns fill only when cSP detection is on, normalisation columns when a reference file is set, and the excitability-compensation block when that option is run.

Group-level LME-ready CSV

Every trial-level column from every included session, prefixed with design columns — participant_id, session, task, timepoint, Stim_Role, and any custom between/within-subject factors defined at the second level. Output is at the trial level (outliers retained with their Z-scores as covariates rather than pre-excluded), so the analyst keeps full control of trial-level modelling. Per-trial add-on outputs are joined on automatically (see Writing Add-ons), so columns such as the variability add-on's robust z scores arrive alongside the core measurements and can be used as covariates. This file is also the input for group-level add-ons.

Physiological Latency Profiles

The derivative-based (Bigoni), bootstrap, and peak-fraction onset detectors all search within a per-muscle physiological window. Defaults assume contralateral cortical stimulation with active facilitation (resting latencies are typically 1–3 ms longer). Windows can be overridden per stimulus type in 1a, and the global defaults edited in Settings → Preferences → Latency Profiles.

Notes. Latency scales positively with height and age, particularly for lower-limb muscles. The lower bound excludes the TMS artefact; the upper bound captures the ±2 SD range of normative cohort data while avoiding late oligosynaptic MEPs. The trunk window is anchored to the contralateral onset latency of 15.8 ± 1.4 ms reported by Miyano et al. [3].

Writing Add-ons

An add-on is a small Python module exposing an ADDON_NAME, an optional description/version/author, an optional ADDON_SCOPE ("single_file" or "group_level"), optional ADDON_SETTINGS, and a run(context) function. It reads from the context and writes new files into context.results_dir.

First-level (single_file) add-ons receive a context with the per-trial waveforms grouped by stimulus type, sampling rate, unit, a stimulus-aligned time axis, the per-trial table, the analysis config, and output paths:

ADDON_NAME  = "my_addon"
ADDON_SCOPE = "single_file"

def run(context):
    import os, numpy as np
    rows = []
    for stim_type, stack in context.segments.items():   # stack: (n_trials, n_samples)
        for i, trace in enumerate(stack):
            rows.append((stim_type, i, float(np.ptp(trace))))
    out = os.path.join(context.results_dir, f"{context.bids_prefix}_my_addon.csv")
    # ... write `rows` to `out` ...
    context.log(f"my_addon → {os.path.basename(out)}")
    return [out]

Second-level (group_level) add-ons receive context.group_table (the merged group DataFrame), with design_columns / metric_columns split out for convenience:

ADDON_NAME  = "my_group_addon"
ADDON_SCOPE = "group_level"

def run(context):
    import os
    summary = context.group_table.groupby("StimType")[context.metric_columns].mean()
    out = os.path.join(context.results_dir, f"{context.bids_prefix}_my_group_addon.csv")
    summary.to_csv(out)
    context.log(f"my_group_addon → {os.path.basename(out)}")
    return [out]

Add-on settings

An add-on may declare ADDON_SETTINGS, a list of dictionaries that render as controls in the add-on's box. Each value is passed into context.config under its key when the add-on runs.

ADDON_SETTINGS = [
    {
        "key": "my_addon_metric",
        "label": "Measure to analyse",
        "help": "Trial-level column to quantify.",
        "type": "str",
        "default": "PTP(mV)",
        "choices": ["PTP(mV)", "AUC(mV*s)"],   # fallback list
        "choices_from": "trial_columns",        # real columns when a dataset is open
    },
    {
        "key": "my_addon_plot",
        "label": "Write figures",
        "type": "bool",
        "default": False,
    },
]

An unrecognised type falls back to a plain text box, so an add-on written for a newer version still loads on an older build.

Computing the same measurements the pipeline does

Add-ons and external scripts should quantify amplitudes through the shared helpers rather than reimplementing them, so their numbers agree with the trial CSVs:

from mep_cmap.detection import (compute_ptp, compute_rms, compute_auc,
                                compute_prestim_rms, compute_prestim_ptp)

ptp = compute_ptp(segment, start_idx, end_idx)      # peak-to-peak in a window
rms = compute_rms(segment, start_idx, end_idx)      # RMS over the same window
auc = compute_auc(segment, onset_idx, end_idx, fs)  # area under rectified EMG
base = compute_prestim_rms(prestim_segment)          # DC offset removed

compute_prestim_rms removes the DC offset by default, which is what the PreStimRMS column contains and what the Carson (2026) compensation expects. Pass demean=False only if the raw, offset-inclusive r.m.s. is specifically what you want.

Getting per-trial results into the group table

Second Level ▸ Group Analysis left-joins any CSV sitting beside <prefix>_trials.csv that carries the join keys StimType and Segment (plus File when present). Segment is 1-based, matching the core trial table, and File must be the source file name as it appears there rather than the BIDS prefix.

The join is additive and safe: a column whose name already exists in the core table arrives namespaced after its add-on rather than overwriting it, and the merge is validated one-to-one, so a sidecar must hold exactly one row per (File, StimType, Segment). A sidecar whose keys match no trials is skipped with a note instead of appending empty columns.

Output that is not per trial — a per-condition summary, a contrast table — simply omits Segment and is left alone by the join. Avoid ending such a file's name with _summary.csv, which is reserved for core outputs.

Put your modules in the matching subfolder (single_file/ or group_level/) of the add-ons folder set in Settings → Preferences → Add-ons. The built-in add-ons are good starting templates: rectified_area and group_summary are deliberately minimal, mepfeatx and temporal_decomposition show per-trial output that joins into the group table, and variability shows settings, dropdowns, figures, and captions.

Building from Source

# Windows
python build_windows.py

# macOS
python3 build_mac.py

# Linux
python3 -m venv venv_linux && source venv_linux/bin/activate
pip install -r requirements.txt
python3 build_linux.py

The build scripts create a local virtual environment, compile the Rust I/O extension (mep_cmap_io) if a Rust toolchain is present, and run PyInstaller with the platform spec. The bundled add-ons and BIDS schema ship automatically.

Dependencies

The optional Rust extension mep_cmap_io provides accelerated I/O for the Spike-2 text, LabChart text, Generic TSV, and CFWB binary formats; all formats fall back to pure Python if it is unavailable.

Citation

If you use MEP-CMAP Analyser in published research, please cite:

Justin W. Andrushko. (2026). jandrushko/mep-cmap-analyser: MEP-CMAP Analyser (Version v1.3.3) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21810844 Northumbria University. https://github.com/jandrushko/mep-cmap-analyser

References

[1] Groppa, S., Oliviero, A., Eisen, A., Quartarone, A., Cohen, L.G., Mall, V., Kaelin-Lang, A., Mima, T., Rossi, S., Thickbroom, G.W., Rossini, P.M., Ziemann, U., Valls-Solé, J., & Siebner, H.R. (2012). A practical guide to diagnostic transcranial magnetic stimulation: Report of an IFCN committee. Clinical Neurophysiology, 123(5), 858–882. https://doi.org/10.1016/j.clinph.2012.01.010

[2] Colebatch, J.G., Rothwell, J.C., Day, B.L., Thompson, P.D., & Marsden, C.D. (1990). Cortical outflow to proximal arm muscles in man. Brain, 113(6), 1843–1856. https://doi.org/10.1093/brain/113.6.1843

[3] Miyano, R., Shirota, Y., Kodama, S., Toda, T., & Hamada, M. (2026). Ipsilateral and contralateral cortical control of the external oblique muscles revealed by TMS. Clinical Neurophysiology, 181, 2111400. https://doi.org/10.1016/j.clinph.2025.2111400

[4] Cantone, M., Lanza, G., Fisicaro, F., Bella, R., Ferri, R., Pennisi, G., Waterstraat, G., & Pennisi, M. (2023). Sex-specific reference values for total, central, and peripheral latency of motor evoked potentials from a large cohort. Frontiers in Human Neuroscience, 17, 1152204. https://doi.org/10.3389/fnhum.2023.1152204

[5] Orth, M., & Rothwell, J.C. (2004). The cortical silent period: intrinsic variability and relation to the waveform of the transcranial magnetic stimulation pulse. Clinical Neurophysiology, 115(5), 1076–1082. https://doi.org/10.1016/j.clinph.2003.12.005

[6] Bigoni, C., Cadic-Melchior, A., Vassiliadis, P., Morishita, T., & Hummel, F.C. (2022). An automatized method to determine latencies of motor-evoked potentials under physiological and pathophysiological conditions. Journal of Neural Engineering, 19(2), 024002. https://doi.org/10.1088/1741-2552/ac636c

[7] Hupfeld, K.E., Swanson, C.W., Fling, B.W., & Seidler, R.D. (2021). TMS-induced silent periods: A review of methods and call for consistency. Journal of Neuroscience Methods, 346, 108950. https://doi.org/10.1016/j.jneumeth.2020.108950

[8] Rossini, P.M., et al. (2015). Non-invasive electrical and magnetic stimulation of the brain, spinal cord, roots and peripheral nerves: Basic principles and procedures for routine clinical and research application. Clinical Neurophysiology, 126(6), 1071–1107. https://doi.org/10.1016/j.clinph.2015.02.001

[9] Carson, R.G. (2026). A method of compensating for the excitability of spinal motoneurones when estimating the magnitude of potentials evoked in skeletal muscles. The Journal of Physiology, 604, 5731–5757. https://doi.org/10.1113/JP290979

[10] Nguyen, T.D., et al. (2025). MEPFeatX: feature extraction for motor evoked potentials. Frontiers in Neuroscience, 18, 1415257. https://doi.org/10.3389/fnins.2024.1415257

[11] Hopkins, W.G. (2000). Measures of reliability in sports medicine and science. Sports Medicine, 30(1), 1–15. https://doi.org/10.2165/00007256-200030010-00001

[12] Shrout, P.E., & Fleiss, J.L. (1979). Intraclass correlations: uses in assessing rater reliability. Psychological Bulletin, 86(2), 420–428. https://doi.org/10.1037/0033-2909.86.2.420

[13] McGraw, K.O., & Wong, S.P. (1996). Forming inferences about some intraclass correlation coefficients. Psychological Methods, 1(1), 30–46. https://doi.org/10.1037/1082-989X.1.1.30

[14] Bland, J.M., & Altman, D.G. (1999). Measuring agreement in method comparison studies. Statistical Methods in Medical Research, 8(2), 135–160. https://doi.org/10.1177/096228029900800204

[15] Vangel, M.G. (1996). Confidence intervals for a normal coefficient of variation. The American Statistician, 50(1), 21–26. https://doi.org/10.1080/00031305.1996.10473537

License

MIT License — see LICENSE for details.