unravel.core.utils module

Utility functions and decorators for handling configurations, processing files and directories, and enhancing command-line scripts with progress bars and detailed function execution info.

Classes:

• CustomMofNCompleteColumn: Progress bar column for completed/total items.

• CustomTimeElapsedColumn: Progress bar column for elapsed time in green.

• CustomTimeRemainingColumn: Progress bar column for remaining time in dark orange.

• AverageTimePerIterationColumn: Progress bar column for average time per iteration.

Functions:

• load_config: Load settings from a config file.

• get_samples: Get a list of sample directories based on provided parameters.

• initialize_progress_bar: Initialize a Rich progress bar.

• verbose_start_msg: Print the start command and time if verbose mode is enabled.

• verbose_end_msg: Print the end time if verbose mode is enabled.

• log_command: Decorator to log the command and execution times to a hidden file.

• print_func_name_args_times: Decorator to print function execution details.

• load_text_from_file: Load text content from a file.

• copy_files: Copy specified files from source to target directory.

• process_files_with_glob: Process files matching a glob pattern using a processing function.

Usage:

Import the functions and decorators to enhance your scripts.

Examples

>>> # Import the functions and decorators
>>> from unravel.core.utils import load_config, get_samples, initialize_progress_bar, print_func_name_args_times, load_text_from_file, copy_files

>>> # Load the configuration from a file
>>> config = load_config("path/to/config.ini")

>>> # Get a list of sample directories
>>> samples = get_samples(["path/to/dir1", "path/to/dir2"], dir_pattern="sample??", verbose=True)

>>> # Initialize a progress bar
>>> progress, task_id = initialize_progress_bar(len(samples), task_message="[red]Processing samples...")

unravel.core.utils.load_config(config_path)

Load settings from the config file and return a Config object.

unravel.core.utils.get_samples(dir_list=None, dir_pattern='sample??', verbose=False)

Finds and returns paths to directories matching a specified pattern within given directories or, if none are provided, the current working directory.

Parameters:

• dir_list (list of Path or str, or Path or str, optional) – A list of paths (as Path objects or strings) to sample?? directories or directories that may contain subdirectories matching the dir_pattern.

• dir_pattern (str, optional) – A pattern to match directory names, default is “sample??”, where “?” is a wildcard matching a single character. This pattern is used to identify directories of interest.

• dir_pattern – A Unix shell-style wildcard pattern used by fnmatch to match directory names. Default is “sample??”, where each “?” matches a single character.

• verbose (bool, optional) – If True, prints the found directories, grouped by their parent directories. Default is False.

Returns:

samples – A list of resolved Path objects pointing to directories that match the dir_pattern.

Return type:

list of Path

Notes

• If no directories are provided via dir_list, the function searches the current working directory.

• If a directory (e.g., the current dir) matches the dir_pattern, it is included in the results and not searched for subdirectories.

Examples

>>> sample_paths = get_samples()  # Search the current working directory for sample?? directories
>>> sample_paths = get_samples([path1, path2], dir_pattern="sample???")  # Search path1 and path2 for sample??? directories

class unravel.core.utils.CustomMofNCompleteColumn(separator='/', table_column=None)

Bases: MofNCompleteColumn

Parameters:

• separator (str) –

• table_column (Column | None) –

render(task)

Show completed/total.

Return type:

Text

class unravel.core.utils.CustomTimeElapsedColumn(table_column=None)

Bases: TimeElapsedColumn

Parameters:

table_column (Column | None) –

render(task)

Show time elapsed.

Return type:

Text

class unravel.core.utils.CustomTimeRemainingColumn(compact=False, elapsed_when_finished=False, table_column=None)

Bases: TimeRemainingColumn

Parameters:

• compact (bool) –

• elapsed_when_finished (bool) –

• table_column (Column | None) –

render(task)

Show time remaining.

Return type:

Text

class unravel.core.utils.AverageTimePerIterationColumn(table_column=None)

Bases: ProgressColumn

Parameters:

table_column (Column | None) –

render(task)

Render the average time per iteration.

Parameters:

task – An object representing a task, which should have a speed attribute.

Returns:

A Text object displaying the average time per iteration.

Return type:

Text

unravel.core.utils.initialize_progress_bar(num_of_items_to_iterate, task_message='[red]Processing...')

unravel.core.utils.verbose_start_msg()

Print the start command and time if verbose mode is enabled.

unravel.core.utils.verbose_end_msg()

Print the end time if verbose mode is enabled.

unravel.core.utils.log_command(func)

A decorator for main() to log the command and execution times to a hidden file (.command_log.txt).

unravel.core.utils.get_dir_name_from_args(args, kwargs)

This function checks args and kwargs for a file or directory path and returns a string based on the name of the file or directory.

unravel.core.utils.print_func_name_args_times(print_dir=True)

A decorator that prints the function name, arguments, duration, and memory usage of the function it decorates.

unravel.core.utils.load_text_from_file(file_path)

unravel.core.utils.copy_files(source_dir, target_dir, filename, sample_path=None, verbose=False)

Copy the specified slices to the target directory.

Parameters:

• source_dir (-) – Path to the source directory containing the .tif files.

• target_dir (-) – Path to the target directory where the selected slices will be copied.

• filename (-) – Name of the file to copy.

• sample_path (-) – Path to the sample directory (provide to prepend to the filename).

• verbose (-) – Increase verbosity.

unravel.core.utils.process_files_with_glob(glob_pattern, processing_func, *args, **kwargs)

Process all files matching a glob pattern using the provided processing function.

Parameters:

glob_patternstr

The glob pattern to match files.

processing_funcfunction

The function to process each file. Should accept a file path as the first argument.

*args, **kwargs :

Additional arguments and keyword arguments to pass to the processing function.

unravel.core.utils.get_pad_percent(reg_outputs_path, pad_percent)