fsl.utils.filetree.filetree

exception fsl.utils.filetree.filetree.MissingVariable

Bases: KeyError

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

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

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

property parent

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

property all_variables

All tree variables including those inherited from the parent tree

get_variable(name: str, default=None) → str

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(short_name: str) → Tuple[str, Dict[str, str]]

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]

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

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]

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]]

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]

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

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]

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)

Saves the Filetree to a pickle file

Parameters

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

classmethod load_pickle(filename)

Loads the Filetree from a pickle file

Parameters

filename – filename produced from Filetree.save

Returns

stored Filetree

defines(short_names, error=False)

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=())

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

exists(short_names, on_disk=False, error=False, glob_vars=())

Deprecated in favor of on_disk() and defines().

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

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

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

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

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