Quickstart

Quickstart#

This page is for a first successful MEGPrep run. You do not need to understand all configuration fields before starting. For a new dataset, the safest first run is usually through ICA cleaning and QC:

MEG data -> preprocessing -> artifact detection -> ICA cleaning -> QC report

The later stages, especially epochs, covariance, coregistration, and source reconstruction, are more dataset-specific. They often need event definitions, noise-covariance choices, and anatomy matching to be checked before a full source-level run. See Full Workflow when you are ready for those stages.

Before You Start#

Prepare two required paths on your computer. You may also need an anatomy path later for source-level analysis:

Path

What it contains

/path/to/bids_or_raw_meg

Your MEG dataset. BIDS is recommended, but raw FIF discovery is also supported by the default config.

/path/to/output

An empty or reusable output directory for MEGPrep results.

/path/to/smri

Optional for the first run. FreeSurfer or DeepPrep anatomy outputs are required later for coregistration and source reconstruction.

If you do not already have anatomy outputs, start with the preprocessing check below. Run anatomy or source reconstruction after you confirm how T1 images should be selected for your dataset.

Run One Command#

Replace only the paths in this command. This first run stops after ICA cleaning, which avoids dataset-specific event and source-model assumptions:

docker run --rm -it \
  -v /path/to/bids_or_raw_meg:/input \
  -v /path/to/output:/output \
  cmrlab/megprep:0.0.3 \
  -i /input \
  -o /output \
  --steps meg_ica \
  --resume

This run imports your MEG files, applies the default continuous preprocessing, detects bad channels and bad segments, fits and labels ICA, applies ICA, and generates the static QC report. The Docker paths after the colon are fixed container paths; normally you only edit the host paths before the colon.

Check the Results#

When the run finishes, open:

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

Start with the dataset dashboard. Sort the table by alarms, bad channels, bad segments, ICA components, missing steps, or, for full runs, coregistration distance and epoch rejection rate. Click a subject to review its detailed page.

The most useful output locations are:

Path

Meaning

output/preprocessed/

Processed data, artifact files, ICA outputs, and any later-stage outputs produced by the selected --steps mode.

output/static_html_report/index.html

Main quality-control report.

output/report.html

Nextflow execution report.

output/timeline.html

Nextflow runtime timeline.

What Do I Need to Change?#

For the first meg_ica run, often nothing beyond paths and --steps. Change the config when one of these applies:

Situation

What to change

You want only a subset of subjects, sessions, tasks, or runs.

Edit meg_import_config in nextflow.config.

Your data are resting-state and you only need fixed-length epochs.

Before running meg_epochs or meg_all, edit epoch_config.task_type and resting.fixed_length_duration.

Your task events come from a specific trigger channel or BIDS events.tsv labels.

Before running meg_epochs or meg_all, edit epoch_config.find_events or epoch_config.event_file.

Your line noise frequency is not 50 Hz.

Edit preproc_config.notch_filter.

You need a different sampling rate.

Edit preproc_config.resample.sfreq.

You have empty-room or noise recordings for covariance.

Set covar_type = "raw" and raw_covariance_task_id.

You only want to rebuild the report.

Run with --steps report.

Minimal Config Override#

Most users should start from the default config. If you only want to select a task from a BIDS dataset, mount a small project config that changes the import filter:

params {
    meg_import_config = """
    subject_id: null
    session_id: null
    task:
      - rest
    run_id: null
    """
}

Then run the first QC pass with:

docker run --rm -it \
  -v /path/to/bids:/input \
  -v /path/to/output:/output \
  -v /path/to/smri:/smri \
  -v /path/to/my_nextflow.config:/program/nextflow/nextflow.config \
  cmrlab/megprep:0.0.3 \
  -i /input -o /output --fs_subjects_dir /smri --steps meg_ica --resume

The Docker entrypoint automatically prepares the mounted output directory and runs the pipeline as the host UID/GID inferred from /input. The output directory does not need to exist before the command is launched. Report-only runs that only mount /output infer ownership from /output. If neither mount is owned by the desired output user, add -e LOCAL_UID="$(id -u)" -e LOCAL_GID="$(id -g)" before the volume mounts.

Next Steps#

After your first report is generated:

  • Read Reports to understand the static report.

  • Read Outputs to find processed files.

  • Read Full Workflow when you are ready to run anatomy, epochs, covariance, coregistration, and source reconstruction.

  • Read Configuration Reference when you need full parameter details.

  • Read Configuration Examples for resting-state, task-based, source reconstruction, cluster, and empty-room covariance examples.

Contents