fsl.utils.path

This module contains a few utility functions for working with file system paths.

deepest

Finds the deepest directory which ends with one of the given sequence of suffixes, or returns None if no directories end with any of the suffixes.

shallowest

Finds the shallowest directory which ends with one of the given sequence of suffixes, or returns None if no directories end with any of the suffixes.

allFiles

Return a list containing all files which exist underneath the specified root directory.

hasExt

Convenience function which returns True if the given path ends with any of the given allowedExts, False otherwise.

addExt

Adds a file extension to the given file prefix.

removeExt

Returns the base name of the given file name.

getExt

Returns the extension of the given file name.

splitExt

Returns the base name and the extension from the given file name.

getFileGroup

If the given path is part of a fileGroup, returns a list containing the paths to all other files in the group (including the path itself).

removeDuplicates

Reduces the list of paths down to those which are unique with respect to the specified fileGroups.

uniquePrefix

Return the longest prefix for the given file name which unambiguously identifies it, relative to the other files in the same directory.

commonBase

Identifies the deepest common base directory shared by all files in paths.

exception fsl.utils.path.PathError

Bases: Exception

Exception class raised by the functions defined in this module when something goes wrong.

fsl.utils.path.deepest(path, suffixes)

Finds the deepest directory which ends with one of the given sequence of suffixes, or returns None if no directories end with any of the suffixes.

fsl.utils.path.shallowest(path, suffixes)

Finds the shallowest directory which ends with one of the given sequence of suffixes, or returns None if no directories end with any of the suffixes.

fsl.utils.path.allFiles(root)

Return a list containing all files which exist underneath the specified root directory.

fsl.utils.path.hasExt(path, allowedExts)

Convenience function which returns True if the given path ends with any of the given allowedExts, False otherwise.

fsl.utils.path.addExt(prefix, allowedExts=None, mustExist=True, defaultExt=None, fileGroups=None, unambiguous=True)

Adds a file extension to the given file prefix.

If mustExist is False, and the file does not already have a supported extension, the default extension is appended and the new file name returned. If the prefix already has a supported extension, it is returned unchanged.

If mustExist is True (the default), the function checks to see if any files exist that have the given prefix, and a supported file extension. A PathError is raised if:

  • No files exist with the given prefix and a supported extension.

  • fileGroups is None and unambiguous is True, and more than one file exists with the given prefix, and a supported extension.

Otherwise the full file name is returned.

Parameters
  • prefix – The file name prefix to modify.

  • allowedExts – List of allowed file extensions.

  • mustExist – Whether the file must exist or not.

  • defaultExt – Default file extension to use.

  • fileGroups – Recognised file groups - see getFileGroup().

  • unambiguous – If True (the default), and more than one file exists with the specified prefix, a PathError is raised. Otherwise, a list containing all matching files is returned.

fsl.utils.path.removeExt(filename, allowedExts=None)

Returns the base name of the given file name. See splitExt().

fsl.utils.path.getExt(filename, allowedExts=None)

Returns the extension of the given file name. See splitExt().

fsl.utils.path.splitExt(filename, allowedExts=None)

Returns the base name and the extension from the given file name.

If allowedExts is None, this function is equivalent to using:

os.path.splitext(filename)

If allowedExts is provided, but the file does not end with an allowed extension, a tuple containing (filename, '') is returned.

Parameters
  • filename – The file name to split.

  • allowedExts – Allowed/recognised file extensions.

fsl.utils.path.getFileGroup(path, allowedExts=None, fileGroups=None, fullPaths=True, unambiguous=False)

If the given path is part of a fileGroup, returns a list containing the paths to all other files in the group (including the path itself).

If the path does not appear to be part of a file group, or appears to be part of an incomplete file group, a list containing only the path is returned.

If the path does not exist, or appears to be part of more than one file group, a PathError is raised.

File groups can be used to specify a collection of file suffixes which should always exist alongside each other. This can be used to resolve ambiguity when multiple files exist with the same prefix and supported extensions (e.g. file.hdr and file.img). The file groups are specified as a list of sequences, for example:

[('.img',    '.hdr'),
 ('.img.gz', '.hdr.gz')]

If you specify fileGroups=[('.img', '.hdr')] and prefix='file', and both file.img and file.hdr exist, the addExt() function would return file.img (i.e. the file which matches the first extension in the group).

Similarly, if you call the imcp.imcp() or imcp.immv() functions with the above parameters, both file.img and file.hdr will be moved.

Note

The primary use-case of file groups is to resolve ambiguity with respect to NIFTI and ANALYSE75 image pairs. By specifying fileGroups=[('.img', '.hdr'), ('.img.gz', '.hdr.gz')], the addExt(), imcp.immv() and imcp.imcp() functions are able to figure out what you mean when you specify file, and both file.hdr and file.img (or file.hdr.gz and file.img.gz) exist.

Parameters
  • path – Path to the file. Must contain the file extension.

  • allowedExts – Allowed/recognised file extensions.

  • fileGroups – Recognised file groups.

  • fullPaths – If True (the default), full file paths (relative to the path) are returned. Otherwise, only the file extensions in the group are returned.

  • unambiguous – Defaults to False. If True, and the path is not unambiguously part of one group, or part of no groups, a PathError is raised. Otherwise, the path is returned.

fsl.utils.path.removeDuplicates(paths, allowedExts=None, fileGroups=None)

Reduces the list of paths down to those which are unique with respect to the specified fileGroups.

For example, if you have a directory containing:

001.hdr
001.img
002.hdr
002.img
003.hdr
003.img

And you call removeDuplicates like so:

paths       = ['001.img', '001.hdr',
               '002.img', '002.hdr',
               '003.img', '003.hdr']

allowedExts = ['.img',  '.hdr']
fileGroups  = [('.img', '.hdr')]

removeDuplicates(paths, allowedExts, fileGroups)

The returned list will be:

['001.img', '002.img', '003.img']

If you provide allowedExts, you may specify incomplete paths (i.e. without extensions), as long as there are no path ambiguities.

A PathError will be raised if any of the paths do not exist, or if there are any ambiguities with respect to incomplete paths.

Parameters
  • paths – List of paths to reduce.

  • allowedExts – Allowed/recognised file extensions.

  • fileGroups – Recognised file groups - see getFileGroup().

fsl.utils.path.uniquePrefix(path)

Return the longest prefix for the given file name which unambiguously identifies it, relative to the other files in the same directory.

Raises a PathError if a unique prefix could not be found (which will never happen if the path is valid).

fsl.utils.path.commonBase(paths)

Identifies the deepest common base directory shared by all files in paths.

Raises a PathError if the paths have no common base. This will never happen for absolute paths (as the base will be e.g. '/').