What’s new?#
Version 0.21 (unreleased)#
Detailed list of changes#
🚀 Enhancements#
Add
mne_bids.read_participants()to readparticipants.tsvinto rows keyed by subject label, also from the file’s bytes for files that are not on a local disk, by Bruno Aristimunha (#1706)Expose MRI defacing function to public API as
mne_bids.deface_mri()by Erica Peterson (#1544)Add an
extra_fieldsparameter tomake_dataset_description()to write additional top-level keys todataset_description.json, by Bruno Aristimunha (#1674)Add
mne_bids.open_lock(), the cross-process file lock mne-bids uses for shared files such asparticipants.tsv, so downstream writers can share it, by Bruno Aristimunha (#1675)mne_bids.read_epochs_bids()now reads epoched FIF files (RecordingType: "epoched") withmne.read_epochs(), andmne_bids.read_raw_bids()points to it for such files, by Hamza Abdelhedi (#1679)mne_bids.read_raw_bids()now accepts path-like inputs (strorpathlib.Path), converting them viamne_bids.get_bids_path_from_fname(), by Bruno Aristimunha (#1695)Add
fnamesparameter tomne_bids.find_matching_paths()to filter pre-collected file paths without walking the filesystem, by Bruno Aristimunha (#1698)Add
mne_bids.find_inherited_sidecars()to choose, from a list of file paths, the sidecar files that apply to a recording under the BIDS inheritance principle, ordered from the dataset root down, without accessing the files, so it also works with URLs, by Bruno Aristimunha (#1708)mne_bids.BIDSPathandmne_bids.get_entities_from_fname()now know every entity, datatype and raw-data suffix of the BIDS schema (for exampleecho,reconstruction,tracer, and thefunc,dwi,fmap,perf,pet,mrsandmicrdatatypes), so the names of such MRI, PET, MRS and microscopy files can be parsed, and built when their extension is one MNE-BIDS accepts (such as.nii.gzand.json); withcheck=True, extensions such as.bval,.bvec,.ome.tifand.ome.zarrare still rejected, by Bruno Aristimunha (#1715)
🧐 API and behavior changes#
mne_bids.get_entities_from_fname()withon_error="warn"or"ignore"now keeps an entity that is not in the BIDS schema. Thus,BIDSPath(**get_entities_from_fname(fname, on_error="warn"))can raise aTypeError. By Bruno Aristimunha (#1715)BIDSPath.entitiesandmne_bids.get_entities_from_fname()now return all 35 BIDS entities, by Bruno Aristimunha (#1715).The
recanddirparts of a BIDS filename are returned as thereconstructionanddirectionentities, by Bruno Aristimunha (#1715)Sidecar files are now written to a temporary file and moved into place, so reading them no longer takes a file lock, and a sidecar whose content would not change is no longer rewritten, by Hamza Abdelhedi (#1680)
🛠 Requirements#
None yet
🪲 Bug fixes#
mne_bids.read_raw_bids()now uses the ageUnitsfromparticipants.json(for example months) when setting the birthday, instead of always assuming years, by Bruno Aristimunha (#1721)Reject unexpected EEGLAB companion file extensions with a
ValueErrorinstead of an assertion, so validation is retained when Python runs with optimization enabled, by Bruno Aristimunha (#1710)mne_bids.read_raw_bids()now leaves the birthday unset when a participant age is non-finite or would produce an out-of-range date, preserving other participant metadata instead of failing, by Bruno Aristimunha (#1709)mne_bids.read_raw_bids()no longer fails with anAttributeErrorwhen anevents.jsonsidecar is not a JSON object (for example[]), by Bruno Aristimunha (#1703)mne_bids.read_raw_bids()now passeson_split_missing="warn"by default when reading split FIF files, allowing partial data loading with a warning when later split files are missing instead of crashing, by Bruno Aristimunha (#1712)Read
events.tsvfiles with reserved column names or negative durations (with a warning), and TSV files with non-UTF-8 bytes past the first 64 KiB, by Bruno Aristimunha (#1714)Fix readers seeing a partially written sidecar while another process was rewriting it, by Hamza Abdelhedi (#1680)
Fix parallel
mne_bids.write_raw_bids()calls for BTi/4D data overwriting each other’s.bidsignorechanges, by Hamza Abdelhedi (#1680)find_matching_paths()andBIDSPath.match()now follow symbolic links to directories, and no longer return hidden files (or files inside hidden directories), which could happen when a dataset was searched withoutdatatypesand withoutignore_nosub, by Hamza Abdelhedi (#1678)Fix
find_matching_paths()omitting files with atracksysentity and returning no matches whentracking_systemsis specified, by Shubham Padkonde.Fix
find_matching_paths()andBIDSPath.match()omitting every file with an entity they did not know, such asechoorrecin MRI filenames;find_matching_paths()matches these entities with its newentitiesparameter, by Bruno Aristimunha (#1715)Allow
acquisition="calibration"or"crosstalk"together with ataskinBIDSPathwhendatatypeis not"meg", since these labels are reserved only for MEG fine-calibration and crosstalk files, by Bruno Aristimunha (#1673)Fix
find_matching_paths()andBIDSPath.match()raising an error when the dataset contains a file that cannot be represented as aBIDSPath, such as FreeSurfer output inderivatives; such files are now skipped, by Eric Larson (#1699)Fix
mne_bids.get_entity_vals()withinclude_matchreturning no values when the dataset itself is inside a hidden directory, by Eric Larson (#1699)Fix
mne_bids.get_bids_path_from_fname()raising anUnboundLocalErrorinstead of a clear error for ascans.tsvfile name without subject or session entities, by Eric Larson (#1699)mne_bids.read_raw_bids()no longer sets fNIRS channels whosechannels.tsvtype isNIRSCWHBO,NIRSCWHBRorNIRSCWOPTICALDENSITYtomisc: they get the MNE typeshbo,hbrandfnirs_od, andchannels.tsvis written with these BIDS types for such channels instead of raising aKeyError, by Bruno Aristimunha (#1701)mne_bids.find_matching_paths()andmne_bids.BIDSPath.match()now return MEF3.mefdrecordings, which are directories, as they do CTF.dsdirectories, by Bruno Aristimunha (#1707)mne_bids.read_raw_bids()now matches fNIRS channels on thesource,detectorandwavelength_nominalcolumns ofchannels.tsvwhen their names differ from the names MNE gives SNIRF channels (for exampleS1-D1-690.0in OpenNeuro ds004830), instead of raising a channel mismatch error, by Bruno Aristimunha (#1704)
⚕️ Code health#
mne_bids.read_raw_bids()now parsesparticipants.tsvonce per version of the file instead of on every call, so reading every recording of a large dataset no longer gets slower as the number of subjects grows, by Hamza Abdelhedi (#1681)Dropping rows from a TSV table no longer deep-copies the table first, by Hamza Abdelhedi (#1681)
Sped up
mne_bids.read_raw_bids()andmne_bids.write_raw_bids()on network filesystems by taking fewer file locks, by Hamza Abdelhedi (#1680)Improvements to directory searching that speed up
BIDSPath.match(),find_matching_paths(), andread_raw_bids(), especially when searching network file systems, by Hamza Abdelhedi (#1678)Creating and updating
BIDSPathobjects is faster, which speeds upBIDSPath.match()andfind_matching_paths()on datasets with many files, by Eric Larson (#1699)