What’s new?

Version 0.5 (2020-10-22)

This is a big release with lots of changes, many of them breaking existing code. But do not fear: migration is easy, and you will love what we have been cooking for you!

Notable changes

• We introduce mne_bids.BIDSPath, a new class for all BIDS file and folder operations. All functions in MNE-BIDS that previously accepted filenames and folder locations (e.g. bids_root) have been updated to work with BIDSPath. Others have been removed. Consequently, you will need to update your existing code, too. See the API changes section for an overview of which functions have changed or have been removed, and follow this introduction and our to learn about the basics of BIDSPath. Don’t worry – it’s going to be a breeze! 🤗

• MNE-BIDS now requires MNE-Python 0.21.

• The new function mne_bids.make_report() can help you populate a paragraph of your next paper’s methods section!

• You can now interactively mark channels as bad using mne_bids.mark_bad_channels().

• Elekta/Neuromag/MEGIN fine-calibration and crosstalk files can now be stored in your BIDS dataset via mne_bids.write_meg_calibration() and mne_bids.write_meg_crosstalk().

• When writing a raw file that contains annotations, these will now be converted to and stored as events by mne_bids.write_raw_bids().

Authors

The following people have contributed to this release of MNE-BIDS:

• Adam Li

• Alexandre Gramfort

• Alex Rockhill

• Austin Hurst

• Evgenii Kalenkovich

• Mainak Jas

• Richard Höchenberger

• Robert Luke

• Stefan Appelhoff

Detailed list of changes

Enhancements

