utils module

General utilities for data handling, file I/O, and parallel execution.

I/O

DICOM

Parallel processing

Logging and progress

Centralized logging utility module for HABIT project.

This module provides a unified logging system with the following features: - Hierarchical logger management - Single log file per run (no duplicate logs folders) - Console and file output with different formats - Thread-safe logger initialization - Multiprocess-safe logging via QueueHandler + QueueListener (Option C) - Clear separation between main logs and module logs

Design principles: 1. One log file per application/script run 2. All logs stored in {output_dir}/processing.log (no logs/ subfolder) 3. Hierarchical logger names (habit.preprocessing, habit.habitat, etc.) 4. Console output: simple format for readability 5. File output: detailed format with file location and line numbers 6. Child processes enqueue records; the main process QueueListener writes in order

class habit.utils.log_utils.LoggerManager

Bases: object

Centralized logger manager for the HABIT project.

This class ensures consistent logging across all modules with: - Single point of configuration - No duplicate handlers - Hierarchical logger structure - Multiprocess queue routing when file logging is enabled in the main process

static __new__(cls)

Singleton pattern to ensure only one LoggerManager instance.

__init__()

Initialize the LoggerManager.

setup_root_logger(log_file: Path | None = None, level: int = 20, console_level: int | None = None, append_mode: bool = False) → Logger

Setup the root logger for HABIT project.

This should be called once at the start of each application/script. All subsequent module loggers will inherit from this configuration.

When append_mode is False and log_file is set, the main process routes all habit logs through a multiprocessing queue so child processes and the main process share one ordered writer.

Parameters:

• log_file – Path to the log file. If None, only console logging is enabled.

• level – Logging level for file output (default: INFO)

• console_level – Logging level for console output. If None, uses same as level.

• append_mode – Legacy child-process direct append when no queue is available.

Returns:

The root logger for HABIT project

Return type:

logging.Logger

stop_queue_listener() → None

Stop the multiprocessing log listener and flush pending records.

Safe to call when queue logging was never started or already stopped.

get_logger(name: str) → Logger

Get a logger with the specified name under the HABIT hierarchy.

Parameters:

name – Logger name (will be prefixed with ‘habit.’ if not already)

Returns:

Logger instance

Return type:

logging.Logger

get_log_file() → Path | None

Get the current log file path.

Returns:

Path to log file, or None if file logging not enabled

Return type:

Optional[Path]

get_log_queue() → Any

Return the multiprocessing log queue for child processes.

Returns:

Queue when file logging uses queue mode; otherwise None.

Return type:

Optional[multiprocessing.Queue]

habit.utils.log_utils.setup_logger(name: str, output_dir: Path | None = None, log_filename: str = 'processing.log', level: int = 20, console_level: int | None = None) → Logger

Setup a logger for a HABIT module or script.

This is the main entry point for setting up logging in HABIT applications.

Parameters:

• name – Name of the module/script (e.g., ‘preprocessing’, ‘habitat’)

• output_dir – Directory where log file will be created. If None, only console logging.

• log_filename – Name of the log file (default: ‘processing.log’)

• level – Logging level for file output (default: INFO)

• console_level – Logging level for console. If None, uses same as level.

Returns:

Configured logger instance

Return type:

logging.Logger

habit.utils.log_utils.get_module_logger(module_name: str) → Logger

Get a logger for a module.

Parameters:

module_name – The __name__ of the module

Returns:

Logger instance for the module

Return type:

logging.Logger

habit.utils.log_utils.disable_external_loggers() → None

Disable verbose logging from external libraries.

habit.utils.log_utils.resolve_radiomics_logging_level(debug: bool = False) → int

Resolve PyRadiomics logger level for feature extraction.

When debug is True, PyRadiomics emits DEBUG messages such as Calculating voxel batch no. X/Y during voxel-based extraction.

Parameters:

debug – Whether habitat debug mode is enabled.

Returns:

logging.DEBUG when debug is True, otherwise logging.INFO.

Return type:

int

habit.utils.log_utils.radiomics_feature_class_logging(level: int = 20) → Iterator[None]

Temporarily raise the PyRadiomics logger level during voxel feature extraction.

Pass resolve_radiomics_logging_level() when wiring habitat debug so batch progress lines (DEBUG) are visible in habitat_analysis.log.

Parameters:

level – Logging level to apply to the radiomics logger (default: INFO).

Yields:

None

habit.utils.log_utils.restore_logging_in_subprocess(log_file_path: Path | None = None, log_level: int = 20, log_queue: Any | None = None) → None

Restore logging configuration in a child process.

Prefer log_queue from the parent process so records are written in order by the main-process QueueListener. When no queue is available, fall back to direct append-mode file logging (legacy path).

Parameters:

• log_file_path – Path to the log file (legacy fallback)

• log_level – Logging level for the child root logger

• log_queue – Multiprocessing queue shared with the main process

habit.utils.log_utils.shutdown_subprocess_logging() → None

Flush and close logging handlers in a child process before exit.

Ensures queued records reach the main-process listener before the worker exits.

habit.utils.log_utils.stop_queue_listener() → None

Stop the main-process queue listener and flush pending log records.

habit.utils.log_utils.setup_output_logger(output_dir: Path, name: str, level: int = 20) → Logger

Legacy function for backward compatibility.

Parameters:

• output_dir – Directory where log file will be created

• name – Name of the logger

• level – Logging level

Returns:

Configured logger instance

Return type:

logging.Logger

Visualization

Math and metrics