fsl.utils.filetree.filetree

exception fsl.utils.filetree.filetree.MissingVariable[source]

Bases: KeyError

Returned when the variables of a tree or its parents do not contain a given variable

__module__ = 'fsl.utils.filetree.filetree'
__weakref__

list of weak references to the object (if defined)

class fsl.utils.filetree.filetree.FileTree(templates: Dict[str, str], variables: Dict[str, Any], sub_trees: Dict[str, FileTree] = None, parent: Optional[FileTree] = None, name: str = None)[source]

Bases: object

Contains the input/output filename tree

Properties:

  • templates: dictionary mapping short names to filename templates

  • variables: dictionary mapping variables in the templates to specific values (variables set to None are explicitly unset)

  • sub_trees: filename trees describing specific sub-directories

  • parent: parent FileTree, of which this sub-tree is a sub-directory

  • name: descriptive name of the tree

__init__(templates: Dict[str, str], variables: Dict[str, Any], sub_trees: Dict[str, FileTree] = None, parent: Optional[FileTree] = None, name: str = None)[source]

Creates a new filename tree.

property parent

Parent FileTree, of which this sub-tree is a sub-directory

property name

Name of this FileTree, or None if it has no name.

property all_variables

All tree variables including those inherited from the parent tree

get_variable(name: str, default=None) → str[source]

Gets a variable used to fill out the template

Parameters
  • name – variable name

  • default – default variables (if not set a MissingVariable error is raised if a variable is missing)

Returns

value of the variable

_get_template_tree(short_name: str) → Tuple[fsl.utils.filetree.filetree.FileTree, str][source]

Retrieves template text from this tree, parent tree or sub_tree

Parameters

short_name – filename reference name

Returns

tuple with the containing tree and the template text

get_template(short_name: str) → Tuple[str, Dict[str, str]][source]

Returns the sub-tree that defines a given short name

  • ‘/’ characters in short_name refer to sub-trees

  • ‘../’ characters in short_name refer to parents

For example:

  • “eddy/output” refers to the “output” in the “eddy” sub_tree (i.e. self.sub_trees['eddy'].templates['output'])

  • “../other/name” refers to the “other” sub-tree of the parent tree (i.e., self.parent.sub_trees['other'].templates['name'])

Parameters

short_name – name of the template

Returns

tuple with the template and the variables corresponding to the template

template_variables(short_name: Optional[str] = None, optional=True, required=True) → Set[str][source]

Returns the variables needed to define a template

Parameters
  • short_name – name of the template (defaults to all)

  • optional – if set to False don’t include the optional variables

  • required – if set to False don’t include the required variables

Returns

set of variable names

get(short_name, make_dir=False) → str[source]

Gets a full filename based on its short name

Parameters
  • short_name – identifier in the tree

  • make_dir – if True make sure that the directory leading to this file exists

Returns

full filename

get_all(short_name: str, glob_vars=()) → Tuple[str][source]

Gets all existing directory/file names matching a specific pattern

Parameters
  • short_name – short name of the path template

  • glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk. Any defined variables in glob_vars will be ignored. If glob_vars is set to ‘all’, all undefined variables will be used to look up matches.

Returns

sorted sequence of paths

get_all_vars(short_name: str, glob_vars=()) → Tuple[Dict[str, str]][source]

Gets all the parameters that generate existing filenames

Parameters
  • short_name – short name of the path template

  • glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk. Any defined variables in glob_vars will be ignored. If glob_vars is set to ‘all’, all undefined variables will be used to look up matches.

Returns

sequence of dictionaries with the variables settings used to generate each filename

get_all_trees(short_name: str, glob_vars=(), set_parent=True) → Tuple[fsl.utils.filetree.filetree.FileTree][source]

Gets all the trees that generate the existing files matching the pattern

tree.get_all(short_name) == tuple(tree.get(short_name) for tree in tree.get_all_trees(short_name))

Parameters
  • short_name – short name of the path template

  • glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk. Any defined variables in glob_vars will be ignored. If glob_vars is set to ‘all’, all undefined variables will be used to look up matches.

  • set_parent – Update the variables of the top-level rather than current tree if True. Ony relevant if self is a sub-tree.

Returns

sequence of FileTrees used to generate each file on disk matching the pattern of short_name

update(set_parent=True, **variables) → fsl.utils.filetree.filetree.FileTree[source]

