Add optional smoothing filter support to reconstruction module

[Copilot]

This PR adds optional spatial filtering (smoothing) functionality to the reconstruction module's create_map methods, allowing users to reduce noise and improve SNR in output maps as part of the standard processing pipeline.

Overview

In most ASL data processing workflows, it is common practice to apply spatial filtering to output maps to reduce noise, enhance signal-to-noise ratio (SNR), and improve interpretability. This feature addresses that need by adding smoothing capabilities directly to the reconstruction classes.

Key Features

• Backward compatible: Default behavior unchanged (no smoothing applied unless explicitly enabled)
• Optional parameters: smoothing=None, smoothing_params=None added to all create_map methods
• Multiple filter types: Support for Gaussian and median filtering
• Smart defaults: Gaussian uses sigma=1.0, median uses size=3
• All maps smoothed: Applied consistently to CBF, ATT, T1blGM, and diffusion maps
• Comprehensive coverage: Works with CBFMapping, MultiTE_ASLMapping, and MultiDW_ASLMapping

Usage Examples

from asltk.reconstruction import CBFMapping
from asltk.asldata import ASLData

# Load your ASL data
asl_data = ASLData(pcasl="data.nii.gz", m0="m0.nii.gz", ...)
mapper = CBFMapping(asl_data)

# No smoothing (default behavior - unchanged)
results = mapper.create_map()

# Gaussian smoothing with default parameters
results = mapper.create_map(smoothing='gaussian')

# Custom Gaussian smoothing
results = mapper.create_map(
    smoothing='gaussian', 
    smoothing_params={'sigma': 1.5}
)

# Median filtering for edge-preserving smoothing
results = mapper.create_map(
    smoothing='median',
    smoothing_params={'size': 5}
)

Implementation Details

New Components

• asltk/smooth/median.py: New median filter implementation using scipy.ndimage
• asltk/reconstruction/smooth_utils.py: Utility functions for consistent smoothing application
• Enhanced create_map methods: All reconstruction classes now support smoothing parameters

Modified Classes

• CBFMapping.create_map(): Returns {'cbf', 'cbf_norm', 'att'} with optional smoothing
• MultiTE_ASLMapping.create_map(): Returns {'cbf', 'cbf_norm', 'att', 't1blgm'} with optional smoothing
• MultiDW_ASLMapping.create_map(): Returns all diffusion maps with optional smoothing

Error Handling

# Invalid smoothing type raises clear error
results = mapper.create_map(smoothing='invalid')
# ValueError: Unsupported smoothing type: invalid. Supported types are: None, 'gaussian', 'median'

Testing

• ✅ 37 new tests covering smoothing functionality
• ✅ All existing tests pass unchanged (backward compatibility verified)
• ✅ Integration tests for all reconstruction classes
• ✅ Parameter validation and error handling tests
• ✅ Utility function tests

Benefits

1. Improved workflow: Users can apply smoothing directly in reconstruction pipeline
2. Noise reduction: Both Gaussian and median filters available for different use cases
3. Flexibility: Custom parameters supported for advanced users
4. Consistency: Same smoothing applied to all output maps
5. Zero breaking changes: Existing code continues to work exactly as before

Fixes #15.

---

💬 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 95.00000% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
asltk/reconstruction/smooth_utils.py	89.28%	3 Missing ⚠️

Files with missing lines	Coverage Δ
asltk/reconstruction/cbf_mapping.py	100.00% <100.00%> (ø)
asltk/reconstruction/multi_dw_mapping.py	94.50% <100.00%> (+0.12%)	⬆️
asltk/reconstruction/multi_te_mapping.py	100.00% <100.00%> (ø)
asltk/smooth/__init__.py	100.00% <100.00%> (ø)
asltk/smooth/median.py	100.00% <100.00%> (ø)
asltk/reconstruction/smooth_utils.py	89.28% <89.28%> (ø)

🚀 New features to boost your workflow:

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