Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.interfaces.bids.get_bids_files¶

nilearn.interfaces.bids.get_bids_files(main_path, file_tag='*', file_type='*', sub_label='*', modality_folder='*', filters=None, sub_folder=True)[source]¶

Search for files in a BIDS dataset following given constraints.

This utility function allows to filter files in the BIDS dataset by any of the fields contained in the file names. Moreover it allows to search for specific types of files or particular tags.

The provided filters have to correspond to a file name field, so any file not containing the field will be ignored. For example the filter (‘sub’, ‘01’) would return all files corresponding to the first subject that specifically contain in the file name ‘sub-01’. If more filters are given then we constraint the possible files names accordingly.

Notice that to search in the derivatives folder, it has to be given as part of the main_path. This is useful since the current convention gives exactly the same inner structure to derivatives than to the main BIDS dataset folder, so we can search it in the same way.

Parameters:

main_pathstr or pathlib.Path: Directory of the BIDS dataset.
file_tagstr accepted by glob, default=’*’: The final tag of the desired files. For example ‘bold’ if one is interested in the files related to the neuroimages.
file_typestr accepted by glob, default=’*’: The type of the desired files. For example to be able to request only ‘nii’ or ‘json’ files for the ‘bold’ tag.
sub_labelstr accepted by glob, default=’*’: Such a common filter is given as a direct option since it applies also at the level of directories. the label is what follows the ‘sub’ field in the BIDS convention as ‘sub-label’.
modality_folderstr accepted by glob, default=’*’: Inside the subject and optional session folders a final level of folders is expected in the BIDS convention that groups files according to different neuroimaging modalities and any other additions of the dataset provider. For example the ‘func’ and ‘anat’ standard folders. If given as the empty string ‘’, files will be searched inside the sub-label/ses-label directories.
filterslist of tuple (str, str), optional: Filters are of the form (field, label). Only one filter per field allowed. A file that does not match a filter will be discarded. Filter examples would be (‘ses’, ‘01’), (‘dir’, ‘ap’) and (‘task’, ‘localizer’).
sub_folderbool, default=True: Determines if the files searched are at the level of subject/session folders or just below the dataset main folder. Setting this option to False with other default values would return all the files below the main directory, ignoring files in subject or derivatives folders.

Returns:

fileslist of str: List of file paths found.