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, overwrite=False, verbose=True)[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_pathmne_bids.BIDSPath

The file to write. The mne_bids.BIDSPath instance passed here must have the .root attribute 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.

format‘auto’ | ‘BrainVision’ | ‘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, or FIF) will only take place when the original file format lacks some necessary features. When a str is passed, a conversion can be forced to the BrainVision format for EEG, or the FIF format 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_roommne_bids.BIDSPath | 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.

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

If True, this will print a snippet of the sidecar files. Otherwise, no content will be printed.

Returns
bids_pathmne_bids.BIDSPath

The path of the created data file.

See also

mne.io.Raw.anonymize
mne.find_events
mne.Annotations
mne.events_from_annotations

Notes

You should ensure that raw.info['subject_info'] and raw.info['meas_date'] are set to proper (not-None) values to allow for the correct computation of each participant’s age when creating *_participants.tsv.

This function will convert existing mne.Annotations from raw.annotations to events. Additionally, any events supplied via events_data will be written too. To avoid writing of annotations, remove them from the raw file via raw.set_annotations(None) before invoking write_raw_bids.

To write events encoded in a STIM channel, you first need to create the events array manually and pass it to this function:

See the documentation of mne.find_events() for more information on event extraction from STIM channels.

When anonymizing .edf files, then the file format for EDF limits how far back we can set the recording date. Therefore, all anonymized EDF datasets will have an internal recording date of 01-01-1985, and the actual recording date will be stored in the scans.tsv file’s acq_time column.

write_raw_bids will generate a dataset_description.json file if it does not already exist. Minimal metadata will be written there. If one sets overwrite to True here, it will not overwrite an existing dataset_description.json file. If you need to add more data there, or overwrite it, then you should call mne_bids.make_dataset_description() directly.

API Documentation mne_bids.read_raw_bids