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)

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)

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)

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)

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='_')

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)

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)

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)

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)

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)

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)

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)

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

Return a timestamp string suitable for using in filenames.

Returns:

Represents the current time.

Return type:

str

make_path(root_path, sub_path, filename)

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)

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.