fsleyes.plugins.controls.filetreepanel.manager

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.plugins.controls.filetreepanel.manager.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.plugins.controls.filetreepanel.manager.FileGroup(varyings, fixed, ftypes, files)

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 called varyings, files, and fixedvars.

Another attribute, fileIDs, contains a unique ID for each file within one FileGroup. This ID can be used to pair up files from different FileGroup objects.

__init__(varyings, fixed, ftypes, files)

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 as None.

__str__()

Return a string representation of this FileGroup.

__repr__()

Return a string representation of this FileGroup.

__eq__(other)

Return True if this FileGroup is equal to other.

__dict__ = mappingproxy({'__module__': 'fsleyes.plugins.controls.filetreepanel.manager', '__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__>, '__repr__': <function FileGroup.__repr__>, '__eq__': <function FileGroup.__eq__>, '__dict__': <attribute '__dict__' of 'FileGroup' objects>, '__weakref__': <attribute '__weakref__' of 'FileGroup' objects>, '__hash__': None, '__annotations__': {}})

__hash__ = None

__module__ = 'fsleyes.plugins.controls.filetreepanel.manager'

__weakref__

list of weak references to the object (if defined)

class fsleyes.plugins.controls.filetreepanel.manager.FileTreeManager(overlayList, displayCtx, query)

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 an OverlayManager which handles overlay display.

__init__(overlayList, displayCtx, query)

Create a FileTreeManager.

Parameters

• overlayList – The OverlayList

• displayCtx – The DisplayContext which is to manage the file tree overlay display.

• query – FileTreeQuery instance

destroy()

Must be called when this FileTreeManager is no longer needed. Destroys the OverlayManager and clears references.

update(ftypes, varyings, fixed)

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)

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)

Show the overlays associated with a FileGroup.

All arguments are passed through to the OverlayManager.show() method.

property query

Returns the FileTreeQuery object used by this FileTreeManager.

property ftypes

Returns a list of all file types to be displayed.

property varyings

Returns a dict of { var : [value] } mappings, containing every possible value for each varying variable.

property 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.

property varcols

Returns a list of varying variable names to be used as columns for the varying variables.

property 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.

property filegroups

Returns a list containing all of the FileGroup objects. Each FileGroup represents one row in the file tree grid.

__dict__ = mappingproxy({'__module__': 'fsleyes.plugins.controls.filetreepanel.manager', '__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>, '__annotations__': {}})

__module__ = 'fsleyes.plugins.controls.filetreepanel.manager'

__weakref__

list of weak references to the object (if defined)

fsleyes.plugins.controls.filetreepanel.manager.prepareVaryings(query, ftypes, varyings)

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.

fsleyes.plugins.controls.filetreepanel.manager.prepareFixed(query, ftypes, fixed)

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.

fsleyes.plugins.controls.filetreepanel.manager.genColumns(ftypes, varyings, fixed)

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 (see prepareVaryings()).

• 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, containing fixed variable values

fsleyes.plugins.controls.filetreepanel.manager.genFileGroups(query, varyings, fixed)

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 (see prepareVaryings()).

• 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.

fsleyes.plugins.controls.filetreepanel.manager.filterFileGroups(filegroups, fixedcols)

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 and fixedcols

class fsleyes.plugins.controls.filetreepanel.manager.OverlayManager(overlayList, displayCtx)

Bases: object

The OverlayManager is used by the FileTreeManager. It manages the mechanics of displaying overlays associated with the file tree.

The update() method is used to tell the OverlayManager about the currently displayed list of FileGroup objects. The show() method is used to show the overlays in a specific FileGroup.

Whenever the show() method is called, the overlays from any previously displayed FileGroup are “swapped” out for the overlays in the new FileGroup. The display properties for matching pairs of overlays are preserved as best as possible.

__init__(overlayList, displayCtx)

Create an OverlayManager

Parameters

• overlayList – The OverlayList

• displayCtx – The DisplayContext which is to manage the file tree overlay display.

destroy()

Must be called when this OverlayManager is no longer needed. Clears references.

update(filegroups)

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)

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.

__load(new, old, callback=None)

Called by show(). Loads the files specified in new, then passes them (along with the old) 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.

__show(new, old)

Adds the given new overlays to the OverlayList. The display properties of any old 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.plugins.controls.filetreepanel.manager', '__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>, '__annotations__': {}})

__module__ = 'fsleyes.plugins.controls.filetreepanel.manager'

__weakref__

list of weak references to the object (if defined)

fsleyes.plugins.controls.filetreepanel.manager.REPLACE = <MagicMock name='mock.utils.typedict.TypeDict()' id='4116378456'>

This dict contains DisplayOpts properties which refer to other images, and which need to be explicitly handled when the OverlayManager swaps a group of overlays in for another.

fsleyes.plugins.controls.filetreepanel.manager.SKIP = <MagicMock name='mock.utils.typedict.TypeDict()' id='4116378456'>

This dict contains DisplayOpts properties which are not copied when the OverlayManager swaps a group of overlays in for an existing group.

class fsleyes.plugins.controls.filetreepanel.manager.ToReplace(value)

Bases: object

Placeholder type used by the getProperties() function when a property value is in the REPLACE dictionary, and needs to be explicitly handled by the OverlayManager.

__dict__ = mappingproxy({'__module__': 'fsleyes.plugins.controls.filetreepanel.manager', '__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>, '__annotations__': {}})

__init__(value)

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'fsleyes.plugins.controls.filetreepanel.manager'

__weakref__

list of weak references to the object (if defined)

fsleyes.plugins.controls.filetreepanel.manager.getProperties(ovl, displayCtx)

Retrieves the Display and DisplayOpts properties for the given overlay, applying the rules defined by the REPLACE and SKIP dictionaries.

Parameters

• ovl – An overlay

• displayCtx – The DisplayContext managing the overlay display.

Returns

a dict of { name : value} mappings.