io_util

Utilities for generating and handling file names.

Functions

check_filename(test_file[, name_prefix, ...])

Return True if correct extension, suffix, and prefix.

clean_filename(filename)

Replace invalid characters with under-bars.

extract_suffix_path(path, prefix_path)

Return the suffix of path after prefix path has been removed.

get_allowed(value[, allowed_values, starts_with])

Return the portion of the value that matches a value in allowed_values or None if no match.

get_alphanumeric_path(pathname[, replace_char])

Replace sequences of non-alphanumeric characters in string (usually a path) with specified character.

get_dir_dictionary(dir_path[, name_prefix, ...])

Create dictionary directory paths keys.

get_file_list(root_path[, name_prefix, ...])

Return paths satisfying various conditions.

get_filtered_by_element(file_list, elements)

Filter a file list by whether the base names have a substring matching any of the members of elements.

get_filtered_list(file_list[, name_prefix, ...])

Get list of filenames satisfying the criteria.

get_path_components(root_path, this_path)

Get a list of the remaining components after root path.

get_task_dict(files)

Return a dictionary of the tasks that appear in the file names of a list of files.

get_task_from_file(file_path)

Returns the task name entity from a BIDS-type file path.

get_timestamp()

Return a timestamp string suitable for using in filenames.

make_path(root_path, sub_path, filename)

Get path for a file, verifying all components exist.

parse_bids_filename(file_path)

Split a filename into BIDS-relevant components.

check_filename(test_file, name_prefix=None, name_suffix=None, extensions=None)[source]

Return True if correct extension, suffix, and prefix.

Parameters:
  • test_file (str) – Path of filename to test.

  • name_prefix (list, str, None) – An optional name_prefix or list of prefixes to accept for the base filename.

  • name_suffix (list, str, None) – An optional name_suffix or list of suffixes to accept for the base file name.

  • extensions (list, str, None) – An optional extension or list of extensions to accept for the extensions.

Returns:

True if file has the appropriate format.

Return type:

bool

Notes

  • Everything is converted to lower case prior to testing so this test should be case-insensitive.

  • None indicates that all are accepted.

clean_filename(filename)[source]

Replace invalid characters with under-bars.

Parameters:

filename (str) – source filename.

Returns:

The filename with anything but alphanumeric, period, hyphens, and under-bars removed.

Return type:

str

extract_suffix_path(path, prefix_path)[source]

Return the suffix of path after prefix path has been removed.

Parameters:
  • path (str) –

  • prefix_path (str) –

Returns:

Suffix path.

Return type:

str

Notes

  • This function is useful for creating files within BIDS datasets.

get_allowed(value, allowed_values=None, starts_with=True)[source]

Return the portion of the value that matches a value in allowed_values or None if no match.

Parameters:
  • value (str) – value to be matched.

  • allowed_values (list, str, or None) – Values to match.

  • starts_with (bool) – If True match is done at beginning of string, otherwise the end.

Returns:

portion of value that matches the various allowed_values.

Return type:

str or list

Notes

  • match is done in lower case.

get_alphanumeric_path(pathname, replace_char='_')[source]

Replace sequences of non-alphanumeric characters in string (usually a path) with specified character.

Parameters:
  • pathname (str) – A string usually representing a pathname, but could be any string.

  • replace_char (str) – Replacement character(s).

Returns:

New string with characters replaced.

Return type:

str

get_dir_dictionary(dir_path, name_prefix=None, name_suffix=None, extensions=None, skip_empty=True, exclude_dirs=None)[source]

Create dictionary directory paths keys.

Parameters:
  • dir_path (str) – Full path of the directory tree to be traversed (no ending slash).

  • name_prefix (str, None) – An optional name_prefix for the base filename.

  • name_suffix (str, None) – An optional name_suffix for the base file name.

  • extensions (list, None) – An optional list of file extensions.

  • skip_empty (bool) – Do not put entry for directories that have no files.

  • exclude_dirs (list) – List of directories to skip.

Returns:

Dictionary with directories as keys and file lists values.

Return type:

dict

get_file_list(root_path, name_prefix=None, name_suffix=None, extensions=None, exclude_dirs=None)[source]

Return paths satisfying various conditions.

Parameters:
  • root_path (str) – Full path of the directory tree to be traversed (no ending slash).

  • name_prefix (str, None) – An optional name_prefix for the base filename.

  • name_suffix (str, None) – The name_suffix of the paths to be extracted.

  • extensions (list, None) – A list of extensions to be selected.

  • exclude_dirs (list, None) – A list of paths to be excluded.

Returns:

The full paths.

Return type:

list

Notes: Exclude directories are paths relative to the root path.

get_filtered_by_element(file_list, elements)[source]

Filter a file list by whether the base names have a substring matching any of the members of elements.

Parameters:
  • file_list (list) – List of file paths to be filtered.

  • elements (list) – List of strings to use as filename filters.

Returns:

The list only containing file paths whose filenames match a filter.

Return type:

list

get_filtered_list(file_list, name_prefix=None, name_suffix=None, extensions=None)[source]

Get list of filenames satisfying the criteria.

Everything is converted to lower case prior to testing so this test should be case-insensitive.

Parameters:
  • file_list (list) – List of files to test.

  • name_prefix (str) – Optional name_prefix for the base filename.

  • name_suffix (str) – Optional name_suffix for the base filename.

  • extensions – Optional list of file extensions (allows two periods (.tsv.gz)).

get_path_components(root_path, this_path)[source]

Get a list of the remaining components after root path.

Parameters:
  • root_path (str) – A path (no trailing separator).

  • this_path (str) – The path of a file or directory descendant of root_path.

Returns:

A list with the remaining elements directory components to the file.

Return type:

list or None

Notes: this_path must be a descendant of root_path.

get_task_dict(files)[source]

Return a dictionary of the tasks that appear in the file names of a list of files.

Parameters:

files (list) – List of filenames to be separated by task.

Returns:

dictionary of filenames keyed by task name.

Return type:

dict

get_task_from_file(file_path)[source]

Returns the task name entity from a BIDS-type file path.

Parameters:

file_path (str) – File path.

Returns:

The task name or an empty string.

Return type:

str

get_timestamp()[source]

Return a timestamp string suitable for using in filenames.

Returns:

Represents the current time.

Return type:

str

make_path(root_path, sub_path, filename)[source]

Get path for a file, verifying all components exist.

Parameters:
  • root_path (str) – path of the root directory.

  • sub_path (str) – sub-path relative to the root directory.

  • filename (str) – filename of the file.

Returns:

A valid realpath for the specified file.

Return type:

str

Notes: This function is useful for creating files within BIDS datasets.

parse_bids_filename(file_path)[source]

Split a filename into BIDS-relevant components.

Parameters:

file_path (str) – Path to be parsed.

Returns:

BIDS suffix name. str: File extension (including the .). dict: Dictionary with key-value pair being (entity type, entity value).

Return type:

str

Raises:

HedFileError

  • If filename does not conform to name-value_suffix format.

Notes

  • splits into BIDS suffix, extension, and a dictionary of entity name-value pairs.