Full Workflow

Full Workflow#

The Quickstart intentionally stops at meg_ica because later stages are dataset-specific. A full source-level run needs correct event definitions, noise covariance choices, anatomy matching, and coregistration settings. This page explains when to run each broader workflow mode and what to check before using it.

Docker output ownership is handled by the MEGFlow entrypoint. It prepares mounted output permissions as root, then drops to the host UID/GID inferred from /input before running Nextflow. Report-only runs that only mount /output infer ownership from /output instead. The host output directory does not need to be created in advance. Use -e LOCAL_UID="$(id -u)" -e LOCAL_GID="$(id -g)" if neither mount is owned by the desired output user.

Choose a Configuration Style#

The Quickstart uses a small overlay that contains only the settings needed for an initial quality-control run. That is the easiest way to start. For a planned full analysis, use the complete user-facing template instead:

Download full_workflow.config

full_workflow.config lists every shared MEG import, preprocessing, artifact, ICA, epoch, covariance, anatomy, coregistration, source, and report setting in one file. It intentionally omits environment-specific paths, executors, logging paths, and internal failure strategies.

Edit the template at three levels:

params.megflow.defaults contains the complete policy shared by all datasets.
params.megflow.datasets.<name> contains only differences for one dataset. Use docker_input for a Docker single-dataset run.
recordings inside a dataset contains only differences for recordings selected by a match block.

The effective order is defaults -> dataset -> recording. A value at a more specific level replaces the corresponding shared value; unrelated defaults remain available. Dataset and recording examples are commented out in the template so downloading it does not create an unintended extra dataset.

Use the Full Configuration with Docker#

The image first loads its bundled base configuration. The entrypoint then applies full_workflow.config and finally writes run-specific input, output, and optional anatomy paths supplied on the command line:

image base config -> full_workflow.config -> Docker path/stage options

Mount the downloaded file at a separate read-only path:

docker run --rm -it \
  -v /path/to/bids_or_raw_meg:/input \
  -v /path/to/output:/output \
  -v /path/to/smri:/smri \
  -v /path/to/license.txt:/fs_license.txt \
  -v /path/to/full_workflow.config:/config/full_workflow.config:ro \
  cplmeg/megflow:1.0.0 \
  --config /config/full_workflow.config \
  --input /input \
  --output /output \
  --fs_subjects_dir /smri \
  --fs_license_file /fs_license.txt \
  --resume

Keep the configuration template and image on the same MEGFlow release when possible. Command-line --steps is optional and temporarily overrides the configured stage for that run.

Use the Full Configuration from Source#

Before a source run, add the intended dataset profile and its paths under params.megflow.datasets, then select it with params.megflow.dataset_include. Nextflow loads the repository nextflow.config first and applies the full configuration as a soft override:

nextflow run nextflow/megflow.nf \
  -c /path/to/full_workflow.config \
  -resume

This file is not a standalone replacement for the execution configuration. Do not use Nextflow -C with it, and do not mount it over /program/nextflow/nextflow.config. The source and Docker base files must continue to provide their own paths, executors, logs, profiles, and failure policies.

Recommended Progression#

For a new dataset, use this order:

meg_ica      -> verify continuous preprocessing, artifacts, and ICA QC
anatomy      -> prepare or verify structural MRI outputs, if needed
meg_epochs   -> verify events and epoch rejection
meg_all      -> run covariance, coregistration, forward, and source
report       -> regenerate the static report when outputs already exist

You can run all when the anatomy and MEG settings are already known and you want structural MRI processing plus full MEG processing in one execution.

Run Anatomy Only#

Use --steps anatomy when you only want to prepare structural MRI outputs. This is useful when MEG and MRI are processed at different times, or when you want to inspect FreeSurfer/DeepPrep outputs before source reconstruction.

For a BIDS dataset with T1w images:

docker run --rm -it \
  -v /path/to/bids_dataset:/input \
  -v /path/to/output:/output \
  -v /path/to/smri:/smri \
  -v /path/to/license.txt:/fs_license.txt \
  cplmeg/megflow:1.0.0 \
  -i /input \
  -o /output \
  --fs_subjects_dir /smri \
  --fs_license_file /fs_license.txt \
  --steps anatomy \
  --resume

This writes or updates anatomy derivatives under /path/to/smri and the MEGFlow output directory. After anatomy is ready and the MEG preprocessing QC looks reasonable, run MEG processing with the same --fs_subjects_dir.

Run Through Epochs#

Use --steps meg_epochs after you have checked how events should be created. This stage is where dataset assumptions usually matter most.

For resting-state data, confirm:

epochs.task_type = "resting"
resting.fixed_length_duration
epoch length, rejection by annotation, and optional rejection thresholds

For task data, confirm:

