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)[source]¶ 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 template, and variable values.The
query()
method returns a collection ofMatch
objects, each of which represents one file which matches the query.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') [Match(./my_bids_data/sub-01/anat/sub-01_T1w.nii.gz), Match(./my_bids_data/sub-01/anat/sub-01_T2w.nii.gz)]
Matches for templates contained within sub-trees are referred to by constructing a hierarchical path from the sub-tree template name(s), and the template name - see the
Match.full_name()
method.-
axes
(template) → List[str][source]¶ Returns a list containing the names of variables present in files of the given
template
type, in the same order of the axes ofMatch
arrays that are returned by thequery()
method.
-
variables
(template=None) → Dict[str, List][source]¶ Return a dict of
{variable : [values]}
mappings. This dict describes all variables and their possible values in the tree.If a
template
is specified, only variables which are present in files of thattemplate
type are returned.
-
property
templates
¶ Returns a list containing all templates of the
FileTree
that are present in the directory.
-
query
(template, asarray=False, **variables)[source]¶ Search for files of the given
template
, 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, template, tree, variables)[source]¶ 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
template
¶
-
property
full_name
¶ The
full_name
of aMatch
is a combination of thetemplate
(i.e. the matched template), and the name(s) of the relevantFileTree
objects.It allows one to unamiguously identify the location of a
Match
in aFileTree
hierarchy, where the sameshort_name
may be used in different sub-trees.
-
property
tree
¶
-
property
variables
¶
-
property
-
fsl.utils.filetree.query.
scan
(tree: fsl.utils.filetree.filetree.FileTree) → List[fsl.utils.filetree.query.Match][source]¶ Scans the directory of the given
FileTree
to find all files which match a tree template.
-
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]][source]¶ 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
{ full_name : [variables] }
mappings, containing the variables which are relevant to each template.