Develop (#57)

* WIP: Add download_brain_atlas function to download Cucaracha models from a given URL

* ENH: Add antspyx and kagglehub dependencies to pyproject.toml

* WIP: Add Brain Atlas data structure and methods for atlas management

* ENH: Create __init__.py for asltk.data package initialization

* WIP: Implement brain normalization function for image registration using ANTsPy

* Implement code changes to enhance functionality and improve performance

* ENH: Refactor BrainAtlas class to remove hardcoded atlas data and improve atlas URL retrieval method

* ENH: Add multiple brain atlas JSON files with metadata and descriptions

* ENH: Add multiple brain atlas JSON files with metadata and descriptions

* ENH: Add unit tests for BrainAtlas class to validate atlas listing and URL retrieval

* STY: Clean up whitespace and ensure consistent formatting in download_brain_atlas function

* ENH: Remove unused kaggle_tools.py file and associated download_brain_atlas function

* ENH: Update MNI2009.json to include dataset URL and detailed labels for brain regions

* ENH: Refactor BrainAtlas class to improve atlas loading and error handling, and add methods for T1-weighted and label data collection

* ENH: Refactor brain normalization function to space normalization, improve template image handling from BrainAtlas, and enhance registration process with console status updates

* ENH: Add comprehensive tests for rigid body registration and head movement correction, including error handling and space normalization validation

* ENH: Add data.brain_atlas reference to documentation and include it in the navigation

* ENH: Add initial test suite for registration module

* ENH: Implement space normalization function and head movement correction, refactor registration methods, and remove obsolete files

* ENH: Refactor registration tests to improve error handling and add comprehensive tests for rigid body and space normalization functions

* ENH: Add tests for head movement correction function, including success and error cases

* ENH: Add tests for error handling in setting atlas and retrieving URL and labels for known atlases

* ENH: Update Python version matrix in CI workflows to include 3.11, 3.12, and 3.13

* ENH: Improve docstring for head movement correction function to clarify parameters, exceptions, and return values

* ENH: Update code formatting check step in CI workflow to use 'lint_check' task

* ENH: Update CI workflow to use 'lint_check' task for code formatting checks and add 'lint_check' command to taskipy

* ENH: Add dataset DOI and citation DOIs to MNI2009 brain atlas JSON

* ENH: Update Python version matrix in CI workflows to include 3.11, 3.12, and 3.13

* ENH: Remove Python 3.13 from version matrix in CI workflows for develop and main branches

* ENH: Add workflow_dispatch trigger to CI for develop branch

* ENH: Add test for ParcellationReport class to validate report generation and saving

* ENH: Implement BasicReport and ParcellationReport classes for report generation

* ENH: Update Python version matrix in CI workflows to only include 3.9 for develop and main branches

* ENH: Add LGPHCC2022 brain atlas JSON file and remove obsolete LGPHCCxxxx file

* ENH: Add AICHA2021 brain atlas JSON file and remove obsolete AICHAxxxx file

* ENH: Add AAL32024 brain atlas JSON file and remove obsolete AAL2015 file

* ENH: Add additional metadata fields to brain atlas JSON files for CAPRSC, DKA, and HA

* ENH: Add JHA2005 brain atlas JSON file and remove obsolete JHAxxxx file

* ENH: Add FCA7N2011 brain atlas JSON file and remove obsolete FCA7Nxxxx file

* ENH: Update AAT2022 brain atlas JSON file with dataset URL, DOI, and detailed labels

* ENH: Update HOCSA2006 brain atlas JSON file with dataset URL, DOI, and detailed labels

* ENH: Update description in MA2012 brain atlas JSON file for clarity

* STY: fix linter

* WIP: Parcellation Report partial implementation

* ENH: Remove deprecated brain atlas JSON files and add updated versions for DKA2006, HA2003, and MA2012

* STY: Fix linter

* STY: Fix linter and isort

* BUG: Correct JSON formatting in HOCSA2006 brain atlas file

* ENH: Add unit tests for BrainAtlas class functionality

* WIP: ParcellationReport tests

* BUG: Update mask loading to handle numpy arrays in space_normalization function

* ENH: Implement ASL data registration with normalization and error handling

* WIP: Fix file path for saving regions DataFrame in ParcellationReport

* ENH: Add tests for asl_template_registration function to validate input types and error handling

* ENH: Implement progress bar for volume registration in asl_template_registration function

* ENH: Add tests for apply_transformation function to validate output and error handling

* WIP: Adjusting asl_template_registration method

* ENH: Add tests for ASLData class to validate copy behavior and length calculation

* ENH: Implement deep copy method for ASLData class and add length calculation for ASL data volumes

* STY: Remove outdated TODO comments related to atlas resources and compatibility checks

* DOC: Add Brain Parcellation Reports module and update navigation in mkdocs.yml

* ENH: Add apply_transformation function to apply a list of transformations to an image

* ENH: Remove console logging from space_normalization function to streamline registration process

* ENH: Refactor asl_template_registration to improve normalization process and update ASLData handling

* DOC: Update docstrings in BasicReport class for improved clarity and structure

* BUG: Fix linter

* ENH: Update lint task name to lint_check in CI workflows for consistency

* BUG: Improve docstring for copy method in ASLData class for clarity

* ENH: Update pre_test task to use lint_check for consistency in CI workflows

* WIP: Fixing asl_template_normalization to use M0 volume first

* BUG: Improve type checks in apply_transformation function for moving and reference images

* ENH: Refactor asl_template_registration to prioritize M0 image for normalization and improve atlas integration

* ENH: Implement tests for asl_template_registration to validate success and error cases

* ENH: Add tests for apply_transformation with BrainAtlas reference input handling

* BUG: Update error messages in apply_transformation tests for clarity on input requirements

* WIP: commenting asl_template_registration tests for a while

* STY: Refactor asl_template_registration for improved readability and structure

* BUG: Fix type checking for reference_image in apply_transformation function

* ENH: Add pytest-mock dependency for improved testing capabilities

* ENH: Add tests for BasicReport and ASLData, including error handling and warnings

* DOC: Update import path for load_image and save_image functions in getting_started.md

* STY: Refactor import paths for load_image and save_image functions; remove unused utils.py

* ENH: Implement load_image and save_image functions for BIDS directory handling; add ASL data serialization methods

* STY: Update import path for collect_data_volumes in gaussian.py

* STY: Add TODO comments for fixing T1 data loading and adjusting Kaggle datasets for 2mm resolution

* REF: Update import paths and replace ants.image_read with load_image for atlas image loading in asl_template_registration

* WIP: New modules to image orientation validation

* ENH: Add unit tests for rigid body registration and head movement correction

* STY: Remove commented-out test placeholder for brain mask dimension check

* WIP: Implement initial structure for ASLRegistration class with pipeline comments

* DOC: Add initial Copilot instructions for ASL toolkit usage and guidelines

* ENH: Add VSCode settings for Python testing configuration and commit message guidelines

* ENH: Improve ASL template registration by normalizing pcasl volumes and updating progress reporting

* ENH: Fix linter and merge conflicts

* ENH: Simplify workflow names for CI configurations

* BUG: Update lint check task name in CI workflows for consistency

* BUG: Update assertion in test_basic_report_generate_report_abstract_method to check for TypeError

* ENH: Remove unused parameter from asl_template_registration and delete obsolete test file

* ENH: Remove unused ASLRegistration class and add tests for head movement correction functionality

* ENH: Refactor space_normalization function by removing unused parameters and comments, and improving parameter handling

* DOC: Improve ASLData constructor documentation for clarity and detail

* ENH: Improve image resizing logic and optimize orientation analysis for better performance

* WIP: Update test_space_normalization_success to use actual ASLData paths and add new test for transform type Affine

* BUG: Fix M0 image loading to support both file paths and numpy arrays

* ENH: Implement image loading test for M0 using numpy array

* ENH: Add test for creating ASLData object with PCASL as numpy array and validate head movement correction output

* DOC: Improve head movement correction function with detailed docstring and update ASLData object

* BUG: Support loading ASL image from numpy array in ASLData initialization

* ENH: Add new test files for image manipulation and statistics, including various test cases for ASL model functions and image loading/saving functionalities

* ENH: Implement calculate_snr and analyze_image_properties functions for medical image analysis, including SNR calculation and image property assessment

* ENH: Refactor image property analysis by removing redundant function and integrating analyze_image_properties for improved clarity and efficiency

* REF: Refactor smoothing functionality by moving it to aux_methods.py and updating tests

* REF: Update smoothing function references in CBF, MultiDW, and MultiTE mapping files

* Add T2Scalar_ASLMapping to __all__ in __init__.py

* WIP: Add T2Scalar_ASLMapping initial implementation

* Add unit tests for MultiTE and T2Scalar ASL mapping functionalities

- Created `test_multi_te_mapping.py` to test MultiTE_ASLMapping class, including methods for setting brain masks, CBF and ATT maps, and creating maps.
- Implemented tests for error handling when ASLData is incomplete or when invalid parameters are provided.
- Added `test_te_mapping.py` for T2Scalar_ASLMapping class, verifying initialization, error handling for missing TE and PLD values, and successful T2 map creation.
- Removed the outdated `test_reconstruction.py` file to streamline test organization and improve maintainability.

* WIP: Refactor T2Scalar_ASLMapping: streamline initialization, enhance T2 fitting process, and improve error handling for TE and PLD values

* Remove unused import of asl_t2_scalar_multi_te from t2_mapping.py

* Refactor T2Scalar_ASLMapping: improve multiprocessing handling, enhance T2 fitting logic, and add unit tests for initialization and error scenarios

* TEST: Add tests for handling DW values in ASL data, T2 map retrieval, and brain mask functionality

* TEST: Add median smoothing tests with default parameters, different sizes, and invalid inputs

* ENH: Refactor T2Scalar_ASLMapping: enhance error handling for TE/PLD values, add logging for T2 map creation process, and restore multiprocessing functions

* STY: Remove commented TODO regarding LD/PLD size check in CBFMapping.create_map method

* ENH: Add validation for smoothing_params in _apply_smoothing_to_maps function

* DOC: Add Copilot instructions and code commit guidelines

* DOC: Improve documentation for T2Scalar_ASLMapping class and load_image function

* ENH: Add T2 Scalar Mapping script with argument parsing and processing logic

* ENH: Add T2 Scalar Mapping script documentation and update navigation in mkdocs

* ENH: Add script entries for ASLTK command line tools in pyproject.toml

* ENH: Update command usage in documentation and script help for clarity

* BUG: Fix M0 image loading to support both file paths and numpy arrays

* ENH: Implement image loading test for M0 using numpy array

* ENH: Add test for creating ASLData object with PCASL as numpy array and validate head movement correction output

* BUG: Support loading ASL image from numpy array in ASLData initialization

* ENH: Improve SNR and mean intensity calculations with ROI support and error handling

* ENH: Add tests for calculate_mean_intensity and improve calculate_snr tests with ROI support

* ENH: Add reference volume selection functionality with SNR and mean intensity methods

* DOC: Update copilot instructions with detailed commit message guidelines and prefix patterns

* ENH: Rename parameter 'transformation_matrix' to 'transforms' in apply_transformation function for clarity

* ENH: Improve ASLData class by adding warnings for 4D M0 images and averaging functionality for M0 images

* ENH: Refactor image loading and saving in tests, add error handling for invalid image inputs

* ENH: Enhance head movement correction by adding flexible reference volume selection and transformation proportion calculations

* ENH: Add select_reference_volume function and corresponding tests for reference volume selection

* ENH: Update error message for invalid reference volume and add validation check in head movement correction tests

* STY: Update import statement for load_image to correct module path

* STY: Update import statement for load_image to correct module path

* STY: Update import statement for load_image to correct module path

* Add T2Scalar_ASLMapping to __all__ in __init__.py

* Add unit tests for MultiTE and T2Scalar ASL mapping functionalities

- Created `test_multi_te_mapping.py` to test MultiTE_ASLMapping class, including methods for setting brain masks, CBF and ATT maps, and creating maps.
- Implemented tests for error handling when ASLData is incomplete or when invalid parameters are provided.
- Added `test_te_mapping.py` for T2Scalar_ASLMapping class, verifying initialization, error handling for missing TE and PLD values, and successful T2 map creation.
- Removed the outdated `test_reconstruction.py` file to streamline test organization and improve maintainability.

* Refactor T2Scalar_ASLMapping: improve multiprocessing handling, enhance T2 fitting logic, and add unit tests for initialization and error scenarios

* DOC: Add Copilot instructions and code commit guidelines

* ENH: Bumpversion v0.5.0

* Add T2Scalar_ASLMapping to __all__ in __init__.py

* Add unit tests for MultiTE and T2Scalar ASL mapping functionalities

- Created `test_multi_te_mapping.py` to test MultiTE_ASLMapping class, including methods for setting brain masks, CBF and ATT maps, and creating maps.
- Implemented tests for error handling when ASLData is incomplete or when invalid parameters are provided.
- Added `test_te_mapping.py` for T2Scalar_ASLMapping class, verifying initialization, error handling for missing TE and PLD values, and successful T2 map creation.
- Removed the outdated `test_reconstruction.py` file to streamline test organization and improve maintainability.

* Refactor T2Scalar_ASLMapping: improve multiprocessing handling, enhance T2 fitting logic, and add unit tests for initialization and error scenarios

* Add T2Scalar_ASLMapping to __all__ in __init__.py

* WIP: Add T2Scalar_ASLMapping initial implementation

* Add unit tests for MultiTE and T2Scalar ASL mapping functionalities

- Created `test_multi_te_mapping.py` to test MultiTE_ASLMapping class, including methods for setting brain masks, CBF and ATT maps, and creating maps.
- Implemented tests for error handling when ASLData is incomplete or when invalid parameters are provided.
- Added `test_te_mapping.py` for T2Scalar_ASLMapping class, verifying initialization, error handling for missing TE and PLD values, and successful T2 map creation.
- Removed the outdated `test_reconstruction.py` file to streamline test organization and improve maintainability.

* WIP: Refactor T2Scalar_ASLMapping: streamline initialization, enhance T2 fitting process, and improve error handling for TE and PLD values

* Refactor T2Scalar_ASLMapping: improve multiprocessing handling, enhance T2 fitting logic, and add unit tests for initialization and error scenarios

* Add T2Scalar_ASLMapping to __all__ in __init__.py

* WIP: Add T2Scalar_ASLMapping initial implementation

* Add unit tests for MultiTE and T2Scalar ASL mapping functionalities

- Created `test_multi_te_mapping.py` to test MultiTE_ASLMapping class, including methods for setting brain masks, CBF and ATT maps, and creating maps.
- Implemented tests for error handling when ASLData is incomplete or when invalid parameters are provided.
- Added `test_te_mapping.py` for T2Scalar_ASLMapping class, verifying initialization, error handling for missing TE and PLD values, and successful T2 map creation.
- Removed the outdated `test_reconstruction.py` file to streamline test organization and improve maintainability.

* WIP: Refactor T2Scalar_ASLMapping: streamline initialization, enhance T2 fitting process, and improve error handling for TE and PLD values

* Refactor T2Scalar_ASLMapping: improve multiprocessing handling, enhance T2 fitting logic, and add unit tests for initialization and error scenarios

* ENH: Implement image loading test for M0 using numpy array

* ENH: Add test for creating ASLData object with PCASL as numpy array and validate head movement correction output

* ENH: Implement image loading test for M0 using numpy array

* ENH: Implement image loading test for M0 using numpy array

* STY: Fix linter

* STY: Remove unused import of load_image from asltk.utils

* DEL: Remove copilot instructions document

* STY: Comment out unused imports and class definitions in report modules and tests

Author: acsenrafilho

asltk/__init__.py

@@ -3,6 +3,9 @@
 BIDS_IMAGE_FORMATS = ('.nii', '.nii.gz')
 AVAILABLE_IMAGE_FORMATS = ('.nii', '.nii.gz', '.mha', '.nrrd')
 
+PARCELLATION_REPORT_PATH = os.path.join(
+    os.path.expanduser('~'), 'asltk', os.path.sep, 'parcellation_reports'
+)
 # Import logging functionality for easy access
 from .logging_config import configure_for_scripts, get_logger, setup_logging
 

asltk/asldata.py

@@ -316,3 +316,11 @@ def _check_m0_dimension(self):
                 'This may cause issues in processing. '
                 'Consider averaging the M0 image across the first dimension.'
             )
+
+    def _check_m0_dimension(self):
+        if len(self._m0_image.shape) > 3:
+            warnings.warn(
+                'M0 image has more than 3 dimensions. '
+                'This may cause issues in processing. '
+                'Consider averaging the M0 image across the first dimension.'
+            )

asltk/registration/__init__.py

@@ -21,21 +21,6 @@ def __init__(self):
         pass
 
 
-# TODO Montar classe para fazer o coregistro de ASL
-class ASLRegistration:
-
-    # Pipeline
-    # inputs: ASLData (com m0 e pcasl), BrainAtlas, resolution (1 or 2 mm)
-    # Tomar m0 e comparar orientação com o template
-    # Se necessário, corrigir orientação do template para estar coerente com o m0 (salvar a transformação e aplicar para os labels)
-    # Realizar o registro do m0 no template
-    # com a transformação do m0, deixar salvo como parametro do objeto da classe
-    # Ter metodos para aplicar transformação para o pcasl, ou mapas gerados pelo CBFMapping, MultiTE, etc.
-
-    def __init__(self):
-        pass
-
-
 def space_normalization(
     moving_image: np.ndarray,
     template_image: BrainAtlas,