mne_bids.write_raw_bids

mne_bids.write_raw_bids(raw, bids_path, events_data=None, event_id=None, anonymize=None, format='auto', 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. The data should not be loaded from disk, i.e., raw.preload must be False.

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. 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 data type is automatically inferred from the raw object, as well as the extension. Data with MEG and other electrophysiology data in the same file will be stored as 'meg'.

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.

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.