mne_bids.write_raw_bids¶

mne_bids.write_raw_bids(raw, bids_path, events_data=None, event_id=None, anonymize=None, format='auto', symlink=False, empty_room=None, allow_preload=False, montage=None, acpc_aligned=False, overwrite=False, verbose=None)[source]¶

Save raw data to a BIDS-compliant folder structure.

Warning

The original file is simply copied over if the original file format is BIDS-supported for that datatype. Otherwise, this function will convert to a BIDS-supported file format while warning the user. For EEG and iEEG data, conversion will be to BrainVision format; for MEG, conversion will be to FIFF.
mne-bids will infer the manufacturer information from the file extension. If your file format is non-standard for the manufacturer, please update the manufacturer field in the sidecars manually.

Parameters

rawmne.io.Raw

The raw data. It must be an instance of mne.io.Raw that is not already loaded from disk unless allow_preload is explicitly set to True. See warning for the allow_preload parameter.

bids_pathBIDSPath

The file to write. The mne_bids.BIDSPath instance passed here must have the subject, task, and root attributes set. If the datatype attribute is not set, it will be inferred from the recording data type found in raw. In case of multiple data types, the .datatype attribute must be set. Example:

bids_path = BIDSPath(subject='01', session='01', task='testing',
                     acquisition='01', run='01', datatype='meg',
                     root='/data/BIDS')

This will write the following files in the correct subfolder root:

sub-01_ses-01_task-testing_acq-01_run-01_meg.fif
sub-01_ses-01_task-testing_acq-01_run-01_meg.json
sub-01_ses-01_task-testing_acq-01_run-01_channels.tsv
sub-01_ses-01_acq-01_coordsystem.json

and the following one if events_data is not None:

sub-01_ses-01_task-testing_acq-01_run-01_events.tsv

and add a line to the following files:

participants.tsv
scans.tsv

Note that the extension is automatically inferred from the raw object.

events_datapath-like | np.ndarray | None

Use this parameter to specify events to write to the *_events.tsv sidecar file, additionally to the object’s mne.Annotations (which are always written). If a path, specifies the location of an MNE events file. If an array, the MNE events array (shape: (n_events, 3)). If a path or an array and raw.annotations exist, the union of event_data and raw.annotations will be written. Corresponding descriptions for all event IDs (listed in the third column of the MNE events array) must be specified via the event_id parameter; otherwise, an exception is raised. If None, events will only be inferred from the the raw object’s mne.Annotations.

Note

If not None, writes the union of events_data and raw.annotations. If you wish to only write raw.annotations, pass events_data=None. If you want to exclude the events in raw.annotations from being written, call raw.set_annotations(None) before invoking this function.

Note

Descriptions of all event IDs must be specified via the event_id parameter.

event_iddict | None

Descriptions of all event IDs, if you passed events_data. The descriptions will be written to the trial_type column in *_events.tsv. The dictionary keys correspond to the event descriptions and the values to the event IDs. You must specify a description for all event IDs in events_data.

anonymizedict | None

If None (default), no anonymization is performed. If a dictionary, data will be anonymized depending on the dictionary keys: daysback is a required key, keep_his is optional.

daysbackint: Number of days by which to move back the recording date in time. In studies with multiple subjects the relative recording date differences between subjects can be kept by using the same number of daysback for all subject anonymizations. daysback should be great enough to shift the date prior to 1925 to conform with BIDS anonymization rules.
keep_hisbool: If False (default), all subject information next to the recording date will be overwritten as well. If True, keep subject information apart from the recording date.
keep_sourcebool: Whether to store the name of the raw input file in the source column of scans.tsv. By default, this information is not stored.

format‘auto’ | ‘BrainVision’ | ‘EDF’ | ‘FIF’

Controls the file format of the data after BIDS conversion. If 'auto', MNE-BIDS will attempt to convert the input data to BIDS without a change of the original file format. A conversion to a different file format (BrainVision, EDF, or FIF) will only take place when the original file format lacks some necessary features. Conversion can be forced to BrainVision or EDF for (i)EEG, and to FIF for MEG data.

symlinkbool

Instead of copying the source files, only create symbolic links to preserve storage space. This is only allowed when not anonymizing the data (i.e., anonymize must be None).

Note

Symlinks currently only work with FIFF files. In case of split files, only a link to the first file will be created, and mne_bids.read_raw_bids() will correctly handle reading the data again.

Note

Symlinks are currently only supported on macOS and Linux. We will add support for Windows 10 at a later time.

empty_roomBIDSPath | None

The empty-room recording to be associated with this file. This is only supported for MEG data, and only if the root attributes of bids_path and empty_room are the same. Pass None (default) if you do not wish to specify an associated empty-room recording.

allow_preloadbool

If True, allow writing of preloaded raw objects (i.e., raw.preload is True). Because the original file is ignored, you must specify what format to write (not auto).

Warning

BIDS was originally designed for unprocessed or minimally processed data. For this reason, by default, we prevent writing of preloaded data that may have been modified. Only use this option when absolutely necessary: for example, manually converting from file formats not supported by MNE or writing preprocessed derivatives. Be aware that these use cases are not fully supported.

montagemne.channels.DigMontage | None

The montage with channel positions if channel position data are to be stored in a format other than “head” (the internal MNE coordinate frame that the data in raw is stored in).

acpc_alignedbool

It is difficult to check whether the T1 scan is ACPC aligned which means that “mri” coordinate space is “ACPC” BIDS coordinate space. So, this flag is required to be True when the digitization data is in “mri” for intracranial data to confirm that the T1 is ACPC-aligned.

overwritebool

Whether to overwrite existing files or data in files. Defaults to False.

If True, any existing files with the same BIDS parameters will be overwritten with the exception of the *_participants.tsv and *_scans.tsv files. For these files, parts of pre-existing data that match the current data will be replaced. For *_participants.tsv, specifically, age, sex and hand fields will be overwritten, while any manually added fields in participants.json and participants.tsv by a user will be retained. If False, no existing data will be overwritten or replaced.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns

bids_pathBIDSPath: The path of the created data file.

Examples using `mne_bids.write_raw_bids`¶

API Documentation

mne_bids.read_raw_bids

mne_bids.write_raw_bids¶

Examples using mne_bids.write_raw_bids¶

Examples using `mne_bids.write_raw_bids`¶