fsleyes.plugins.controls.filetreepanel.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 |
- class fsleyes.plugins.controls.filetreepanel.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 file_tree import FileTree >>> from fsleyes.filetree import 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.- __init__(tree)[source]
Create a
FileTreeQuery
. The contents of the tree directory are scanned via thescan()
function, which may take some time for large data sets.- Parameters
tree – The
FileTree
object
- axes(template)[source]
Returns a list containing the names of variables present in files of the given
template
type.
- variables(template=None)[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 tree
Returns the
FileTree
associated with thisFileTreeQuery
.
- property templates
Returns a list containing all templates of the
FileTree
that are present in the directory.
- matcharray(template)[source]
Returns a reference to the
xarray.DataArray
which contains the file paths for the giventemplate
.
- query(template, **variables)[source]
Search for files of the given
template
, which match the specifiedvariables
. All hits are returned for variables that are unspecified.- Parameters
template – Template of files to search for.
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
- __dict__ = mappingproxy({'__module__': 'fsleyes.plugins.controls.filetreepanel.query', '__doc__': "The ``FileTreeQuery`` class uses a ``FileTree`` to search\n a directory for files which match a specific query.\n\n A ``FileTreeQuery`` scans the contents of a directory which is described\n by a ``FileTree``, and identifies all file types (a.k.a. *templates*\n or *short names*) that are present, and the values of variables within each\n short name that are present. The :meth:`query` method can be used to\n retrieve files which match a specific template, and variable values.\n\n The :meth:`query` method returns a collection of :class:`Match` objects,\n each of which represents one file which matches the query.\n\n Example usage::\n\n >>> from file_tree import FileTree\n >>> from fsleyes.filetree import FileTreeQuery\n\n >>> tree = FileTree.read('bids_raw', './my_bids_data')\n >>> query = FileTreeQuery(tree)\n\n >>> query.axes('anat_image')\n ['acq', 'ext', 'modality', 'participant', 'rec', 'run_index',\n 'session']\n\n >>> query.variables('anat_image')\n {'acq': [None],\n 'ext': ['.nii.gz'],\n 'modality': ['T1w', 'T2w'],\n 'participant': ['01', '02', '03'],\n 'rec': [None],\n 'run_index': [None, '01', '02', '03'],\n 'session': [None]}\n\n >>> query.query('anat_image', participant='01')\n [Match(./my_bids_data/sub-01/anat/sub-01_T1w.nii.gz),\n Match(./my_bids_data/sub-01/anat/sub-01_T2w.nii.gz)]\n\n\n Matches for templates contained within sub-trees are referred to by\n constructing a hierarchical path from the sub-tree template name(s),\n and the template name - see the :meth:`Match.full_name` method.\n ", '__init__': <function FileTreeQuery.__init__>, 'axes': <function FileTreeQuery.axes>, 'variables': <function FileTreeQuery.variables>, 'tree': <property object>, 'templates': <property object>, 'matcharray': <function FileTreeQuery.matcharray>, 'query': <function FileTreeQuery.query>, '__dict__': <attribute '__dict__' of 'FileTreeQuery' objects>, '__weakref__': <attribute '__weakref__' of 'FileTreeQuery' objects>, '__annotations__': {}})
- __module__ = 'fsleyes.plugins.controls.filetreepanel.query'
- __weakref__
list of weak references to the object (if defined)
- class fsleyes.plugins.controls.filetreepanel.query.Match(filename, template, variables)[source]
Bases:
object
A
Match
object represents a file with a name matching a template in aFileTree
. TheFileTree.query()
method returnsMatch
objects.- __init__(filename, template, variables)[source]
Create a
Match
object. All arguments are added as attributes.- Parameters
template – template identifier
value –
- property filename
- property template
- property variables
- __dict__ = mappingproxy({'__module__': 'fsleyes.plugins.controls.filetreepanel.query', '__doc__': 'A ``Match`` object represents a file with a name matching a template in\n a ``FileTree``. The :meth:`FileTree.query` method returns ``Match``\n objects.\n ', '__init__': <function Match.__init__>, 'filename': <property object>, 'template': <property object>, 'variables': <property object>, '__eq__': <function Match.__eq__>, '__lt__': <function Match.__lt__>, '__repr__': <function Match.__repr__>, '__str__': <function Match.__str__>, '__dict__': <attribute '__dict__' of 'Match' objects>, '__weakref__': <attribute '__weakref__' of 'Match' objects>, '__hash__': None, '__gt__': <function _gt_from_lt>, '__le__': <function _le_from_lt>, '__ge__': <function _ge_from_lt>, '__annotations__': {}})
- __ge__(other, NotImplemented=NotImplemented)
Return a >= b. Computed by @total_ordering from (not a < b).
- __gt__(other, NotImplemented=NotImplemented)
Return a > b. Computed by @total_ordering from (not a < b) and (a != b).
- __hash__ = None
- __le__(other, NotImplemented=NotImplemented)
Return a <= b. Computed by @total_ordering from (a < b) or (a == b).
- __module__ = 'fsleyes.plugins.controls.filetreepanel.query'
- __weakref__
list of weak references to the object (if defined)
- fsleyes.plugins.controls.filetreepanel.query.scan(tree, filterEmpty=True)[source]
Scans the directory of the given
FileTree
to find all files which match a tree template.A dictionary of
{template : xarray.DataArray}
mappings is returned, where eachDataArray
has dimensions corresponding to variables used in the template, and contains names (as strings) of matching files present on disk as strings. Entries in an arrays for variable values which do not exist on disk are set to the empty string.See the
file_tree.FileTree.get_mult_glob
method for more details.- Parameters
tree –
FileTree
to scanfilterEmpty – If
True
(the default), file tree templates which do not match any files on disk are not returned.
- Returns
A dict of
{template : xarray.DataArray}
objects, one for each template.