195 add IO module

[darksim33]

Introduce helper functions for saving NIfTI files and improve NNLS results processing with cutoff handling and peak merging. Refactor tests for better coverage and documentation updates. Fix various issues related to GPU fitting and peak handling.

[darksim33]

Summary

This PR refactors the NIfTI saving mechanism to use a centralized approach and adds comprehensive test coverage for NNLS results, particularly focusing on cutoff handling and the new preparation methods.

Changes

1. Centralized NIfTI Saving (results.py, ivim.py, nnls.py)

Refactored saving architecture:

• Introduced preparation methods that separate file path/image preparation from actual saving
• _prepare_non_separate_nii(): Prepares combined 4D files (e.g., _d.nii.gz with all D values)
• _prepare_separate_nii(): Prepares indexed 3D files (e.g., _d_0.nii.gz, _d_1.nii.gz)
• Both methods return tuple[list[Path], list[RadImgArray]]
• save_to_nii() now calls preparation methods then uses centralized nifti.arrays_to_nifti()

Benefits:

• Single point of control for NIfTI file writing
• Consistent file naming across all result types
• Easier to extend functionality in subclasses
• Better separation of concerns (prepare vs. save)

IVIM-specific enhancements:

• Override preparation methods to add T1 parameter when fitted
• T1 saved as {basename}_t1.nii.gz
• Works in both separate and non-separate modes

NNLS-specific enhancements:

• Override _prepare_non_separate_nii() to handle cutoff requirements
• Automatically apply cutoffs if passed via kwargs
• Log warning if cutoffs not applied (NNLS needs normalized compartment counts)
• Prevents inconsistent NIfTI files with varying dimensions

2. Enhanced NNLS Test Coverage (test_nnls_results.py)

New test classes and coverage:

TestNNLSCutoffs (7 tests)

• Basic cutoff application and validation
• Fraction preservation with controlled spectra
• Edge cases: no peaks in range, multiple peaks in range
• Overlapping cutoff ranges
• Cutoff attribute storage

TestNNLSNIfTIPreparation (4 tests)

• Preparation methods with applied cutoffs
• Warning when cutoffs not applied (loguru logger compatible)
• Cutoff application via kwargs
• Prevention of cutoff reapplication

TestNNLSNIfTISaving (3 tests)

• Full save_to_nii() workflow with cutoffs
• Separate files mode with cutoffs
• dtype preservation validation

TestNNLSSpectrum (4 tests)

• Spectrum storage after eval_results()
• Excel export with correct bins
• Custom bins functionality
• Spectrum shape validation

TestGeometricMeanPeak (3 tests)

• Basic geometric mean calculation
• Equal weights scenario
• Single peak edge case

TestNNLSIntegration (2 tests)

• Complete workflow: evaluate → cutoff → save
• Multi-format saving (NIfTI + Excel + spectrum)

TestNNLSEdgeCases (5 tests)

• Empty results handling
• Single peak detection
• Very narrow cutoff ranges
• Cutoffs extending beyond bin range

Test improvements:

• Uses controlled spectra with known peak positions
• Validates fraction preservation across transformations
• Ensures proper handling of NaN values in sparse ranges
• Tests both pixel-wise and segmentation-wise workflows

3. Documentation Updates (DataExport.md)

Comprehensive export documentation:

• Detailed NIfTI section with file naming conventions
• Examples for both combined and separate file modes
• NNLS cutoff usage examples and explanations
• IVIM T1 parameter documentation
• Excel export formats and use cases
• Spectrum and fitted curve export examples
• Format comparison table
• Best practices and troubleshooting guide

4. Bug Fixes

GPU fitting test fix (test_pygpufit.py):

• Fixed test_gpu_fitter_raises_on_invalid_model to properly mock the model property
• Used unittest.mock.patch with PropertyMock to mock read-only property

Breaking Changes

None. The API remains unchanged and is fully backwards compatible.

Testing

• ✅ All existing tests pass
• ✅ 28 new NNLS tests added
• ✅ Test coverage for preparation methods
• ✅ Edge case coverage significantly improved
• ✅ Integration tests validate complete workflows

Migration Guide

No migration needed - existing code continues to work as before.

Optional enhancement for NNLS users:

# New: Pass cutoffs directly during save
results.save_to_nii('output', img, dtype=float, cutoffs=[(0.0, 0.001), (0.001, 0.01)])

# Still works: Apply cutoffs separately
results.apply_cutoffs([(0.0, 0.001), (0.001, 0.01)])
results.save_to_nii('output', img, dtype=float)

Checklist

• Code follows project style guidelines
• Tests added for new functionality
• Documentation updated
• All tests passing
• Backwards compatible
• Commit messages follow conventional commits format