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:
Scans the directory of the given |
|
Identifies the |
-
class
fsl.utils.filetree.query.
FileTreeQuery
(tree)¶ Bases:
object
The
FileTreeQuery
class uses aFileTree
to search a directory for files which match a specific query.A
FileTreeQuery
scans the contents of a directory which is described by aFileTree
, 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. Thequery()
method can be used to retrieve files which match a specific short name, and variable values.The
query()
method returns a multi-dimensionalnumpy.array
which containsMatch
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 ofMatch
arrays that are returned by thequery()
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 thatshort_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 specifiedvariables
. All hits are returned for variables that are unspecified.- Parameters
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 anumpy.array
ifasarray=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 aFileTree
. Thescan()
function andFileTree.query()
method both returnMatch
objects.-
property
filename
¶
-
property
short_name
¶
-
property
variables
¶
-
property
-
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
objectmatches – list of
Match
objects (e.g. as returned byscan()
)
- Returns
a tuple containing two dicts:
A dict of
{ variable : [values] }
mappings containing all variables and their possible values present in the given list ofMatch
objects.A dict of
{ short_name : [variables] }
mappings, containing the variables which are relevant to each short name.