Creates a new FileTree with updated variables

Parameters
  • set_parent – Update the variables of the top-level rather than current tree if True. Ony relevant if self is a sub-tree.

  • variables – new values for the variables Setting a variable to None will cause the variable to be unset

Returns

New FileTree with same templates for directory names and filenames, but updated variables

extract_variables(short_name: str, filename: str) → Dict[str, str][source]

Extracts the variables from the given filename

Parameters
  • short_name – short name of the path template

  • filename – filename matching the template

Returns

variables needed to get to the given filename Variables with None value are optional variables in the template that were not used

save_pickle(filename)[source]

Saves the Filetree to a pickle file

Parameters

filename – filename to store the file tree (usually ending with .pck)

classmethod load_pickle(filename)[source]

Loads the Filetree from a pickle file

Parameters

filename – filename produced from Filetree.save

Returns

stored Filetree

defines(short_names, error=False)[source]

Checks whether templates are defined for all the short_names

Parameters
  • short_names – sequence of expected short names to exist in the tree

  • error – if True raises ValueError if any short_names are undefined

Returns

True if all are defined, False otherwise

Raise

ValueError if error is set to True and any template is missing

on_disk(short_names, error=False, glob_vars=())[source]

Checks whether at least one file exists for every file in short_names

Parameters
  • short_names – list of expected short names to exist in the tree

  • error – if True raises a helpful error when the check fails

  • glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk If glob_vars contains any defined variables, it will be ignored.

Returns

True if short names exist and optionally exist on disk (False otherwise)

Raise
  • ValueError if error is set and the tree is incomplete

  • IOError if error is set and any files are missing from the disk

classmethod read(tree_name: str, directory='.', **variables) → fsl.utils.filetree.filetree.FileTree[source]

Reads a FileTree from a specific file

The return type is cls unless the tree_name has been previously registered. The return type of any sub-tree is FileTree unless the tree_name has been previously registered.

Parameters
  • tree_name – file containing the filename tree. Can provide the filename of a tree file or the name for a tree in the filetree.tree_directories.

  • directory – parent directory of the full tree (defaults to current directory)

  • variables – variable settings

Returns

dictionary from specifier to filename

__dict__ = mappingproxy({'__module__': 'fsl.utils.filetree.filetree', '__doc__': '\n Contains the input/output filename tree\n\n Properties:\n\n - ``templates``: dictionary mapping short names to filename templates\n - ``variables``: dictionary mapping variables in the templates to specific values (variables set to None are explicitly unset)\n - ``sub_trees``: filename trees describing specific sub-directories\n - ``parent``: parent FileTree, of which this sub-tree is a sub-directory\n - ``name``: descriptive name of the tree\n ', '__init__': <function FileTree.__init__>, 'parent': <property object>, 'name': <property object>, 'all_variables': <property object>, 'get_variable': <function FileTree.get_variable>, '_get_template_tree': <function FileTree._get_template_tree>, 'get_template': <function FileTree.get_template>, 'template_variables': <function FileTree.template_variables>, 'get': <function FileTree.get>, 'get_all': <function FileTree.get_all>, 'get_all_vars': <function FileTree.get_all_vars>, 'get_all_trees': <function FileTree.get_all_trees>, 'update': <function FileTree.update>, 'extract_variables': <function FileTree.extract_variables>, 'save_pickle': <function FileTree.save_pickle>, 'load_pickle': <classmethod object>, 'defines': <function FileTree.defines>, 'on_disk': <function FileTree.on_disk>, 'read': <classmethod object>, '__dict__': <attribute '__dict__' of 'FileTree' objects>, '__weakref__': <attribute '__weakref__' of 'FileTree' objects>})
__module__ = 'fsl.utils.filetree.filetree'
__weakref__

list of weak references to the object (if defined)

fsl.utils.filetree.filetree.register_tree(name: str, tree_subtype: type)[source]

Registers a tree_subtype under name

Loading a tree with given name will lead to the tree_subtype rather than FileTree to be returned

Parameters
  • name – name of tree filename

  • tree_subtype – tree subtype

fsl.utils.filetree.filetree.get_registered(name, default=<class 'fsl.utils.filetree.filetree.FileTree'>) → type[source]

Get the previously registered subtype for name

Parameters
  • name – name of the sub-tree

  • default – type to return if the name has not been registered

Returns

FileTree or sub-type thereof