From a BIDS dataset to a quality verdict.
MEEGqc turns raw MEG and EEG recordings into auditable quality information at three nested scopes: subject-level, dataset-level, and multi-dataset-level. This page is the conceptual tour. For hands-on commands, jump to the tutorial.
The signal-quality problem
MEG and EEG capture millisecond-scale neural dynamics, but the signals they record are tiny relative to a long list of non-neural sources. Even with well-shielded rooms and good acquisition protocols, every recording arrives with some amount of:
Physiological contamination
Cardiac activity (ECG), eye movements and blinks (EOG), and muscle activity (jaw clenches, neck tension) routinely leak into the recording.
Environmental interference
Mains harmonics (50 / 60 Hz and multiples), site-specific magnetic noise, and ground vibrations show up as narrowband and broadband contamination.
Hardware variability
Sensor instability, drifts, and calibration issues produce noisy or flat channels that need to be flagged before downstream analysis.
Head motion
Even small head movements relative to the dewar (MEG) or cap (EEG) can bias source localisation and add structured residual artifacts after compensation.
Reviewing all of this visually, one recording at a time, does not scale. Once a research group starts automating the review, conventions diverge between laboratories, parameter choices drift between recording sessions and between acquisition sites, and the quality decisions that get made rarely travel with the data: they live inside someone's preprocessing pipeline rather than as standalone, queryable annotations. This is the gap MEEGqc closes.
What MEEGqc is
MEEGqc is an open-source, BIDS-aligned Python toolbox that puts quality assessment (QA) at the front of the workflow, then layers quality control (QC) decisions on top of the QA layer with full traceability between the two.
meg_qc, the
meg-qc distribution on PyPI, the original
run-megqc family of CLI commands) keep the old
name so existing scripts and pipelines keep working.
- QA = systematic measurement. Continuous, unthresholded descriptors of the signal: per-channel and per-epoch distributions, power spectral density (PSD), temporal patterns, spatial patterns, ECG / EOG correlations, muscle-band noise, head-movement traces.
- QC = criterion-based decisions on top of QA. Two layers: (1) per-metric flags, i.e. thresholds applied to the QA outputs to mark noisy / flat channels, high-correlation channels, muscle-event count, etc.; and (2) the Global Quality Index (GQI), a single 0–100 composite score per recording with a transparent penalty breakdown across four families.
Both layers ship two output streams: machine-readable BIDS derivatives (TSV + JSON sidecars) for programmatic re-use and aggregation, and interactive HTML reports for human inspection. The GQI is additionally versioned: each recomputation writes a new attempt file alongside the exact parameters used, so threshold sweeps stay reproducible.
The toolbox is designed to be accessible across user profiles. A graphical interface drives point-and-click operation, a command-line interface enables scripted and automated workflows, and a programmatic Python API lets developers wire MEEGqc into their own pipelines. All three modes route to the same dispatchers, so they behave identically.
Modalities and formats
MEEGqc auto-detects the modality at file load time and routes
each recording through the right pipeline. There is nothing
to configure beyond ch_types in
settings.ini.
EEG-only datasets in native formats and MEG recordings with
embedded EEG channels are both handled.
| Recording | System label | Channels processed |
|---|---|---|
Neuromag / Elekta / MEGIN .fif (incl. OPM exports) | Triux | mag, grad (+ embedded eeg) |
CTF / VSM MedTech .ds | CTF | grad (+ embedded eeg) |
| EDF, BDF, BrainVision, EEGLAB, EGI, Neuroscan, FIF | EEG | eeg |
_eeg.fif (auto-discovered as EEG) | EEG | eeg |
.fif, covers MEGIN / Elekta systems and
optically pumped magnetometer (OPM) exports) and CTF
(.ds, CTF / VSM MedTech).
Yokogawa / KIT (.con / .sqd), Ricoh
(.con), and BTi / 4D Neuroimaging
(.pdf) are not yet supported. Users with those
formats should convert to one of the supported formats first.
For EEG, MEEGqc applies a small set of EEG-specific
preparations when the modality is detected: re-referencing
(default common average, REST or none also available),
electrode-montage assignment (auto-detected from channel
names or set explicitly), and a dedicated 20-100 Hz muscle
band (vs 110-140 Hz for MEG). All of this is driven from
settings.ini; see the
settings reference in
the tutorial.
Main dependencies
MEEGqc builds on the established scientific-Python
neuroscience stack. All dependencies are resolved
automatically by pip install meg-qc or by the
bootstrap installer. The headline pieces:
MNE-Python
Reads every supported MEG and EEG file format and provides the signal-processing primitives MEEGqc applies during preprocessing and metric computation.
ancpBIDS
Walks BIDS datasets lazily, picks up MEG and EEG files by suffix, reads sidecars, and writes derivatives back in a BIDS-compliant layout.
Plotly
Powers the interactive HTML reports: zoomable topomaps, distribution plots, channel x epoch heatmaps, and the rest of the visual grammar.
NumPy + pandas + SciPy
Carry the vectorized numerical work for metric computation and the tabular layer for the machine-readable derivatives.
Numba + joblib
JIT-compile the peak-to-peak metric for speed and
parallelize the calculation and plotting stages across
subjects (controlled by n_jobs).
PyQt6
Renders the desktop GUI shell that exposes the same dispatchers used by the CLI and the Python API.
How it works
MEEGqc follows a modular layered architecture that explicitly decouples data computation from report rendering. Hover over any stage of the diagram below to see what happens at that step. The traversal moves from BIDS inputs on the left through metric computation and report rendering to the two output families on the right.
Analysis profiles
Analysis profiles are how MEEGqc keeps multiple parameter configurations side by side on the same dataset without overwriting each other. They are the unit of reproducibility for sensitivity analyses, threshold sweeps, and parameter comparisons across research groups.
By specifying an analysis mode, you control where derivatives are written and whether prior runs are reused:
| Mode | Behaviour |
|---|---|
legacy |
Classic non-profile layout under
derivatives/Meg_QC/. No namespacing. |
new |
Create or use a profile. With no
analysis_id, MEEGqc auto-generates one;
passing it explicitly is recommended for
reproducibility. |
reuse |
Use an existing profile. Requires an explicit
analysis_id. Useful when a calculation
pass has finished and you only want to re-render or
recompute GQI. |
latest |
Resolve the most recently modified profile automatically. |
In profile mode, derivatives live under:
On top of profiles, the GQI score is independently versioned
by attempt: every globalqualityindex run writes a
new
Global_Quality_Index_attempt_<n>_{meg,eeg}.tsv
alongside a frozen
global_quality_index_<n>.ini snapshot, so
threshold sweeps within a single profile are also auditable.
BIDS-aligned outputs
MEEGqc is BIDS native end to end. Inputs follow BIDS / MEG-BIDS
conventions; outputs land under
derivatives/Meg_QC/ in a layout that downstream
analysis frameworks (MNE-Python, FieldTrip, Brainstorm) can
consume directly. In legacy mode, the tree looks like:
A BIDS-organized dataset is a precondition. If your data isn't in BIDS yet, tools like BIDS Manager can convert it.
Next: installation, the tutorial, or the reports tour.