meeg_utils.io.save_derivative#

meeg_utils.io.save_derivative(inst, source, root, *, pipeline=None, desc='preproc', overwrite=False, sources=None, metadata=None)[source]#

Save processed data as a BIDS derivative, with a provenance sidecar.

The data are written to <root>/sub-<sub>/[ses-<ses>/]<datatype>/<entities>_desc-<desc>_<suffix>.fif, where <suffix> is the datatype (meg/eeg) for Raw data, epo for Epochs and ave for Evoked. A JSON sidecar with the same name holds the source file and, if pipeline is given, its configuration, provenance and QC metrics. <root>/dataset_description.json is created if missing.

A plain path inside a BIDS dataset is treated as BIDS. For a non-BIDS source, the file is written directly to root as <source stem>_desc-<desc>_<suffix>.fif.

Parameters:

  • inst (Raw | Epochs | Evoked) – The processed data.

  • source (BIDSPath | str | Path) – The recording the data were derived from; its BIDS entities name the output.

  • root (str | Path) – Root of the derivatives dataset, e.g. <bids_root>/derivatives/meeg-utils.

  • pipeline (Pipeline | None) – The (fitted) pipeline that produced the data.

  • desc (str) – Value of the BIDS desc entity.

  • overwrite (bool) – Whether to overwrite existing files.

  • sources (list | None) – The files the data were derived from, for the sidecar’s Sources (default: source), e.g. the runs combined into one file.

  • metadata (dict | None) – Additional entries for the sidecar’s MeegUtils section.

Returns:

The data file written.

Return type:

Path

Raises:

FileExistsError – If the output exists and overwrite is False.