Add comprehensive logging system to ASLTK library

[Copilot]

This PR implements a comprehensive logging system for the ASLTK library to provide detailed runtime information, improve debugging capabilities, and facilitate integration with larger applications and pipelines.

Features Added

Core Logging Infrastructure

• Centralized logging configuration in asltk/logging_config.py with flexible setup options
• Multiple log levels (DEBUG, INFO, WARNING, ERROR) with configurable verbosity
• Flexible output options - console, file, or both with custom formatting
• Script-friendly configuration functions for easy CLI integration

Integration Coverage

• Data loading and validation - ASLData creation, image loading, parameter validation
• Registration workflows - Head movement correction with progress tracking and error handling
• Reconstruction pipelines - CBF mapping with performance statistics and completion metrics
• Command-line scripts - TE ASL and DW ASL processing with verbose mode support
• Error handling - Structured error messages with contextual information

Developer Experience

• Helper functions for common logging patterns (log_processing_step, log_data_info, etc.)
• Modular design - different modules can have separate loggers for granular control
• Backward compatibility - existing verbose flags and print statements continue to work
• Comprehensive test suite - 14 tests validating all logging functionality

Usage Examples

Basic Setup

from asltk import setup_logging, get_logger

# Enable logging with INFO level
setup_logging(level='INFO', console_output=True, file_output='processing.log')

# Use in ASL processing
from asltk.asldata import ASLData
asl_data = ASLData(pcasl='data.nii.gz', m0='m0.nii.gz')
# Automatically logs: data loading, validation, dimensions

Script Integration

from asltk import configure_for_scripts

# Configure based on verbose flag
configure_for_scripts(verbose=args.verbose, log_file='processing.log')

Processing Workflows

from asltk.reconstruction import CBFMapping

cbf_mapper = CBFMapping(asl_data)
results = cbf_mapper.create_map(cores=4)
# Logs: initialization, processing progress, completion statistics

Benefits

• Transparency - Detailed runtime information for users monitoring ASL processing
• Debugging - Structured error messages and execution tracing for troubleshooting
• Integration - Easy embedding in larger applications with configurable logging
• Performance monitoring - Timing and statistics for optimization
• Maintainability - Easier identification and isolation of issues during development

Documentation

Added comprehensive documentation in docs/logging.md with:

• Configuration options and examples
• Integration patterns for different use cases
• Best practices for logging in ASL workflows
• Complete example scripts demonstrating all features

The implementation follows Python logging best practices and provides a solid foundation for monitoring and debugging ASL data processing workflows while maintaining full backward compatibility.

Fixes #33.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[codecov]

Codecov Report

❌ Patch coverage is 99.27536% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
asltk/logging_config.py	98.50%	1 Missing ⚠️

Files with missing lines	Coverage Δ
asltk/__init__.py	100.00% <100.00%> (ø)
asltk/asldata.py	94.25% <100.00%> (+1.94%)	⬆️
asltk/reconstruction/cbf_mapping.py	100.00% <100.00%> (ø)
asltk/registration/__init__.py	100.00% <100.00%> (ø)
asltk/logging_config.py	98.50% <98.50%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.