`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:

scan

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

class fsleyes.plugins.controls.filetreepanel.query.FileTreeQuery(tree)[source]¶

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 template, and variable values.

The query() method returns a collection of Match 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 the scan() 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 that template type are returned.

property tree¶: Returns the FileTree associated with this FileTreeQuery.

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 given template.

query(template, **variables)[source]¶

Search for files of the given template, which match the specified variables. 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 a FileTree. The FileTree.query() method returns Match 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¶

__eq__(other)[source]¶: Return self==value.

__lt__(other)[source]¶: Return self<value.

__repr__()[source]¶: Returns a string representation of this Match.

__str__()[source]¶: Returns a string representation of this Match.

__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 each DataArray 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 scan
filterEmpty – 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.

fsleyes.plugins.controls.filetreepanel.query¶

`fsleyes.plugins.controls.filetreepanel.query`¶