Reports

Reports#

MEGPrep provides two report interfaces:

  • A portable static HTML report generated by the Nextflow workflow.

  • An interactive Streamlit report viewer started with -r or --view_report.

Static HTML Report#

Every MEGPrep run that reaches a MEG milestone writes a static report under:

<output_dir>/static_html_report/

Open the report entry point:

<output_dir>/static_html_report/index.html

The static report can also be regenerated without rerunning the pipeline:

docker run --rm -it \
  -v /data/bids:/input \
  -v /data/out:/output \
  -v /data/smri:/smri \
  cmrlab/megprep:0.0.3 \
  -i /input -o /output --fs_subjects_dir /smri --steps report

The report directory is self-contained and includes copied figures, sidecar files, JSON summaries, CSV summaries, and a config snapshot when available. Subject pages also include a collapsed Task Details table derived from the Nextflow trace file when one is available. If a task failed or was ignored, the page adds Task Failure Details with the error summary and packaged command log excerpts.

Path

Description

index.html

Dataset-level dashboard with workflow diagram, aggregate metrics, subject table, alarm counts, and links to subject pages.

subjects/<recording>.html

Recording-level details for artifacts, ICA, coregistration, epochs, covariance, head model, source reconstruction, and packaged files.

alarms.html

Searchable alarm list across all recordings.

data/dataset_summary.json

Machine-readable dataset summary.

data/subjects.csv

Spreadsheet-friendly subject summary table.

data/subjects/<recording>.json

Machine-readable per-recording summary.

data/nextflow.config.txt

Effective Nextflow config snapshot when MEGPrep can locate one.

data/megprep_run_manifest.json

Workflow mode and run metadata used to render the workflow diagram.

files/<recording>/errors/*.txt

Packaged .command.err, .command.log, and .command.out excerpts for failed or ignored tasks, when available.

files/<recording>/tasks/*.txt

Optional .command.log excerpts for successful tasks when static_task_log_mode = 'all-command-log'.

Task Log Bundling#

By default, MEGPrep copies successful-task .command.log excerpts as well as failed-task command logs so the portable report contains fuller task provenance. Configure this with static_task_log_mode in the Nextflow config, or pass --static_task_log_mode through the Docker entrypoint or Nextflow command.

Value

Behavior

all-command-log

Default. Copy .command.err, .command.log, and .command.out excerpts for failed or ignored tasks, and also copy .command.log for successful tasks.

failed

Copy command logs only for failed or ignored tasks when a smaller report package is preferred.

none

Do not copy .command* logs. The report still shows trace-derived task status, exit code, duration, memory, and hash values.

Example:

docker run ... cmrlab/megprep:<version> \
  -i /input -o /output \
  --static_task_log_mode all-command-log

How to Interpret the Static Report#

Start from index.html:

  1. Review the workflow diagram to verify that the selected steps mode matches the intended run.

  2. Sort the subject table by alarms, bad channels, bad segments, coregistration distance, or epoch rejection rate.

  3. Open subject pages for recordings marked WARN or FAIL.

  4. For artifact alarms, inspect the bad-channel list, bad-segment table, and artifact mask heatmap. The heatmap summarizes where bad channels and bad time segments occur across the recording before opening the more detailed waveform images.

  5. For ICA alarms, inspect marked components, ECG/EOG candidates, component topographies, and ICA overlay/PSD plots.

  6. For coregistration alarms, inspect the staged coregistration figures and confirm that the recording was matched to the correct MRI subject.

  7. If a subject is marked FAIL because a Nextflow task failed or was ignored, open Task Failure Details first, then expand Task Details for the full trace context.

The current report uses static thresholds and measured values. It does not yet include calibrated normative QC scores. See Quality Control Metrics for the complete metric list.

Interactive Streamlit Report#

To view quality control reports through the interactive Streamlit interface, run MEGPrep with Docker and expose port 8501:

docker run --rm -it -p 8501:8501 \
  -v /data/megprep_output:/output \
  cmrlab/megprep:<version> \
  -r

The Docker entrypoint handles mounted output permissions automatically. It starts as root, prepares /output when needed, then drops to the host UID/GID inferred from /input. For report-only runs that only mount /output, the UID/GID are inferred from /output instead, so an existing report directory owned by the submitting user stays writable. If neither mount has the desired owner, pass -e LOCAL_UID="$(id -u)" -e LOCAL_GID="$(id -g)".

Then open:

http://<server_ip>:8501

Use http://localhost:8501 when running locally. The Streamlit report is a viewer and does not run Nextflow preprocessing.

Contents