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)	Replaces 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_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_from_file(file_path)
get_timestamp()
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)

Replaces 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.

Notes

• match is done in lower case.

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

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

get_timestamp()

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.