fsl.utils.filetree.query

This module contains the FileTreeQuery class, which can be used to search for files in a directory described by a .FileTree. A FileTreeQuery object returns Match objects which each represent a file that is described by the FileTree, and which is present in the directory.

The following utility functions, used by the FileTreeQuery class, are also defined in this module:

scan

Scans the directory of the given FileTree to find all files which match a tree template.

allVariables

Identifies the FileTree variables which are actually represented in files in the directory.

class fsl.utils.filetree.query.FileTreeQuery(tree)

Bases: object

The FileTreeQuery class uses a FileTree to search a directory for files which match a specific query.

A FileTreeQuery scans the contents of a directory which is described by a FileTree, and identifies all file types (a.k.a. templates or short names) that are present, and the values of variables within each short name that are present. The query() method can be used to retrieve files which match a specific short name, and variable values.

The query() method returns a multi-dimensional numpy.array which contains Match objects, where each dimension one represents variable for the short name in question.

Example usage:

>>> from fsl.utils.filetree import FileTree, FileTreeQuery

>>> tree  = FileTree.read('bids_raw', './my_bids_data')
>>> query = FileTreeQuery(tree)

>>> query.axes('anat_image')
['acq', 'ext', 'modality', 'participant', 'rec', 'run_index',
 'session']

>>> query.variables('anat_image')
{'acq': [None],
 'ext': ['.nii.gz'],
 'modality': ['T1w', 'T2w'],
 'participant': ['01', '02', '03'],
 'rec': [None],
 'run_index': [None, '01', '02', '03'],
 'session': [None]}

>>> query.query('anat_image', participant='01')
array([[[[[[[Match(./my_bids_data/sub-01/anat/sub-01_T1w.nii.gz)],
            [nan],
            [nan],
            [nan]]]],

         [[[[Match(./my_bids_data/sub-01/anat/sub-01_T2w.nii.gz)],
            [nan],
            [nan],
            [nan]]]]]]], dtype=object)
axes(short_name) → List[str]

Returns a list containing the names of variables present in files of the given short_name type, in the same order of the axes of Match arrays that are returned by the query() method.

variables(short_name=None) → Dict[str, List]

Return a dict of {variable : [values]} mappings. This dict describes all variables and their possible values in the tree.

If a short_name is specified, only variables which are present in files of that short_name type are returned.

property short_names

Returns a list containing all short names of the FileTree that are present in the directory.

query(short_name, asarray=False, **variables)

Search for files of the given short_name, which match the specified variables. All hits are returned for variables that are unspecified.

Parameters
  • short_name – Short name of files to search for.

  • asarray – If True, the relevant Match objects are returned in a in a ND numpy.array where each dimension corresponds to a variable for the short_name in question (as returned by axes()). Otherwise (the default), they are returned in a list.

All other arguments are assumed to be variable=value pairs, used to restrict which matches are returned. All values are returned for variables that are not specified, or variables which are given a value of '*'.

Returns

A list of Match objects, (or a numpy.array if asarray=True).

class fsl.utils.filetree.query.Match(filename, short_name, variables)

Bases: object

A Match object represents a file with a name matching a template in a FileTree. The scan() function and FileTree.query() method both return Match objects.

property filename
property short_name
property variables
fsl.utils.filetree.query.scan(tree: fsl.utils.filetree.filetree.FileTree) → List[fsl.utils.filetree.query.Match]

Scans the directory of the given FileTree to find all files which match a tree template.

Returns

list of Match objects

fsl.utils.filetree.query.allVariables(tree: fsl.utils.filetree.filetree.FileTree, matches: List[fsl.utils.filetree.query.Match]) → Tuple[Dict[str, List], Dict[str, List]]

Identifies the FileTree variables which are actually represented in files in the directory.

Parameters
  • filetree – The FileTree object

  • matches – list of Match objects (e.g. as returned by scan())

Returns

a tuple containing two dicts:

  • A dict of { variable : [values] } mappings containing all variables and their possible values present in the given list of Match objects.

  • A dict of { short_name : [variables] } mappings, containing the variables which are relevant to each short name.