What was new in previous releases?

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)

Version 0.4

Changelog

• Added automatic conversion of FIF to BrainVision format with warning for EEG only data and conversion to FIF for meg non-FIF data, by Alex Rockhill (#237)

• Add possibility to pass raw readers parameters (e.g. allow_maxshield) to read_raw_bids() to allow reading BIDS-formatted data before applying maxfilter, by Sophie Herbst

• New feature in mne_bids.write.write_anat for shear deface of mri, by Alex Rockhill (#271)

• Added option to anonymize by shifting measurement date with anonymize parameter, in accordance with BIDS specifications, by Alex Rockhill (#280)

• Added mne_bids.get_matched_empty_room to get empty room filename matching a data file, by Mainak Jas (#290)

• Add ability for mne_bids.get_head_mri_trans() to read fiducial points from fif data without applying maxfilter, by Maximilien Chaumon (#291)

• Added landmark argument to write_anat() to pass landmark location directly for deface, by Alex Rockhill (#292)

• Standardized bids_root and output_path arguments in read_raw_bids(), write_raw_bids(), and make_bids_folders to just bids_root, by Adam Li (#303)

• Add existence check for write_raw_bids() before make_dataset_description() is called, by Adam Li (#331)

• Update scans.tsv writer to adhere to MNE-Python v0.20+ where meas_date is stored as a datetime object, by Adam Li (#344)

• read_raw_bids() now reads in sidecar json files to set, or estimate Power Line Frequency, by Adam Li (#341)

• Allow FIF files with multiple parts to be read using read_raw_bids(), by Teon Brooks (#346)

• Added handedness to participant files, by Dominik Welke (#354)

• MNE-BIDS can now handle a paths that are pathlib.Path objects (in addition to strings), by Richard Höchenberger (#362)

• The documentation is now available for all MNE-BIDS versions via a dropdown menu, by Stefan Appelhoff (#370)

Bug

• Fixed broken event timing broken by conversion to BV in write_raw_bids(), by Alex Rockhill (#294)

• Support KIT related files .elp and .hsp BIDS conversion in write_raw_bids(), by Fu-Te Wong (#323)

• Enforce that the name arg is a required field for mne_bids.make_dataset_description(), by Teon Brooks and Stefan Appelhoff (#342)

• Fix writing to scans.tsv file when anonymization is turned on, by Adam Li (#352)

• Fix read_raw_bids() to properly read in sidecar json even if a similarly named copy lives inside “derivatives/” sub-folder, by Adam Li (#350)

• Fix read_raw_bids() to properly read in events.tsv sidecar if the ‘trial_type’ description has a “#” character in it, by Adam Li (#355)

• Avoid cases in which NumPy would raise a FutureWarning when populating TSV files, by Richard Höchenberger (#372)

• Remove events with an unknown onset, and assume unknown event durations to be zero, when reading BIDS data via read_raw_bids(), by Richard Höchenberger (#375)

Authors

People who contributed to this release (in alphabetical order):

• Adam Li

• Alex Rockhill

• Alexandre Gramfort

• Ariel Rokem

• Dominik Welke

• Fu-Te Wong

• Mainak Jas

• Maximilien Chaumon

• Richard Höchenberger

• Sophie Herbst

• Stefan Appelhoff

• Teon Brooks

Version 0.3

Changelog

• New function mne_bids.get_modalities for getting data types from a BIDS dataset, by Stefan Appelhoff (#253)

• New function mne_bids.get_entity_vals() allows to get a list of instances of a certain entity in a BIDS directory, by Mainak Jas and Stefan Appelhoff (#252)

• mne_bids.print_dir_tree() now accepts an argument max_depth which can limit the depth until which the directory tree is printed, by Stefan Appelhoff (#245)

• New command line function exposed cp for renaming/copying files including automatic doc generation “CLI”, by Stefan Appelhoff (#225)

• read_raw_bids() now also reads channels.tsv files accompanying a raw BIDS file and sets the channel types accordingly, by Stefan Appelhoff (#219)

• Add example convert_mri_and_trans for using get_head_mri_trans() and write_anat(), by Stefan Appelhoff (#211)

• get_head_mri_trans() allows retrieving a trans object from a BIDS dataset that contains MEG and T1 weighted MRI data, by Stefan Appelhoff (#211)

• write_anat() allows writing T1 weighted MRI scans for subjects and optionally creating a T1w.json sidecar from a supplied trans object, by Stefan Appelhoff (#211)

• read_raw_bids() will return the the raw object with raw.info['bads'] already populated, whenever a channels.tsv file is present, by Stefan Appelhoff (#209)

• read_raw_bids() is now more likely to find event and channel sidecar json files, by Marijn van Vliet (#233)

• Enhanced read_raw_bids() and write_raw_bids() for iEEG coordinates along with example and unit test, by Adam Li (#335)

Bug

• Fixed bug in mne_bids.datasets.fetch_faces_data where downloading multiple subjects was impossible, by Stefan Appelhoff (#262)

• Fixed bug where read_raw_bids() would throw a ValueError upon encountering strings in the “onset” or “duration” column of events.tsv files, by Stefan Appelhoff (#234)

• Allow raw data from KIT systems to have two marker files specified, by Matt Sanderson (#173)

API

• read_raw_bids() no longer optionally returns events and event_id but returns the raw object with mne.Annotations, whenever an events.tsv file is present, by Stefan Appelhoff (#209)

Authors

People who contributed to this release (in alphabetical order):

• Alexandre Gramfort

• Mainak Jas

• Marijn van Vliet

• Matt Sanderson

• Stefan Appelhoff

• Teon Brooks

Version 0.2

Changelog

• Add a reader for BIDS compatible raw files, by Mainak Jas (#135)

Bug

• Normalize the length of the branches in mne_bids.print_dir_tree() by the length of the root path, leading to more adequate visual display, by Stefan Appelhoff (#192)

• Assert a minimum required MNE-version, by Dominik Welke (#166)

• Add function in mne_bids.utils to copy and rename CTF files mne_bids.utils.copyfile_ctf, by Romain Quentin (#162)

• Encoding of BrainVision .vhdr/.vmrk files is checked to prevent encoding/decoding errors when modifying, by Dominik Welke (#155)

• The original units present in the raw data will now correctly be written to channels.tsv files for BrainVision, EEGLAB, and EDF, by Stefan Appelhoff (#125)

• Fix logic with inferring unknown channel types for CTF data, by Mainak Jas (#129)

• Fix the file naming for FIF files to only expose the part key-value pair when files are split, by Teon Brooks (#137)

• Allow files with no stim channel, which could be the case for example in resting state data, by Mainak Jas (#167)

• Better handling of unicode strings in TSV files, by Mainak Jas (#172)

• Fix separator in scans.tsv to always be /, by Matt Sanderson (#176)

• Add seeg to mne_bids.utils._handle_datatype when determining the kind of ieeg data, by Ezequiel Mikulan (#180)

• Fix problem in copying CTF files on Network File System due to a bug upstream in Python, by Mainak Jas (#174)

• Fix problem in copying BTi files. Now, a utility function ensures that all the related files such as config and headshape are copied correctly, by Mainak Jas (#135)

• Fix name of “sample” and “value” columns on events.tsv files, by Ezequiel Mikulan (#185)

• Update function to copy KIT files to the meg directory, by Matt Sanderson (#187)

API

• make_dataset_description() is now available from mne_bids main namespace, all copyfile functions are available from mne_bids.copyfiles namespace, by Stefan Appelhoff (#196)

• Add support for non maxfiltered .fif files, by Maximilien Chaumon (#171)

• Remove support for Neuroscan .cnt data because its support is no longer planned in BIDS, by Stefan Appelhoff (#142)

• Remove support for Python 2 because it is no longer supported in MNE-Python, by Teon Brooks (#141)

• Remove Pandas requirement to reduce number of dependencies, by Matt Sanderson (#122)

• Use more modern API of event_from_annotations in MNE for extracting events in .vhdr and .set files, by Mainak Jas (#167)

Authors

People who contributed to this release (in alphabetical order):

• Alexandre Gramfort

• Chris Holdgraf

• Clemens Brunner

• Dominik Welke

• Ezequiel Mikulan

• Mainak Jas

• Matt Sanderson

• Maximilien Chaumon

• Romain Quentin

• Stefan Appelhoff

• Teon Brooks

Version 0.1

Changelog

• Add example for how to rename BrainVision file triplets: rename_brainvision_files.py, by Stefan Appelhoff (#104)

• Add function to fetch BrainVision testing data mne_bids.datasets.fetch_brainvision_testing_data, by Stefan Appelhoff (#104)

• Add support for EEG and a corresponding example: make_eeg_bids.py, by Stefan Appelhoff (#78)

• Update mne_bids.raw_to_bids to work for KIT and BTi systems, by Teon Brooks (#16)

• Add support for iEEG and add mne_bids.make_bids_folders and mne_bids.make_bids_folders, by Chris Holdgraf (#28 and #37)

• Add command line interface, by Teon Brooks (#31)

• Add mne_bids.print_dir_tree() for visualizing directory structures and restructuring package to be more open towards integration of other modalities (iEEG, EEG), by Stefan Appelhoff (#55)

• Automatically generate participants.tsv, by Matt Sanderson (#70)

• Add support for KIT marker files to be exported with raw data, by Matt Sanderson (#114)

Bug

• Correctly handle the case when measurement date is not available, by Mainak Jas (#23)

• Fix counting of miscellaneous channels, by Matt Sanderson (#49)

• The source data is now copied over to the new BIDS directory. Previously this was only true for FIF data, by Stefan Appelhoff (#55)

• Fix ordering of columns in scans.tsv, by Matt Sanderson (#68)

• Fix bug in how artificial trigger channel STI014 is handled in channels.tsv for KIT systems, by Matt Sanderson (#72)

• Fix channel types for KIT system in channels.tsv, by Matt Sanderson (#76)

• Fix the way FIF files are named to satisfy the BIDS part parameters of the filename construction, Teon Brooks (#102)

• Fix how overwriting of data is handled, by Matt Sanderson (#99)

Authors

People who contributed to this release (in alphabetical order):

• Alexandre Gramfort

• Chris Holdgraf

• Kambiz Tavabi

• Mainak Jas

• Matt Sanderson

• Romain Quentin

• Stefan Appelhoff

• Teon Brooks