Run MEEGqc on a BIDS dataset.

Pick a dataset

Two small BIDS datasets are provided to follow the rest of the tutorial: one MEG, one EEG. Pick either to exercise the full pipeline; use both to also exercise the multi-dataset-level reports.

# MEG (Logical reasoning study, openneuro.ds003483)
datalad install https://github.com/OpenNeuroDatasets/ds003483.git
cd ds003483 && datalad get sub-009/

# EEG (HAD-MEEG, openneuro.ds007353)
datalad install https://github.com/OpenNeuroDatasets/ds007353.git
cd ds007353 && datalad get sub-01/

GUI walkthrough

Launch MEEGqc by double-clicking the desktop shortcut the installer created, or by running meegqc in an activated environment. The main window has two top tabs (QA/QC calculation and QA/QC plotting), plus collapsible Inputs, Output folder, and Log sections, and a Settings... button on each dataset row.

1. Add one or more BIDS datasets in the Inputs section. You can optionally detach the panel into its own window for multi-dataset runs, then click + Add dataset to browse to the BIDS root. Reorder and remove entries, and toggle Use per-dataset configuration as needed.

   

   

   

2. Two separate things called "settings". Don't conflate them:
   • GUI Settings: the app's own preferences (theme, parallel-worker count limit, system info readout). Affects the GUI shell only, not the analysis.

     

   • Analysis settings (the settings.ini editor): what actually drives the pipeline: enabled metrics, channel types, thresholds, GQI parameters, etc. Click Global settings... for a single settings.ini shared across all datasets, or Settings... on a dataset row for a per-dataset override. The dialog is a typed editor over the same settings.ini the CLI consumes (section reference at settings.ini reference below).
     Whichever settings.ini a run uses is saved back as a snapshot and shown in a dedicated Settings tab inside every report, so the parameters that produced a figure travel with it. Numeric fields such as epoch_tmax accept decimal values.
3. Pick an analysis profile (optional). The Mode control switches between Non-profile / New profile / Reuse profile / Latest profile. For sensitivity sweeps, choose New profile and give it an explicit ID. Selecting Non-profile greys out the profile controls.
4. Set parallelism with n_jobs in the QA/QC calculation tab. Each parallel job handles one subject.
5. Run Calculation to compute QA metrics, or click Run ALL (calc + plotting) to compute and generate every report in one shot. The Log panel streams progress.

   

6. Switch to the QA/QC plotting tab to render reports independently. Tick the scopes you want (QA subject reports, QA dataset reports, QA multi-dataset report, QC dataset report(s), QC multi-dataset report) and click Run Plotting.

   

7. Recompute GQI independently with Run GQI in the calculation tab. Each click writes a new attempt file with the exact thresholds used.
8. Point at an output folder (the Output folder panel). By default MEEGqc writes derivatives under <dataset>/derivatives/MEEGqc/; the Output folder override redirects them to a custom root.

   

   

CLI walkthrough

For scripted runs and batch processing. The CLI exposes four entry points; the GUI calls into the same dispatchers under the hood.

mkdir -p ./config
get-meegqc-config --target_directory ./config --filename settings.ini

run-meegqc \
  --inputdata /path/to/bids_dataset \
  --config ./config/settings.ini \
  --n_jobs 4

# Subject + dataset-level QA from one dataset
run-meegqc-plotting \
  --inputdata /path/to/bids_dataset \
  --qa-subject --qa-dataset

# Cross-dataset comparison; --njobs (no underscore) for plotting
run-meegqc-plotting \
  --inputdata /path/ds1 /path/ds2 \
  --qa-multi-dataset --qc-multi-dataset --njobs 4

globalqualityindex \
  --inputdata /path/to/bids_dataset \
  --analysis_mode reuse-profile \
  --analysis_id qa_pass_01

# Then re-render the QC dataset report against the new attempt
run-meegqc-plotting \
  --inputdata /path/to/bids_dataset \
  --qc-dataset --attempt 2

run-meegqc \
  --inputdata /path/ds1 /path/ds2 \
  --config ./config/settings.ini \
  --run-all --all

Multi-dataset with per-dataset overrides

run-meegqc \
  --inputdata /path/ds1 /path/ds2 \
  --subs_per_dataset \
    "/path/ds1::001,002,003" \
    "/path/ds2::all" \
  --config_per_dataset \
    "/path/ds1::./config/ds1.ini" \
    "/path/ds2::./config/ds2.ini" \
  --n_jobs 4

CLI reference

Every flag, grouped by command. Use --help on any command for the runtime version.

