MEP-CMAP Analyser

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

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.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.

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.

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

Three 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.

Derivative-based method — Bigoni et al. 2022 (default) — identifies onset as the start of the longest sustained positive-derivative run on the MEP rising edge, with optional Savitzky-Golay pre-smoothing. It makes no assumptions about background EMG level, so it is robust for both resting and active-contraction paradigms and for biphasic waveforms of either polarity. Follows Bigoni et al. [6] with adaptations for variable sampling rates and muscle-group windows. Tuneable: smoothing window (default 2 ms) and minimum positive-run length (default 1 ms).

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

Bootstrap threshold method — estimates a noise threshold from the pre-stimulus baseline via a bootstrap distribution, then scans backward within a physiologically plausible latency window. More sensitive on low-amplitude signals. Latency windows are per stimulus type with published normative defaults.

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.

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 (for example, MEPFeatX exposes a tunable noise-gate ratio for handling MEPs recorded during voluntary contraction). 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)
• 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.

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)
    └── 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)
            │   └── ...                                    ← add-on outputs, e.g. *_mepfeatx.csv
            └── figures/                                   ← add-on figures, e.g. MEPFeatX plots

Trial-level CSV columns (selected)

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. 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]

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 (mepfeatx, rectified_area, group_summary) are good starting templates.

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:

Andrushko, J.W. (2026). MEP-CMAP Analyser (Version 1.2) [Software]. 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] 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

License

MIT License — see LICENSE for details.