fsleyes.controls.filetreemanager
¶
This module contains the FileTreeManager
, which is used by the
FileTreePanel
. It also contains the OverlayManager
, which
is used by the FileTreeManager
.
Overview¶
The FileTreePanel
allows the user to navigate structured
directories, where the files and sub-directories are named according to a
filetree
specification. The FileTreePanel
allows the user to
select which file types to display, and to restrict or re-order the files
with file tree variables.
By default, the FileTreePanel
will display a list containing one row
for every combination of variable values; each row will contain all files for
(the selected file types) which correspond to that combination of variables.
The user may also choose to display <all>
values of a specific variable on
a single row.
This module handles the mechanics of generating lists of variables and files according to the user’s settings.
In this module, and in the filetreepanel
module, variables which take
on a different value for each row are referred to as varying, and variables
for which all possible values are displaed on one row are referred to as
fixed.
Example¶
For example, imagine that we have a data set with data for multiple subjects
(sub
) and sessions (ses
), described by this file tree:
subj-{participant}
[ses-{session}]
T1w.nii.gz (T1w)
{hemi}.gii (surface)
So for one subject and one session, we might have the following files:
T1.nii.gz
L.gii
R.gii
So we have two files types (T1
and surface
), and three variables
(sub
, ses
, and hemi
). By default, all variables are varying, so
the FileTreePanel
will display this data set like so (the x
indicates
whether or not each file is present):
sub |
ses |
hemi |
T1 |
surface |
1 |
1 |
L |
x |
x |
1 |
1 |
R |
x |
x |
1 |
2 |
L |
x |
x |
1 |
2 |
R |
x |
x |
2 |
1 |
L |
x |
x |
2 |
1 |
R |
x |
x |
2 |
2 |
L |
x |
x |
2 |
2 |
R |
x |
x |
However, it may make more sense to display all of the surface files together.
The user can do this by setting the hemi
variable to <all>
, thus
changing it to a fixed variable. This will cause the FileTreePanel
to re-arrange the grid like so:
sub |
ses |
T1 |
surface[hemi=L] |
surface[hemi=R] |
1 |
1 |
x |
x |
x |
1 |
2 |
x |
x |
x |
2 |
1 |
x |
x |
x |
2 |
2 |
x |
x |
x |
-
fsleyes.controls.filetreemanager.
FILETREE_PREFIX
= '[filetree] '¶ This is a prefix added to the name of every overlay which is added to the
OverlayList
by this module.
-
class
fsleyes.controls.filetreemanager.
FileGroup
(varyings, fixed, ftypes, files)[source]¶ Bases:
object
A
FileGroup
represents a single row in the file tree panel list. It encapsulates a set of values for all varying variables, and a set of files and their associated fixed variable values. These are all accessible as attributes calledvaryings
,files
, andfixedvars
.Another attribute,
fileIDs
, contains a unique ID for each file within oneFileGroup
. This ID can be used to pair up files from differentFileGroup
objects.-
__init__
(varyings, fixed, ftypes, files)[source]¶ Create a
FileGroup
.Parameters: - varyings – Dict of
{ var : val }
mappings containing the varying variable values. - fixed – List containing
{ var : val }
mappings, each containing the fixed variable values for each file. - ftypes – List containing the file type for each file.
- files – List of file names, the same length as
fixedvars
. Missing files are represented asNone
.
- varyings – Dict of
-
__dict__
= mappingproxy({'__module__': 'fsleyes.controls.filetreemanager', '__doc__': 'A ``FileGroup`` represents a single row in the file tree panel list. It\n encapsulates a set of values for all varying variables, and a set of files\n and their associated fixed variable values. These are all accessible as\n attributes called ``varyings``, ``files``, and ``fixedvars``.\n\n Another attribute, ``fileIDs``, contains a unique ID for each file within\n one ``FileGroup``. This ID can be used to pair up files from different\n ``FileGroup`` objects.\n ', '__init__': <function FileGroup.__init__>, '__str__': <function FileGroup.__str__>, '__eq__': <function FileGroup.__eq__>, '__dict__': <attribute '__dict__' of 'FileGroup' objects>, '__weakref__': <attribute '__weakref__' of 'FileGroup' objects>, '__hash__': None})¶
-
__hash__
= None¶
-
__module__
= 'fsleyes.controls.filetreemanager'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
fsleyes.controls.filetreemanager.
FileTreeManager
(overlayList, displayCtx, query)[source]¶ Bases:
object
The
FileTreeManager
class handles the generation and arranging of varying and fixed variables, and file types, according to a specification of varying and fixed variables.The
FileTreeManager
creates and uses anOverlayManager
which handles overlay display.-
__init__
(overlayList, displayCtx, query)[source]¶ Create a
FileTreeManager
.Parameters: - overlayList – The
OverlayList
- displayCtx – The
DisplayContext
which is to manage the file tree overlay display. - query –
FileTreeQuery
instance
- overlayList – The
-
destroy
()[source]¶ Must be called when this
FileTreeManager
is no longer needed. Destroys theOverlayManager
and clears references.
-
update
(ftypes, varyings, fixed)[source]¶ Update the internal file tree grid information according to the given file types and variables.
Parameters: - ftypes – List of file types that are to be displayed
- varyings – Dict of
{var : value}
mappings defining the varying variables. - fixed – List of variable names defining the fixed variables.
-
reorder
(varcols)[source]¶ Re-order the file groups according to the new varying variable order. The first varying variable is the slowest changing.
Parameters: varcols – List of varying variable names.
-
show
(filegroup, callback=None)[source]¶ Show the overlays associated with a
FileGroup
.All arguments are passed through to the
OverlayManager.show()
method.
-
query
¶ Returns the
FileTreeQuery
object used by thisFileTreeManager
.
-
ftypes
¶ Returns a list of all file types to be displayed.
-
varyings
¶ Returns a dict of
{ var : [value] }
mappings, containing every possible value for each varying variable.
-
fixed
¶ Returns a dict of
{ ftype : { var : [value] } }
mappings which, for each file type, contains a dictionary of all fixed variables and their possible values.
-
varcols
¶ Returns a list of varying variable names to be used as columns for the varying variables.
-
fixedcols
¶ - Returns a list of tuples, with each tuple containing:
- A file type
- A dict of
{var : value}
mappings, containing fixed variable values
Each tuple represents a column for a combination of file type and fixed variable values.
-
filegroups
¶ Returns a list containing all of the
FileGroup
objects. EachFileGroup
represents one row in the file tree grid.
-
__dict__
= mappingproxy({'__module__': 'fsleyes.controls.filetreemanager', '__doc__': 'The ``FileTreeManager`` class handles the generation and arranging\n of varying and fixed variables, and file types, according to a\n specification of *varying* and *fixed* variables.\n\n The ``FileTreeManager`` creates and uses an :class:`OverlayManager` which\n handles overlay display.\n ', '__init__': <function FileTreeManager.__init__>, 'destroy': <function FileTreeManager.destroy>, 'update': <function FileTreeManager.update>, 'reorder': <function FileTreeManager.reorder>, 'show': <function FileTreeManager.show>, 'query': <property object>, 'ftypes': <property object>, 'varyings': <property object>, 'fixed': <property object>, 'varcols': <property object>, 'fixedcols': <property object>, 'filegroups': <property object>, '__dict__': <attribute '__dict__' of 'FileTreeManager' objects>, '__weakref__': <attribute '__weakref__' of 'FileTreeManager' objects>})¶
-
__module__
= 'fsleyes.controls.filetreemanager'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
fsleyes.controls.filetreemanager.
prepareVaryings
(query, ftypes, varyings)[source]¶ Called by
FileTreeManager.update()
. Prepares a dictionary which contains all possible values for each varying variable.Parameters: - query –
FileTreeQuery
object - ftypes – List of file types to be displayed.
- varyings – Dict of
{ var : value }
mappings. A value of'*'
indicates that all possible values for this variable should be used.
Returns: A dict of
{ var : [value] }
mappings, containing every possible value for each varying variable.- query –
-
fsleyes.controls.filetreemanager.
prepareFixed
(query, ftypes, fixed)[source]¶ Called by
FileTreeManager.update()
. Prepares a dictionary which contains all possible values for each fixed variable, and for each file type.Parameters: - query –
FileTreeQuery
object - ftypes – List of file types to be displayed
- fixed – List of fixed variables
Returns: A dict of
{ ftype : { var : [value] } }
mappings which, for each file type, contains a dictionary of all fixed variables and their possible values.- query –
-
fsleyes.controls.filetreemanager.
genColumns
(ftypes, varyings, fixed)[source]¶ Determines all columns which need to be present in a file tree grid for the given file types, varying and fixed variables.
Parameters: - ftypes – List of file types to be displayed
- varyings – Dict of
{ var : [value} }
mappings, containing all varying variables and their possible values (seeprepareVaryings()
). - fixed – Dict of
{ ftype : { var : [value] } }
mappings which, for each file type, contains a dictionary of all fixed variables and their possible values.
Returns: Two lists which, combined, represent all columns to be displayed in the file tree grid:
A list of varying variable names
A list of tuples, with each tuple containing: - A file type - A dict of
{var : value}
mappings, containingfixed variable values
-
fsleyes.controls.filetreemanager.
genFileGroups
(query, varyings, fixed)[source]¶ Generates a list of
FileGroup
objects, each representing one row in a grid defined by the given set of varying and fixed variables.Parameters: - query –
FileTreeQuery
object - varyings – Dict of
{ var : [value} }
mappings, containing all varying variables and their possible values (seeprepareVaryings()
). - fixed – List of tuples of
(ftype, { var : value })
mappings, which each contain a file type and set of fixed variables corresponding to one column in the grid.
Returns: A list of
FileGroup
objects.- query –
-
fsleyes.controls.filetreemanager.
filterFileGroups
(filegroups, fixedcols)[source]¶ Filters out empty, duplicate and redundant rows, and empty columns, from
filegroups
Parameters: - filegroups – List of
FileGroup
objects. - fixedcols – List of
(ftype, { var : value })
mappings
Returns: A tuple containing the filtered
filegroups
andfixedcols
- filegroups – List of
-
class
fsleyes.controls.filetreemanager.
OverlayManager
(overlayList, displayCtx)[source]¶ Bases:
object
The
OverlayManager
is used by theFileTreeManager
. It manages the mechanics of displaying overlays associated with the file tree.The
update()
method is used to tell theOverlayManager
about the currently displayed list ofFileGroup
objects. Theshow()
method is used to show the overlays in a specificFileGroup
.Whenever the
show()
method is called, the overlays from any previously displayedFileGroup
are “swapped” out for the overlays in the newFileGroup
. The display properties for matching pairs of overlays are preserved as best as possible.-
__init__
(overlayList, displayCtx)[source]¶ Create an
OverlayManager
Parameters: - overlayList – The
OverlayList
- displayCtx – The
DisplayContext
which is to manage the file tree overlay display.
- overlayList – The
-
update
(filegroups)[source]¶ Must be called when the list of
FileGroup
objects has changed, either due to them being re-ordered or completely changed.
-
show
(filegroup, callback=None)[source]¶ Show the overlays associated with the given
FileGroup
.Any overlays which were previously displayed are removed, and replaced with the overlays associated with the new group.
Parameters: - filegroup –
FileGroup
to show - callback – Optional function which will be called when the overlays have been shown. Will not be called if no new overlays are to be shown.
- filegroup –
-
_OverlayManager__load
(new, old, callback=None)¶ Called by
show()
. Loads the files specified innew
, then passes them (along with theold
) to the__show()
method.Parameters: - new – Dict of
{fileid : file}
mappings, containing the files to load. - old – Dict of
{fileid : overlay}
mappings, containing the existing overlays which will be replaced with the new ones. - callback – No-args function which will be called after the new overlays have been loaded.
- new – Dict of
-
_OverlayManager__show
(new, old)¶ Adds the given
new
overlays to theOverlayList
. The display properties of anyold
overlays with the same ID are copied over to the new ones.All existing overlays which were previously added are removed.
-
__dict__
= mappingproxy({'__module__': 'fsleyes.controls.filetreemanager', '__doc__': 'The ``OverlayManager`` is used by the :class:`FileTreeManager`. It\n manages the mechanics of displaying overlays associated with the file tree.\n\n The :meth:`update` method is used to tell the ``OverlayManager`` about the\n currently displayed list of :class:`FileGroup` objects. The :meth:`show`\n method is used to show the overlays in a specific ``FileGroup``.\n\n Whenever the :meth:`show` method is called, the overlays from any\n previously displayed ``FileGroup`` are "swapped" out for the overlays in\n the new ``FileGroup``. The display properties for matching pairs of\n overlays are preserved as best as possible.\n ', '__init__': <function OverlayManager.__init__>, 'destroy': <function OverlayManager.destroy>, 'update': <function OverlayManager.update>, 'show': <function OverlayManager.show>, '_OverlayManager__load': <function OverlayManager.__load>, '_OverlayManager__show': <function OverlayManager.__show>, '__dict__': <attribute '__dict__' of 'OverlayManager' objects>, '__weakref__': <attribute '__weakref__' of 'OverlayManager' objects>})¶
-
__module__
= 'fsleyes.controls.filetreemanager'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
fsleyes.controls.filetreemanager.
REPLACE
= <MagicMock name='mock.utils.typedict.TypeDict()' id='4120962348'>¶ This dict contains
DisplayOpts
properties which refer to other images, and which need to be explicitly handled when theOverlayManager
swaps a group of overlays in for another.
-
fsleyes.controls.filetreemanager.
SKIP
= <MagicMock name='mock.utils.typedict.TypeDict()' id='4120962348'>¶ This dict contains
DisplayOpts
properties which are not copied when theOverlayManager
swaps a group of overlays in for an existing group.
-
class
fsleyes.controls.filetreemanager.
ToReplace
(value)[source]¶ Bases:
object
Placeholder type used by the
getProperties()
function when a property value is in theREPLACE
dictionary, and needs to be explicitly handled by theOverlayManager
.-
__dict__
= mappingproxy({'__module__': 'fsleyes.controls.filetreemanager', '__doc__': 'Placeholder type used by the :func:`getProperties` function when a\n property value is in the :attr:`REPLACE` dictionary, and needs to be\n explicitly handled by the :class:`OverlayManager`.\n ', '__init__': <function ToReplace.__init__>, '__dict__': <attribute '__dict__' of 'ToReplace' objects>, '__weakref__': <attribute '__weakref__' of 'ToReplace' objects>})¶
-
__module__
= 'fsleyes.controls.filetreemanager'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
fsleyes.controls.filetreemanager.
getProperties
(ovl, displayCtx)[source]¶ Retrieves the
Display
andDisplayOpts
properties for the given overlay, applying the rules defined by theREPLACE
andSKIP
dictionaries.Parameters: - ovl – An overlay
- displayCtx – The
DisplayContext
managing the overlay display.
Returns: a dict of
{ name : value}
mappings.