whether events come from mne.find_events or BIDS events.tsv
the correct stimulus channel, event ids, and event labels
tmin and tmax for the intended analysis
baseline, channel picks, and reject thresholds

Example command:

docker run --rm -it \
  -v /path/to/bids_or_raw_meg:/input \
  -v /path/to/output:/output \
  -v /path/to/my_nextflow.config:/config/project.config:ro \
  cplmeg/megflow:1.0.0 \
  --config /config/project.config \
  --input /input \
  --output /output \
  --steps meg_epochs \
  --resume

Run Full MEG with Existing Anatomy#

Use --steps meg_all when:

meg_ica QC looks reasonable.
epoch settings have been checked.
anatomy outputs already exist under fs_subjects_dir.
MEG recording ids can be matched to anatomy subject ids.
covariance, coregistration, and source settings are ready.

docker run --rm -it \
  -v /path/to/bids_or_raw_meg:/input \
  -v /path/to/output:/output \
  -v /path/to/smri:/smri \
  -v /path/to/license.txt:/fs_license.txt \
  -v /path/to/my_nextflow.config:/config/project.config:ro \
  cplmeg/megflow:1.0.0 \
  --config /config/project.config \
  --input /input \
  --output /output \
  --fs_subjects_dir /smri \
  --fs_license_file /fs_license.txt \
  --steps meg_all \
  --resume

Run Anatomy and Full MEG Together#

Use --steps all only when the structural MRI selection and MEG settings are both ready. The anatomy and MEG branches may run concurrently; they join when coregistration and forward/source modeling require the reconstructed anatomy.

docker run --rm -it \
  -v /path/to/bids_dataset:/input \
  -v /path/to/output:/output \
  -v /path/to/smri:/smri \
  -v /path/to/license.txt:/fs_license.txt \
  -v /path/to/my_nextflow.config:/config/project.config:ro \
  cplmeg/megflow:1.0.0 \
  --config /config/project.config \
  --input /input \
  --output /output \
  --fs_subjects_dir /smri \
  --fs_license_file /fs_license.txt \
  --steps all \
  --resume

If no structural T1 image is available, use Pseudo-MRI mode instead. This mode requires usable digitization/headshape points in the MEG FIF files and still uses FreeSurfer/BEM after generating the pseudo T1 image. Set the backend in the mounted project config:

params {
  megflow {
    datasets {
      docker_input {
        anatomy {
          method = "pseudomri"
        }
      }
    }
  }
}

docker run --rm -it \
  -v /path/to/meg_dataset:/input \
  -v /path/to/output:/output \
  -v /path/to/smri:/smri \
  -v /path/to/license.txt:/fs_license.txt \
  -v /path/to/pseudomri.config:/config/project.config:ro \
  cplmeg/megflow:1.0.0 \
  --config /config/project.config \
  -i /input \
  -o /output \
  --fs_subjects_dir /smri \
  --fs_license_file /fs_license.txt \
  --steps all \
  --resume

Full Workflow Checklist#

Stage	Dataset-specific detail to confirm
MEG import	Subject/session/task/run filters and raw-file exclusion keywords.
NormMEG-QC	Confirm the reference device/category, fixed reference preprocessing, `min_score` processing gate, and `alarm_score` report threshold.
Continuous preprocessing	Line-noise frequency, sampling rate, filtering range, and whether Maxwell/tSSS is required for the device.
Artifact detection	Bad-channel detector sensitivity, bad-segment detector window length, and whether bad channels should be interpolated.
ICA	Number of components, ECG/EOG channel availability, ICLabel/rule-based settings, and manual review expectations.
Epochs	Resting fixed-length windows or task events, trigger channel, event ids, BIDS `events.tsv` labels, epoch time window, baseline, and rejection thresholds.
Covariance	Baseline epochs versus paired raw noise/empty-room recordings. For raw covariance, set `covariance.type = "raw"` and `covariance.raw_covariance_task_id`. Confirm `rank_policy` and the target/noise common-channel set; LCMV additionally writes a data covariance from the exact source input.
Anatomy matching	FreeSurfer/DeepPrep subject ids, `anatomy.select_tag` if needed, and whether anatomy was generated in this run or reused.
Coregistration	Fiducial quality, head-shape quality, HPI availability, and whether the default ICP weights are appropriate.
Forward and source reconstruction	Source spacing, source method, `source.type`, epoch label, inverse or beamformer parameters, rank overrides, and the intended output interpretation. See Rank, Covariance, and Source Imaging.

After a Full Run#

Open:

/path/to/output/static_html_report/index.html

Review the workflow diagram first, then check subject-level alarms. For a full run, pay special attention to epoch rejection rate, covariance figures, coregistration distance, final ICP images, forward/head-model outputs, and source reconstruction figures.