Metadata-Version: 2.4
Name: meg_qc
Version: 0.9.8
Summary: Tool for automated MEG and EEG data quality control
Author: Karel Lopez Vilaret, Evgeniia Gapontseva, Aaron Reer, Jorge Bosch, Erdal Karaca
Author-email: Karel Lopez Vilaret <karel.mauricio.lopez.vilaret@uni-oldenburg.de>
Maintainer-email: "ANCP Lab, University of Oldenburg" <karel.mauricio.lopez.vilaret@uni-oldenburg.de>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ANCPLabOldenburg/MEGqc
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ancpbids<=0.3.0,>=0.3
Requires-Dist: prompt_toolkit<=3.0.52,>=3.0
Requires-Dist: mne<=1.12.0,>=1.6
Requires-Dist: pandas<=3.0.2,>=2.0
Requires-Dist: plotly<=6.7.0,>=5.18
Requires-Dist: joblib<=1.5.3,>=1.3
Requires-Dist: psutil<=7.2.2,>=5.9
Requires-Dist: matplotlib<=3.10.8,>=3.7
Requires-Dist: pyqt6<=6.11.0,>=6.5
Requires-Dist: PyQt6-WebEngine<=6.11.0,>=6.5
Requires-Dist: pyqtgraph<=0.14.0,>=0.13
Requires-Dist: numba<=0.65.0,>=0.58
Dynamic: license-file

# MEGqc

MEGqc is an open-source, BIDS-aligned toolbox for automated **MEG quality assessment (QA)** and explicit **quality control (QC)** summarization.

It is designed for large cohorts and reproducible workflows, and provides both:
- interactive HTML reports for human inspection, and
- machine-readable derivatives for downstream automation.

## What MEGqc Provides

- **QA-first quality profiling** of raw MEG signal quality before exclusion decisions.
- **Multi-metric coverage** including:
  - standard deviation (STD),
  - peak-to-peak amplitude (PtP),
  - power spectral density (PSD),
  - ECG/EOG-related contamination,
  - high-frequency muscle burden,
  - optional head-motion summaries.
- **Multi-scale reporting** across recording, channel, epoch, subject, dataset group, and multi-sample comparisons.
- **QC support layer** with configurable module-level criteria and a Global Quality Index (GQI).
- **Reproducible execution** with profile-aware outputs and saved settings provenance.
- **Three usage modes**: CLI, GUI, and programmatic dispatchers.

## Requirements

- **Python 3.10**
- MEG data organized according to **BIDS/MEG-BIDS**.

## Installation

### Option 1: Installer-based (recommended for most users)

Download the installer bundle from the [MEGqc releases](https://github.com/ANCPLabOldenburg/MEGqc/raw/main/installers/installers.zip) and follow the platform-specific instructions in the [installation guide](https://ancplaboldenburg.github.io/megqc_documentation/installation/gui.html).

### Option 2: CLI-based (Conda + pip)

```bash
conda create -n megqc-py310 python=3.10 pip -y
conda activate megqc-py310
pip install meg-qc
```

For detailed installation instructions, see the [CLI installation guide](https://ancplaboldenburg.github.io/megqc_documentation/installation/cli.html).

## Quick Start (CLI)

1. Export default config:

```bash
get-megqc-config --target_directory ./config
```

2. Run QA/QC calculation:

```bash
run-megqc --inputdata /path/to/bids_dataset --config ./config/settings.ini
```

3. Build plotting reports:

```bash
run-megqc-plotting --inputdata /path/to/bids_dataset
```

4. Recompute GQI summaries (optional):

```bash
globalqualityindex --inputdata /path/to/bids_dataset
```

5. Run full pipeline in one command (calculation + plotting):

```bash
run-megqc --inputdata /path/to/bids_dataset --config ./config/settings.ini --run-all
```

## Launch GUI

```bash
megqc
```

The GUI uses the same backend logic as CLI dispatchers and writes the same derivative/report outputs.

## HPC and CBRAIN Deployment (Apptainer)

MEGqc can be containerized with [Apptainer](https://apptainer.org/) and deployed
on any Linux HPC system, including **[CBRAIN](https://cbrain.ca/)** — the distributed
computing platform at the Montreal Neurological Institute (MNI) / McGill University,
which MEGqc is being integrated into as part of an active collaboration.

The [`hpc/`](hpc/) folder contains the complete deployment materials:

| File | Description |
|------|-------------|
| [`hpc/MEGQC.def`](hpc/MEGQC.def) | Apptainer definition file (source of truth for building the image) |
| [`hpc/BUILD_APPTAINER_IMAGE.md`](hpc/BUILD_APPTAINER_IMAGE.md) | Build guide: prerequisites, image creation, GUI launch, distribution |
| [`hpc/CLI_REFERENCE.md`](hpc/CLI_REFERENCE.md) | Full CLI reference + CBRAIN/Slurm job script template |

**Quick start:**

```bash
# Build the image
apptainer build MEGqc.sif hpc/MEGQC.def

# Run full analysis on a BIDS dataset
apptainer run --containall \
  --bind /path/to/bids_dataset:/mnt_IN \
  --bind "$PWD/settings.ini":/mnt_config/settings.ini \
  --bind "$PWD/outputs":/mnt_OUT \
  MEGqc.sif \
  --inputdata /mnt_IN --config /mnt_config/settings.ini \
  --derivatives_output /mnt_OUT --analysis_mode new --run-all --all
```

See [`hpc/README.md`](hpc/README.md) for the full overview and attribution.

---

## Typical Outputs

MEGqc writes outputs under BIDS derivatives (default):

- `derivatives/Meg_QC/calculation/` — metric tables + JSON summaries
- `derivatives/Meg_QC/reports/` — interactive HTML reports
- `derivatives/Meg_QC/summary_reports/` — QC summaries including GQI artifacts

## Documentation

- **Installation (Installer-based):** [https://ancplaboldenburg.github.io/megqc_documentation/installation/gui.html](https://ancplaboldenburg.github.io/megqc_documentation/installation/gui.html)
- **Installation (CLI-based):** [https://ancplaboldenburg.github.io/megqc_documentation/installation/cli.html](https://ancplaboldenburg.github.io/megqc_documentation/installation/cli.html)
- **Tutorial:** [https://ancplaboldenburg.github.io/megqc_documentation/book/tutorial.html](https://ancplaboldenburg.github.io/megqc_documentation/book/tutorial.html)
- **HTML Reports guide:** [https://ancplaboldenburg.github.io/megqc_documentation/book/report.html](https://ancplaboldenburg.github.io/megqc_documentation/book/report.html)
- **Full documentation:** [https://ancplaboldenburg.github.io/megqc_documentation/](https://ancplaboldenburg.github.io/megqc_documentation/)

## Source Code

[https://github.com/ANCPLabOldenburg/MEGqc](https://github.com/ANCPLabOldenburg/MEGqc)

## License

MIT License.
