`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)[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 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.

__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) → 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 of Match arrays that are returned by the query() 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 that template type are returned.

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

property templates: List[str]: 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 specified variables. All hits are returned for variables that are unspecified.

Parameters:

template – Template 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 templates 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).

__dict__ = mappingproxy({'__module__': 'fsl.utils.filetree.query', '__doc__': "The ``FileTreeQuery`` class uses a :class:`.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 :class:`.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 fsl.utils.filetree import FileTree, 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>, 'query': <function FileTreeQuery.query>, '__dict__': <attribute '__dict__' of 'FileTreeQuery' objects>, '__weakref__': <attribute '__weakref__' of 'FileTreeQuery' objects>, '__annotations__': {}})

__module__ = 'fsl.utils.filetree.query'

__weakref__: list of weak references to the object (if defined)

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 a FileTree. The scan() function and FileTree.query() method both return Match objects.

__init__(filename, template, tree, variables)[source]

Create a Match object. All arguments are added as attributes.

Parameters:

filename – name of existing file
template – template identifier
tree – FileTree which contains this Match
variables – Dictionary of {variable : value} mappings containing all variables present in the file name.

property filename

property template

property full_name

The full_name of a Match is a combination of the template (i.e. the matched template), and the name(s) of the relevant FileTree objects.

It allows one to unamiguously identify the location of a Match in a FileTree hierarchy, where the same short_name may be used in different sub-trees.

property tree

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__': 'fsl.utils.filetree.query', '__doc__': 'A ``Match`` object represents a file with a name matching a template in\n a ``FileTree``. The :func:`scan` function and :meth:`FileTree.query`\n method both return ``Match`` objects.\n ', '__init__': <function Match.__init__>, 'filename': <property object>, 'template': <property object>, 'full_name': <property object>, 'tree': <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__ = 'fsl.utils.filetree.query'

__weakref__: list of weak references to the object (if defined)

fsl.utils.filetree.query.scan(tree: FileTree) → List[Match][source]

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

Parameters:: tree – FileTree to scan
Returns:: list of Match objects

fsl.utils.filetree.query.allVariables(tree: FileTree, matches: List[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 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 { full_name : [variables] } mappings, containing the variables which are relevant to each template.

fsl.utils.filetree.query

`fsl.utils.filetree.query`