meeg_utils.process_dataset#

meeg_utils.process_dataset(dataset, root, *, preprocessing, epochs=None, combine=True, align='average', desc='preproc', epochs_desc='epochs', n_jobs=1, skip_existing=True, on_error='warn')[source]#

Process a whole dataset: each run, then the epochs of each session.

  1. Preprocessing: every recording is processed with its own copy of preprocessing (meeg_utils.process()) and saved with desc.

  2. Epochs (if epochs is given), per group of runs (Dataset.groups()): for MEG with align="average", the runs are first mapped to their average head position (meeg_utils.io.average_dev_head_t(); a HeadAlign step in epochs gets it as destination, otherwise one is inserted before epoching). Each run is epoched with its own copy of epochs and saved with epochs_desc.

  3. Combine (if combine): the runs of each group are concatenated (meeg_utils.epochs.combine()) and saved without the run entity.

Work already done is skipped (skip_existing), so an interrupted batch resumes where it stopped. Failures do not stop other recordings; they are collected in the result.

Parameters:

  • dataset (Dataset) – The recordings.

  • root (str | Path) – Root of the derivatives dataset.

  • preprocessing (Pipeline) – Per-run preprocessing (unfitted; not modified).

  • epochs (Pipeline | None) – Per-run epoching, applied to the preprocessed runs (Raw -> Epochs).

  • combine (bool) – Concatenate the epochs of each group’s runs.

  • align ({"average"} | None) – MEG head alignment of each group’s runs before epoching; None leaves them (combine then requires their head positions to differ by less than 2 mm).

  • desc (str) – BIDS desc of the preprocessed runs and of the epochs.

  • epochs_desc (str) – BIDS desc of the preprocessed runs and of the epochs.

  • n_jobs (int) – Recordings (stage 1) or groups (stages 2-3) processed in parallel.

  • skip_existing (bool) – Skip outputs that already exist (default True: resume).

  • on_error ({"warn", "raise"}) – After all recordings are processed, warn about failures or raise a RuntimeError listing them.

Returns:

The records of every run and group; result.to_csv(...) saves them.

Return type:

BatchResult