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

3. Pick an analysis profile (optional). The Mode control switches between legacy / new / reuse / latest. For sensitivity sweeps, choose new and give the profile an explicit ID.
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, QA Group, QA Multi-dataset, QC Group, QC Multi-dataset) 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/Meg_QC/; 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-group

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

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

# Then re-render the QC Group report against the new attempt
run-meegqc-plotting \
  --inputdata /path/to/bids_dataset \
  --qc-group --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",
    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_group=True,
    qa_multisample=True,
    qc_group=True,
    qc_multisample=True,
    analysis_mode="reuse",
    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",
    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",
    analysis_id="qa_pass_02",
    qa_subject=True,
    qa_group=True,
    qa_multisample=True,
    qc_group=True,
    qc_multisample=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: the reports reference or the metrics + GQI page.