- mne_bids.write_raw_bids(raw, bids_path, events=None, event_id=None, *, anonymize=None, format='auto', symlink=False, empty_room=None, allow_preload=False, montage=None, acpc_aligned=False, overwrite=False, events_data=None, verbose=None)#
Save raw data to a BIDS-compliant folder structure.
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-bidswill 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.
The raw data. It must be an instance of
mne.io.Rawthat is not already loaded from disk unless
allow_preloadis explicitly set to
True. See warning for the
The file to write. The
mne_bids.BIDSPathinstance passed here must have the
rootattributes set. If the
datatypeattribute is not set, it will be inferred from the recording data type found in
raw. In case of multiple data types, the
.datatypeattribute 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
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
and add a line to the following files:
Note that the extension is automatically inferred from the raw object.
- eventspath-like |
Use this parameter to specify events to write to the
*_events.tsvsidecar file, additionally to the object’s
Annotations(which are always written). If
path-like, 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.annotationsexist, the union of
raw.annotationswill be written. Mappings from event names to event codes (listed in the third column of the MNE events array) must be specified via the
event_idparameter; otherwise, an exception is raised. If
Annotationsare present, their descriptions must be included in
event_idas well. If
None, events will only be inferred from the raw object’s
If specified, writes the union of
raw.annotations. If you wish to only write
events=None. If you want to exclude the events in
raw.annotationsfrom being written, call
raw.set_annotations(None)before invoking this function.
Descriptions of all event codes must be specified via the
Descriptions or names describing the event codes, if you passed
events. The descriptions will be written to the
*_events.tsv. The dictionary keys correspond to the event description,s and the values to the event codes. You must specify a description for all event codes appearing in
events. If your data contains
Annotations, you can use this parameter to assign event codes to each unique annotation description (mapping from description to event code).
If None (default), no anonymization is performed. If a dictionary, data will be anonymized depending on the dictionary keys:
daysbackis a required key,
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
daysbackfor all subject anonymizations.
daysbackshould be great enough to shift the date prior to 1925 to conform with BIDS anonymization rules.
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.
Whether to store the name of the
rawinput file in the
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.
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.,
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.
Symlinks are currently only supported on macOS and Linux. We will add support for Windows 10 at a later time.
The empty-room recording to be associated with this file. This is only supported for MEG data. If
Raw, you may pass raw data that was not preloaded (otherwise, pass
allow_preload=True); i.e., it behaves similar to the
rawparameter. The session name will be automatically generated from the raw object’s
info['meas_date']. If a
rootattribute must be the same as in
None(default) if you do not wish to specify an associated empty-room recording.
Changed in version 0.11: Accepts
True, allow writing of preloaded raw objects (i.e.,
True). Because the original file is ignored, you must specify what
formatto write (not
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.
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
rawis stored in).
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.
Whether to overwrite existing files or data in files. Defaults to
True, any existing files with the same BIDS parameters will be overwritten with the exception of the
*_scans.tsvfiles. 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.tsvby a user will be retained. If
False, no existing data will be overwritten or replaced.
Deprecated since version 0.11: Use
You should ensure that
raw.info['meas_date']are set to proper (not-
None) values to allow for the correct computation of each participant’s age when creating
This function will convert existing
raw.annotationsto events. Additionally, any events supplied via
eventswill be written too. To avoid writing of annotations, remove them from the raw file via
To write events encoded in a
STIMchannel, 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
.edffiles, 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
write_raw_bidswill generate a
dataset_description.jsonfile if it does not already exist. Minimal metadata will be written there. If one sets
Truehere, it will not overwrite an existing
dataset_description.jsonfile. If you need to add more data there, or overwrite it, then you should call
When writing EDF or BDF files, all file extensions are forced to be lower-case, in compliance with the BIDS specification.