Enhanced documentation with comprehensive examples for ASL reconstruction classes and utilities

[Copilot]

This PR significantly improves the asltk documentation by adding comprehensive examples and detailed docstrings for all reconstruction classes and utility methods, addressing the need for deeper documentation about asltk usage.

Key Improvements

Enhanced Utils Module Documentation

• load_image(): Added examples for different file formats, BIDS loading, and practical use cases
• save_image(): Added examples for direct file saving, BIDS structure saving, and processed ASL results
• collect_data_volumes(): Added comprehensive examples for 4D/5D data separation and volume processing
• All docstring examples: Tested and verified to work with actual test data

Enhanced Reconstruction Classes Documentation

CBFMapping Class

• Constructor: Added detailed workflow examples and MRI parameter explanations
• create_map(): Added comprehensive parameter explanations, typical value ranges, and result interpretation
• set_brain_mask() & get_brain_mask(): Added practical masking examples and performance optimization tips

MultiTE_ASLMapping Class

• Constructor: Added multi-echo ASL workflow examples and field strength considerations
• create_map(): Added T1 relaxometry examples, clinical interpretation, and processing guidance

MultiDW_ASLMapping Class

• Constructor: Added diffusion-weighted ASL analysis explanations and compartment modeling
• create_map(): Added compartment analysis examples and processing time considerations
• set_brain_mask(): Added performance optimization guidance for computationally intensive processing

New Documentation Files

• docs/examples/workflow_examples.md: Comprehensive end-to-end workflows with complete pipelines
• docs/usage_examples.md: Quick start guide with essential examples and best practices

Example of Enhanced Documentation

Before:

def create_map(self, ub=[1.0, 5000.0], lb=[0.0, 0.0], par0=[1e-5, 1000], cores=cpu_count()):
    """Create the CBF and also ATT maps"""

After:

def create_map(self, ub=[1.0, 5000.0], lb=[0.0, 0.0], par0=[1e-5, 1000], cores=cpu_count()):
    """Create CBF and ATT maps using the Buxton ASL model.
    
    Examples:
        Basic CBF mapping with default parameters:
        >>> asl_data = ASLData(pcasl='./tests/files/pcasl_mte.nii.gz', ...)
        >>> cbf_mapper = CBFMapping(asl_data)
        >>> results = cbf_mapper.create_map()
        >>> cbf_map = results['cbf_norm']  # CBF in mL/100g/min
        
        Interpreting the results:
        >>> # Typical CBF values in healthy brain:
        >>> # Grey matter: ~50-80 mL/100g/min
        >>> # White matter: ~20-30 mL/100g/min
    """

Testing and Validation

• ✅ All 214 existing tests continue to pass
• ✅ All new docstring examples tested with real data files
• ✅ Documentation examples use correct data shapes and parameters
• ✅ Cross-references between methods work correctly

Benefits for Users

• Practical Examples: Real-world usage patterns with actual test data
• Parameter Guidance: Typical value ranges and field strength considerations
• Performance Tips: Brain masking, parallel processing, and optimization strategies
• Result Interpretation: Expected value ranges and quality assessment guidance
• Complete Workflows: End-to-end analysis pipelines comparing different methods

This enhancement makes asltk significantly more accessible to new users while providing advanced guidance for experienced researchers.

Fixes #4.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[acsenrafilho]

Great job! Make a few improvements with the commentaries

[acsenrafilho]

Great job!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
asltk/reconstruction/cbf_mapping.py	100.00% <ø> (ø)
asltk/reconstruction/multi_dw_mapping.py	94.38% <ø> (ø)
asltk/reconstruction/multi_te_mapping.py	100.00% <ø> (ø)
asltk/utils.py	94.18% <ø> (+13.95%)	⬆️

🚀 New features to boost your workflow:

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