run-meegqc (calculation)

run-meegqc-plotting (reports)

globalqualityindex (GQI recomputation)

get-meegqc-config (export settings.ini)

Python API

The dispatchers in meg_qc.test are the same backend the GUI and CLI call. Import them directly to wire MEEGqc into a notebook, a Snakemake workflow, or any larger Python pipeline.

mkdir -p ./config
get-meegqc-config --target_directory ./config --filename settings.ini

from pathlib import Path
import meg_qc

pkg_root     = Path(meg_qc.__file__).resolve().parent
internal_cfg = str(pkg_root / "settings" / "settings_internal.ini")

from meg_qc.test import (
    run_calculation_dispatch,
    run_plotting_dispatch,
    run_gqi_dispatch,
    run_all_dispatch,
)

run_calculation_dispatch(
    dataset_paths=["/path/ds1", "/path/ds2"],
    config_file_path="./config/settings.ini",
    internal_config_file_path=internal_cfg,
    sub_list="all",
    n_jobs=4,
    analysis_mode="new-profile",
    analysis_id="qa_pass_01",
    existing_config_policy="provided",
    processed_subjects_policy="skip",
)

run_plotting_dispatch(
    dataset_paths=["/path/ds1", "/path/ds2"],
    qa_subject=True,
    qa_dataset=True,
    qa_multi_dataset=True,
    qc_dataset=True,
    qc_multi_dataset=True,
    analysis_mode="reuse-profile",
    analysis_id="qa_pass_01",
    njobs=4,
)

run_gqi_dispatch(
    dataset_paths=["/path/ds1", "/path/ds2"],
    default_config_file_path="./config/settings.ini",
    analysis_mode="reuse-profile",
    analysis_id="qa_pass_01",
)

run_all_dispatch(
    dataset_paths=["/path/ds1", "/path/ds2"],
    config_file_path="./config/settings.ini",
    internal_config_file_path=internal_cfg,
    sub_list="all",
    calc_n_jobs=4,
    plot_njobs=4,
    analysis_mode="new-profile",
    analysis_id="qa_pass_02",
    qa_subject=True,
    qa_dataset=True,
    qa_multi_dataset=True,
    qc_dataset=True,
    qc_multi_dataset=True,
)

settings.ini reference

Every behaviour knob in MEEGqc is controlled through settings.ini. Export the defaults with get-meegqc-config, edit the copy, and pass it via --config or load it in the GUI.

[GENERAL]

[Filtering]

[Epoching]

[STD]

[PSD]

[PTP_manual]

[ECG]

[EOG]

[Head_movement]

Reserved section. The block exists in the default settings.ini but has no keys; head motion is toggled by the top-level Head flag in [GENERAL].

[Muscle]

[EEG]

[GlobalQualityIndex]

The GQI math is documented on the metrics page.

Next: a complete map of every file MEEGqc produces below.

Every file MEEGqc produces

A run leaves behind a single, self-describing tree under derivatives/MEEGqc/. Every file name is BIDS-compliant: an alphanumeric desc-<Label> entity followed by the modality suffix (_meg or _eeg) and an extension. This section lists every output, where it lands, and what it holds, so you can read or post-process any of them without opening MEEGqc.

Three writers populate the tree. The calculation module writes the per-recording QA and QC derivatives (TSV + JSON) plus a settings snapshot. The Global Quality Index (GQI) step writes the dataset-level scores. The plotting module writes the interactive HTML reports. Nothing visual is required to keep the data: every report is regenerated from the derivatives.

The derivatives tree

Legacy-mode layout for a dataset that contains MEG recordings (an EEG dataset mirrors this with eeg/ subfolders and _eeg suffixes):

In profile mode the same tree is written under derivatives/MEEGqc/profiles/<analysis_id>/:

Metric output dictionary

Each metric module writes one headline machine-readable table per recording under calculation/{meg,eeg}/sub-XX/. The {Mag,Grad,Eeg} placeholder means one file is written per analysed channel type (for example desc-STDs covers all channel types in one table, while the per-epoch flag tables are split by channel type).

Output classes and paths

Grouped by output class, with the legacy-mode path and its profile-mode equivalent. <label> is a subject label, <N> a GQI attempt number, <id> an analysis profile id.

The four HTML reports

The plotting module renders four report families. All are self-contained: open them in any browser, no MEEGqc install required. Single-dataset reports drop the dataset name from the file name (it is implied by the folder); multi-dataset reports carry a unique run id so repeated runs never collide.

Next: the reports reference or the metrics + GQI page.