• Introduce mne_bids.BIDSPath, the new universal MNE-BIDS working horse for file operations, by Adam Li, Alex Rockhill, and Richard Höchenberger (#496, #507, #511, #514, #542)

• The new function mne_bids.make_report() and its corresponding CLI function, make_report, produce human-readable summary of the BIDS dataset, by Adam Li (#457)

• read_raw_bids() now reads participants.tsv data, by Adam Li (#392)

• mne_bids.get_entity_vals() has gained ignore_* keyword arguments to exclude specific values from the list of results, e.g. the entities for a particular subject or task, by Richard Höchenberger (#409)

• mne_bids.write_raw_bids() now uses the space BIDS entity when writing iEEG electrodes and coordinate frames, by Adam Li (#390)

• convert_ieeg_to_bids to now use sample ECoG EDF data, by Adam Li (#390)

• mne_bids.write_raw_bids() now writes CoordinateSystemDescription as specified in BIDS Specification if CoordinateSystem is MNE-compatible, by Adam Li (#416)

• mne_bids.write_raw_bids() and mne_bids.read_raw_bids() now handle scalp EEG if Captrak coordinate system and NAS/LPA/RPA landmarks are present, by Adam Li (#416)

• write_raw_bids() now adds citations to the README, by Alex Rockhill (#463)

• make_dataset_description() now has an additional parameter dataset_type to set the recommended field DatasetType (defaults to "raw"), by Stefan Appelhoff (#472)

• mne_bids.copyfiles.copyfile_brainvision() now has an anonymize parameter to control anonymization, by Stefan Appelhoff (#475)

• mne_bids.read_raw_bids() and mne_bids.write_raw_bids() now map respiratory (RESP) channel types, by Richard Höchenberger (#482)

• When impedance values are available from a raw.impedances attribute, MNE-BIDS will now write an impedance column to *_electrodes.tsv files, by Stefan Appelhoff (#484)

• mne_bids.write_raw_bids() writes out status_description with 'n/a' values into the channels.tsv sidecar file, by Adam Li (#489)

• Added a new function mne_bids.mark_bad_channels() and command line interface mark_bad_channels which allows updating of the channel status (bad, good) and description of an existing BIDS dataset, by Richard Höchenberger (#491)

• mne_bids.read_raw_bids() correctly maps all specified handedness and sex options to MNE-Python, instead of only an incomplete subset, by Richard Höchenberger (#550)

• mne_bids.write_raw_bids() only writes a README if it does not already exist, by Adam Li (#489)

• Allow mne_bids.write_raw_bids() to write EEG/iEEG files from Persyst using mne.io.read_raw_persyst function, by Adam Li (#546)

• mne_bids.print_dir_tree() now works if a pathlib.Path object is passed, by Adam Li (#555)

• Allow writing of Elekta/Neuromag/MEGIN fine-calibration and crosstalk data via the new functions mne_bids.write_meg_calibration() and mne_bids.write_meg_crosstalk(), and retrieval of the file locations via BIDSPath.meg_calibration_fpath and BIDSPath.meg_crosstalk_fpath, by Richard Höchenberger (#562)

• Allow mne_bids.write_raw_bids() to write EEG/iEEG files from Nihon Kohden using mne.io.read_raw_nihon function, by Adam Li (#567)

• Allow mne_bids.get_entity_vals() to ignore datatypes using ignore_datatypes kwarg, by Adam Li (#578)

• Add with_key keyword argument to mne_bids.get_entity_vals() to allow returning the full entity strings, by Adam Li (#578)

• mne_bids.write_raw_bids() now also writes mne.io.Raw.annotations to *_events.tsv, by Adam Li and Richard Höchenberger (#582)

• BIDS conformity: The _part-%d entity is now called _split- throughout BIDS, MNE, and MNE-BIDS, by Stefan Appelhoff (#417)

Bug fixes

• Fix bug in write_raw_bids() where raw.info[‘subject_info’] can be None, by Adam Li (#392)

• read_raw_bids() will now read all channels from electrodes.tsv. Channels with coordinates 'n/a' will also be included but their location set to np.nan in the raw object, by Adam Li (#393)

• Do not change an events array passed to write_raw_bids() via the events_data keyword argument, by Alexandre Gramfort (#402)

• Fix mne_bids.read_raw_bids() to correctly scale coordinate to meters in electrodes.tsv, and also read possible iEEG coordinate frames via the ‘space’ BIDs-entity by Adam Li (#390)

• Fix coordystem reading in mne_bids.read_raw_bids() for cases where the acq is undefined, by Stefan Appelhoff (#440)

• Calling write_raw_bids() with overwrite==True will preserve existing entries in participants.tsv and participants.json if the new dataset does not contain these entries, by Adam Li (#442)

• BIDS entity recording should be represented as rec in filenames, by Adam Li (#446)

• Fix write_raw_bids() when info['dig'] is None, by Alexandre Gramfort (#452)

• mne_bids.write_raw_bids() now applies verbose to the functions that read events, by Evgenii Kalenkovich (#453)

• Fix raw_to_bids CLI tool to work with non-FIFF files, by Austin Hurst (#456)

• Fix mne_bids.write_raw_bids() to output BTI and CTF data in the scans.tsv according to the BIDS specification, by Adam Li (#465)

• mne_bids.read_raw_bids() now populates the list of bad channels based on *_channels.tsv if (and only if) a status column is present, ignoring similar metadata stored in raw file (which will still be used if no status column is present in *_channels.tsv), by Richard Höchenberger (#499)

• Ensure that Raw.info['bads'] returned by mne_bids.read_raw_bids() is always a list, by Richard Höchenberger (#501)

• mne_bids.write_raw_bids() now ensures that all parts of the mne.io.Raw instance stay in sync when using anonymization to shift dates, e.g. raw.annotations, by Richard Höchenberger (#504)

• Fix mne_bids.write_raw_bids() failed BIDS validator for raw.info['dig'] = [], by Alex Rockhill (#505)

• Ensure mne_bids.print_dir_tree() prints files and directories in alphabetical order, by Richard Höchenberger (#563)

• mne_bids.write_raw_bids() now writes the correct coordinate system names to the JSON sidecars, by Richard Höchenberger (#585)

API changes

In the transition to using mne_bids.BIDSPath, the following functions have been updated:

• mne_bids.write_anat() now accepts a mne_bids.BIDSPath instead of entities as keyword arguments, by Adam Li (#575)

• In mne_bids.write_raw_bids(), mne_bids.read_raw_bids(), and mne_bids.get_head_mri_trans(), the bids_basename and bids_root keyword arguments have been removed. The functions now expect bids_path, an instance of mne_bids.BIDSPath, by Adam Li (#525)

The following functions have been removed:

• mne_bids.make_bids_basename has been removed. Use mne_bids.BIDSPath directly, by Adam Li (#511)

• mne_bids.get_matched_empty_room has been removed. Use mne_bids.BIDSPath.find_empty_room() instead, by Richard Höchenberger (#421, #535)

• mne_bids.make_bids_folders has been removed. Use mne_bids.BIDSPath.mkdir() instead, by Adam Li (#543)

Further API changes:

• The functions mne_bids.write_anat(), mne_bids.make_report(), mne_bids.get_entity_vals() and mne_bids.get_datatypes() use now expect a root keyword argument instead of bids_root, Adam Li (#556)

• Added namespace mne_bids.path which hosts path-like functionality for MNE-BIDS, by Adam Li (#483)

• The datasets.py module was removed from MNE-BIDS and its utility was replaced by mne.datasets, by Stefan Appelhoff (#471)

• mne_bids.make_dataset_description() now accepts the argument overwrite, which will reset all fields if True. If False, user-provided fields will no longer be overwritten by mne_bids.write_raw_bids() when its overwrite argument is True, unless new values are supplied, by Alex Rockhill (#478)

• A function for retrieval of BIDS entity values from a filename, mne_bids.get_entities_from_fname(), is now part of the public API (it used to be a private function called mne_bids.path._parse_bids_filename), by Richard Höchenberger and Adam Li (#487, #496)

• Entity names passed to mne_bids.get_entity_vals() must now be in the “long” format, e.g. subject instead of sub etc., by Richard Höchenberger (#501)

• It is now required to specify the Power Line Frequency to use write_raw_bids(), while in 0.4 it could be estimated, by Alexandre Gramfort and Alex Rockhill (#506)

• Rename mne_bids.get_modalities to mne_bids.get_datatypes() for getting data types from a BIDS dataset, by Alexandre Gramfort (#253)

Find out what was new in previous releases