diff --git a/asltk/registration/asl_normalization.py b/asltk/registration/asl_normalization.py index 1663d6c..0ee27c3 100644 --- a/asltk/registration/asl_normalization.py +++ b/asltk/registration/asl_normalization.py @@ -271,7 +271,6 @@ def norm_function(vol, ref_volume): return new_asl_data, trans_mtx -# TODO Provavel que tenha que separar esse metodo para o asl_template_registration... revisar depois def __apply_array_normalization( total_vols, ref_vol, normalization_function, trans_proportions ): diff --git a/asltk/registration/orientation_utils.py b/asltk/registration/orientation_utils.py deleted file mode 100644 index e69de29..0000000 diff --git a/docs/api/asldata.md b/docs/api/asldata.md index b15a893..b8b0dd5 100644 --- a/docs/api/asldata.md +++ b/docs/api/asldata.md @@ -1 +1,13 @@ +# ASLtk base classes and functions + +## ASLData class API + ::: asldata + +## Auxiliary Methods API + +## Logging Configuration + +## MRI Parameters Class API + +::: mri_parameters diff --git a/docs/api/data.md b/docs/api/data.md index d791c87..7c62df8 100644 --- a/docs/api/data.md +++ b/docs/api/data.md @@ -1,12 +1,21 @@ -# Brain Atlas +# Data Module -The Brain Atlas module provides tools and data structures for representing, manipulating, and analyzing brain region information. It serves as a foundational component for working with anatomical brain atlases, enabling users to access region metadata, and collect atlas data into neuroimaging workflows. +## Brain Atlas -Use this module to facilitate research and development tasks that require standardized brain region definitions and mappings. +The `Brain Atlas` module provides tools and data structures for representing, manipulating, and analyzing brain region information. It serves as a foundational component for working with anatomical brain atlases, enabling users to access region metadata, and collect atlas data into neuroimaging workflows. -## Note +Use this module to facilitate research and development tasks that require standardized brain region definitions and mappings. -This module is intended for use with standardized brain atlases and may require adaptation for custom or non-standard datasets. Refer to the official documentation for integration guidelines and best practices. +!!! tip + The full list of availble brain atlases and templates in the `alstk` can be fetch using the `list_all()` method, as seen in the API description below +!!! note + This module is intended for use with standardized brain atlases and may require adaptation for custom or non-standard datasets. Refer to the official documentation for integration guidelines and best practices. + +## Data Module API + +### Brain Atlas Module API + +#### Brain Atlas Class API ::: data.brain_atlas \ No newline at end of file diff --git a/docs/api/models.md b/docs/api/models.md new file mode 100644 index 0000000..bd7777f --- /dev/null +++ b/docs/api/models.md @@ -0,0 +1,5 @@ +# Models Module + +## Signal Dynamic API + +::: models.signal_dynamic \ No newline at end of file diff --git a/docs/api/reconstruction.md b/docs/api/reconstruction.md index 13c90bc..8f2de55 100644 --- a/docs/api/reconstruction.md +++ b/docs/api/reconstruction.md @@ -1 +1,27 @@ +# Reconstruction Module + +## ASL Mapping Reconstruction + +This is the main module in `asltk` which aims to offer quantitative reconstruction algorithms for the `ASLData`. + +In general, the ASL processing requires data fitting and manipulation to result in quantitative mappings. A classical example are the CBF and ATT mapping. + +One of the major objective in `asltk` is to provide the state-of-the-art reconstruction methods available in the ASL research community, allowing an easy to use application to many studies. + +!!! note + It is intended to the `reconstruction` module to be evolve by the contribution of scientific community. If you want to apply a new reconstruction method in the `asltk` project, please see more details at the `How to Contribute` section and into the reconstruction classes standards + +### Reconstruction class standard + +In order to comply a standarized way to build the reconstruction classes, we assumed the following structure: + +1. All reconstruction classes must hierent from `MRIParameters` data class, which informs the base MRI parameters values for a generic data analysis and fitting +2. The base reconstruction class must have a constructor (`__init__` method) with an input data as the `ASLData` or other types (if needed). +3. Even though there is not obligation (regulated by abstract methods) for determined class methods, it is expected that the reconstruction class can implement a `create_map` method, which is the actual reconstruction calculation that exposes (as an method output) the reconstructed data from `ASLData`. + +!!! info + Depending on the specifity of the reconstruction method, it can vary the way that the inner reconstruction methods can be implemented. However, we try to maintain a basic API usage to get a more uniform implementation thoughout the community contribution. + +## Reconstruction Module API + ::: reconstruction \ No newline at end of file diff --git a/docs/api/registration.md b/docs/api/registration.md new file mode 100644 index 0000000..ece13e5 --- /dev/null +++ b/docs/api/registration.md @@ -0,0 +1,9 @@ +# Registration Module + +## Base Image Normalization API + +::: registration + +## ASL Normalization API + +::: registration.asl_normalization \ No newline at end of file diff --git a/docs/api/reports.md b/docs/api/reports.md index 649bbca..4f10285 100644 --- a/docs/api/reports.md +++ b/docs/api/reports.md @@ -1,12 +1,14 @@ -# Brain Parcellation Reports +# Reports Module + +## Brain Parcellation The Parcellation Report module provides utilities for generating detailed reports on brain parcellation results. These reports help users summarize, visualize, and interpret the outcomes of brain region segmentation and labeling processes. The module supports integration with the Brain Atlas workflow, enabling streamlined analysis and documentation of parcellation data. Use this module to create standardized, reproducible reports that facilitate communication and comparison of parcellation results across studies. -## Note - -The `reports` module provides quantitative pipelines designed to deliver clear and concise views of scientific data. Refer to the documentation for each available report to determine which method best suits your application. +!!! note + The `reports` module provides quantitative pipelines designed to deliver clear and concise views of scientific data. Refer to the documentation for each available report to determine which method best suits your application. +## Reconstruction Module API ::: data.reports \ No newline at end of file diff --git a/docs/api/utils.md b/docs/api/utils.md index 205e1ad..45c79ca 100644 --- a/docs/api/utils.md +++ b/docs/api/utils.md @@ -1 +1,42 @@ -::: utils \ No newline at end of file +# Utils Module + +## Image Manipulation API + + +The `utils.image_manipulation` module focuses on the preprocessing, orientation handling, and quality assessment of medical imaging data, particularly for Arterial Spin Labeling (ASL) MRI and similar volumetric neuroimaging datasets. It provides a set of utility functions designed to ensure that image volumes are properly aligned, normalized, and suitable for subsequent analysis or registration. + +The code integrates well-established Python libraries for medical imaging, such as `SimpleITK`, `ANTsPy`, and `NumPy`, alongside project-specific utilities from asltk. Its main objectives are: + +- Volume Management – Extracting and organizing 3D volumes from multi-dimensional ASL datasets. +- Orientation Analysis and Correction – Checking whether two images are properly aligned in orientation, automatically detecting mismatches, and applying corrective transformations (flips, transpositions, resampling). +- Image Quality Assessment – Computing key statistical measures such as mean intensity and signal-to-noise ratio (SNR) to assist in selecting representative or reference volumes for analysis. +- Reporting and Logging – Generating structured orientation analysis reports, with detailed information on image properties and recommended corrections. + +In practice, these tools are expected to be used as an early step in the ASL processing pipeline. By ensuring that image volumes are consistent in orientation and quality, the subsequent stages of image registration, quantification, and biomarker extraction can be performed more reliably. + +::: utils.image_manipulation + +## Image Statistics API + +The `utils.image_statistics` module provides core utility functions for the quantitative analysis of medical images, focusing on extracting essential statistical and structural properties from volumetric data. The implemented functions are designed to support preprocessing, quality assessment, and orientation verification of medical imaging. + +The main goals of this code is to provide quantitative analysis such as SNR, mean image intensity, correlations, and many others image properties. + +By combining these functions, the module supports early steps in medical image analysis pipelines, where image quality and structural consistency must be verified before applying more advanced techniques like registration, segmentation, or quantitative biomarker extraction. + +::: utils.image_statistics + +## IO + +The `utils.io` module provides utility functions for loading, saving, and managing medical imaging data, with a focus on Arterial Spin Labeling (ASL) MRI and BIDS-compliant datasets. It builds on libraries such as SimpleITK, NumPy, and dill, allowing users to handle both raw image files and serialized data objects in a reproducible way. + +The main features include: + +- Loading Images: Supports a wide range of formats (e.g., .nii, .nii.gz, .nrrd, .mha, .tif) and can automatically detect and load files from a BIDS directory structure. +- Saving Images: Exports images in multiple formats, either to a direct path or within a valid BIDS folder hierarchy. +- Managing ASL Data: Provides serialization (save_asl_data) and deserialization (load_asl_data) of ASL datasets using dill for robust object storage. +- BIDS Integration: Ensures compatibility with the BIDS specification, helping organize imaging data systematically across subjects and sessions. + +These tools are intended to serve as a foundation for preprocessing and organizing ASL datasets, ensuring that images and related data are stored, retrieved, and shared in a standardized and efficient way before further analysis. + +::: utils.io \ No newline at end of file diff --git a/docs/contribute.md b/docs/contribute.md index 579a216..0e31788 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,5 +1,11 @@ # How to Contribute +First of all, thank you for any contribution to the `asltk` project! + +The following details in this page is aimed to assist the general code formatting and explain the logic behind the `asltk` tool. Please, read with attention all the details below in advance to any coding contribution in the Github repository. + +We will cover the topics as presented in the [Homepage](index.md) page in details. However, please take a general overview for the project preparation at you local machine. + ## Preparing the coding environment The first step to start coding new features or correcting bugs in the `asltk` library is doing the repository fork, directly on GitHub, and following to the repository clone: @@ -23,7 +29,10 @@ cd asltk poetry shell && poetry install ``` -Then all the dependencies will be installed and the virtual environment will be created. After all being done successfully, the shortcuts for `test` and `doc` can be called: +!!! note + Depending on the Poetry version the command `poetry shell` or other can vary. Please, first check if the Poetry installation and usage are already setup before following the repository adjustment. + +Then, after the successful Poetry repository installation being completed, all the dependencies will be installed and the virtual environment will be created. Hence, the aliases for `test` and `doc` can be called: ```bash task test @@ -35,6 +44,10 @@ task doc More details about the entire project configuration is provided in the `pyproject.toml` file. +!!! tip + The `asltk` presents some aliases setup in the `pyproject.toml` configuration to assist some common steps in the code develpment. Check theses commands to understand there usages. By the way, if you want to prepare some interesting and useful new alias to the project, feel free to contribute! + + ### Basic tools We assume the following list of developing, testing and documentation tools: @@ -50,9 +63,17 @@ We assume the following list of developing, testing and documentation tools: 9. mkdocs-material 10. pymdown-extensions +and others... + Further adjustments in the set of tools for the project can be modified in the future. However, the details about these modifications are directly reported in new releases, regarding the specific tool versioning (more details at Version Control section) -## Code Structure +## ASLtk Coding Patterns + +Now, as soon as you get all the `asltk` setup been made as described in the above sections, one can follow to the actual coding activity. + +Check carefully the following details: + +### Code Structure The general structure of the `asltk` library is given as the following: @@ -60,6 +81,7 @@ The general structure of the `asltk` library is given as the following: classDiagram MRIParameters <|-- CBFMapping MRIParameters <|-- MultiTE_ASLMapping + MRIParameters <|-- MultiDW_ASLMapping class MRIParameters{ +float T1bl +float T1csf @@ -72,12 +94,21 @@ classDiagram -get_constant(param) } class CBFMapping{ - +__inti__(ASLData) + +__init__(ASLData) +set_brain_mask(brain_mask, label) +create_map() } class MultiTE_ASLMapping{ - +__inti__(ASLData) + +__init__(ASLData) + +set_brain_mask(brain_mask, label) + +set_cbf_map(cbf_map) + -get_cbf_map() + +set_att_map(att_map) + -get_att_map() + +create_map() + } + class MultiDW_ASLMapping{ + +__init__(ASLData) +set_brain_mask(brain_mask, label) +set_cbf_map(cbf_map) -get_cbf_map() @@ -93,6 +124,14 @@ classDiagram +List TE (optional) +List DW (optional) } + class BrainAtlas{ + +__init__(atlas_name) + +set_atlas(atlas_name) + +get_atlas() + +get_atlas_url() + +get_atlas_labels() + +list_atlas() + } ``` Where the `ASLData` class informs the basic data structure to all the ASL mapping strategies. All the ASL processing methods, implemented in the `reconstruction.py` module, have to include a `ASLData` object to the class instance. In particular, for each ASL processing instance that has been created, one can change it's particular `MRIParameters` calling the inheritance parameters. @@ -107,12 +146,14 @@ The `MultiTE_ASLMapping` class provides the implementation of the multi time of !!! tip If the CBF and ATT maps are already present before the call for `MultiTE_ASLMapping` calculation, then the `set_cbf_map` and `set_att_map` methods are useful. +!!! warning + The `asltk` project is applies a hibrid approach between Object-Oriented Programming (OOP) coding strategy and a direct Python function-based usage. Depending on the generalization that can be applied in the scope of the project, the OOP is prefered. Otherwise, if the method being applied can be very specific and localized, then a direct Python function is a better way to go. Decide it wisely! As a coding patterns, it is expected that new ASL processing techniques will be placed in the class organization given as above diagram. All new classes that can be added in the future, should be as follows: -1. A new class implementation in the `reconstruction.py` module +1. A new class implementation in the `reconstruction` module 2. Provides a collection of `set` and `get` methods for required additional data that is not responsability to the `ASLData` structure -3. Implements the `create_map()` method, giving the correct input parameters required in the specific ASL processing method. +3. Implements the `create_map()` method (if it is the case for generated mapping information), giving the correct input parameters required in the specific ASL processing method. !!! question In case of any doubt, discuss with the community using a [issue card](https://github.com/LOAMRI/asltk/issues) in the repo. @@ -121,7 +162,7 @@ As a coding patterns, it is expected that new ASL processing techniques will be [^2]: L Petitclerc et al. "Ultra-long-TE arterial spin labeling reveals rapid and brain-wide blood-to-CSF water transport in humans". Neuroimage (2022). DOI: 10.1016/j.neuroimage.2021.118755 -## Testing +### Testing Another coding pattern expected in new contributions in the `asltk` library is the uses of unit tests. @@ -134,7 +175,43 @@ Each module or class implemented in the `asltk` library should have a series of task test ``` -## Code Documentation +As a coding quality standard applied in `asltk` is that the code testing coverage must be above 80%. Hence, take care if the new contributions will not drop the current code testing too much. Of course, there are leverage that we can play with, however any strong decrease in code coverage is unintended. + +!!! note + All the Pull Requests (PR) in the `asltk` has an automatic code testing evaluation that will ensure if the final testing coverage is within the 80% goal. If not, then it will raise an attention to request more improvements. + +### Build and deployment instructions + +We adopt automatic (or semi-automatic) Continous Integration (CI) and Continous Deployment (CD) at the `asltk` project. All of these procedures are controlled by the Github Actions workflows. + +This configuration will kept under the administrators watch, however, if one can assist to any improvement regarding CI/CD coverage, performance and any other interesting improvement, then tell us opening an [issue](https://github.com/LOAMRI/asltk/issues). + +!!! tip + Check the details about the CI/CD workflows at the `.github` folder in the project + +### Extending the library + +The main objective of `asltk` project is to help MRI researchers and clinitians in ASL processing pipelines. Of course, this effort is mandatory to be a community-based construction and not only belonging to a single laboratory in the world. Therefore, an new extension of `modules`, `methods` or `classes` are more then welcome. + +!!! note + Please, just take the focus of any contribution that are in the scope of ASL-MRI processing. + +We highlight this main point due to occasions that one can offer a new contribution that are related to image handling or DICOM protocol instead. Although we completely understand some other issues can appear along the work in research with state-of-the-art data and analysis, we should keep the `asltk` functional responsibility restrict to ASL only. + +If you want to provide a new functionality in the `asltk`, e.g. a new class that supports a novel ASL processing method, please keep the same data and coding structure as described in the `Code Structure` section. + +Any new ideas to improve the project readbility and coding organization is also welcome. If it is the case, please raise a new issue ticket at GitHub, using the Feature option to open an community debate about your suggestion. Once it is approved, a new project version is release with the new implementations glued in the core code. + +### Dependency management + +All the dependencies manage in the `asltk` project must be in accordance with the Poetry handling, as exposed and manage in the `pyproject.toml` file. + +If one may want or need to include another library in the `asltk` dependency three, please make sure that this will not offer incompatibilities to others previous dependencies that already adjusted in the repository. + +!!! tip + No worry, if a new dependency will be added and has some incompatibility to the code, it is highly probable that the dependency installation and/or code unit test coverage will alert you. + +### Code Documentation The coding documentation pattern is the [Google Docstring](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) @@ -147,21 +224,17 @@ Please, provide as much details as possible in the methods, classes and modules The docstring also passes to a test analysis, then take care about adding `Examples` in the docstring, respecting the same usage pattern for input/output as the code provides - -## Version Control +### Version Control The `asltk` project adopts the [Semantic Versioning 2.0.0 SemVer](https://semver.org/) versioning pattern. Please, also take care about the specific version changes that will be added by further implementations. Another important consideration is that the `asltk` repository has two permanent branches: `main` and `develop`. The `main` branch is placed to stable, versioning controled releases, and the `develop` branch is for unstable most up-to-date functionalities. In order to keep the library as more reliable as possible, please consider making a Pull Request (PR) at the `develop` branch before passing it to the `main` branch. +!!! warning + The actual action to pass the contribution from `develop` to `main` branch is made only for the `asltk` repository administrators. In any case, any question can be raised if needed, just open an [Help me! issue type](https://github.com/LOAMRI/asltk/issues). -## Extending the library - -### Extending core functionalities - -If you want to provide a new functionality in the `asltk`, e.g. a new class that supports a novel ASL processing method, please keep the same data and coding structure as described in the `Code Structure` section. -Any new ideas to improve the project readbility and coding organization is also welcome. If it is the case, please raise a new issue ticket at GitHub, using the Feature option to open an community debate about your suggestion. Once it is approved, a new project version is release with the new implementations glued in the core code. +## Additional help for extending the `asltk` project ### Scripts @@ -176,24 +249,24 @@ In this way, you can share a code that can be called for a specific execution an For instance, a call execution considering the `cbf.py` script can be showed using the `--help` option: ```bash -usage: cbf.py [-h] --pld PLD [PLD ...] --ld LD [LD ...] [--verbose] pcasl m0 [mask] [out_folder] +usage: CBF/ATT Mapping [-h] [--pld PLD [PLD ...]] [--ld LD [LD ...]] [--verbose] [--file_fmt [FILE_FMT]] pcasl m0 [mask] [out_folder] Python script to calculate the basic CBF and ATT maps from ASL data. -positional arguments: - pcasl ASL raw data obtained from the MRI scanner. This must be the basic PLD ASL MRI acquisition protocol. - m0 M0 image in Nifti format. - mask Image mask defining the ROI where the calculations must be done. Any pixel value different from zero will be assumed as the ROI area. - Outside the mask (value=0) will be ignored. - out_folder The output folder that is the reference to save all the output images in the script. The images selected to be saved are given as tags - in the script caller, e.g. the options --cbf_map and --att_map. By default, the TblGM map is placed in the output folder with the name - tblgm_map.nii.gz - - options: - -h, --help show this help message and exit - --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers - --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. - --verbose Show more details thoughout the processing. +Required parameters: + pcasl ASL raw data obtained from the MRI scanner. This must be the basic PLD ASL MRI acquisition protocol. + m0 M0 image reference used to calculate the ASL signal. + out_folder The output folder that is the reference to save all the output images in the script. The images selected to be saved are given as tags in the script caller, e.g. the + options --cbf_map and --att_map. By default, the TblGM map is placed in the output folder with the name tblgm_map.nii.gz + +Optional parameters: + mask Image mask defining the ROI where the calculations must be done. Any pixel value different from zero will be assumed as the ROI area. Outside the mask (value=0) will be + ignored. If not provided, the entire image space will be calculated. + --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers. If not passed, the default values will be used. + --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. If not passed, the default values will be used. + --verbose Show more details thoughout the processing. + --file_fmt [FILE_FMT] + The file format that will be used to save the output images. It is not allowed image compression (ex: .gz, .zip, etc). Default is nii, but it can be choosen: mha, nrrd. ``` !!! tip @@ -201,3 +274,6 @@ positional arguments: !!! info We adopted the general Python `Argparse` scripting module to create a standarized code. More details on how to use it can be found at the [official documentation](https://docs.python.org/3/library/argparse.html) + +!!! note + It is also helpful to set an script alias in the `pyproject.toml` as seen in section `[tool.poetry.scripts]`. There one can find the same calls for the script seen as above, however in a much simpler way. \ No newline at end of file diff --git a/docs/getting_started.md b/docs/getting_started.md index 8392f2a..eda2aa1 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -21,7 +21,7 @@ data = ASLData( The example above creates an `asldata.ASLData` object, called `data`, which will store the pCASL and M0 images, along with the LD, PLD and TE values (in this case we are showing a prototype of multiTE-ASL data loading) !!! tip - There are many other image file formatts that is accepted in the `asltk` tool. We adopted the `SimpleITK` API, then one can check the image formatts in the [official documentation](https://simpleitk.readthedocs.io/en/master/IO.html) + There are many other image file formats that is accepted in the `asltk` tool. We adopted the `SimpleITK` API, then one can check the image formatts in the [official documentation](https://simpleitk.readthedocs.io/en/master/IO.html) ## Example operation using `asltk` diff --git a/docs/index.md b/docs/index.md index 38d04c2..6b43b73 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,9 +37,11 @@ Any improvement and suggestions are more than welcome. The ASL toolkit is a coll 8. Code documentation 9. Version control +See the [How to Contribute](contribute.md) section for more details about the above topics. + !!! note - All the documentation is by default generated in the American English language. Even though this may not be the first language for some users or code developers (including me), it is encouraging to follow this language format to keep the information as broad and accessible as possible. Furthermore, better documentation is also a wonderful way to help the project, so if you want to contribute to correcting typos, grammar or confounding sentences, please make a PR! + All the documentation is by default generated in the American English language. Even though this may not be the first language for some users or code developers (including me), it is encouraging to follow this language format to keep the information as broad and accessible as possible. Furthermore, better documentation is also a wonderful way to help the project, so if you want to contribute to correcting typos, grammar or confounding sentences, please make a Pull Request (PR)! ## Audience diff --git a/docs/logging.md b/docs/logging.md index 603b8c0..d9bb417 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -1,4 +1,4 @@ -# ASLTK Logging System +# ASLtk Logging System The ASLTK library includes a comprehensive logging system that provides detailed runtime information about ASL data processing operations. This system helps with debugging, monitoring, and understanding the behavior of ASL processing workflows. diff --git a/docs/scripts/cbf_script.md b/docs/scripts/cbf_script.md deleted file mode 100644 index b1a134d..0000000 --- a/docs/scripts/cbf_script.md +++ /dev/null @@ -1,47 +0,0 @@ -# CBF/ATT Mapping Script - -This documentation provides an overview of the `cbf.py` script, which is used to calculate the basic CBF (Cerebral Blood Flow) and ATT (Arterial Transit Time) maps from ASL (Arterial Spin Labeling) data. - -## Overview - -The `cbf.py` script processes ASL data to generate CBF and ATT maps. The script takes ASL raw data, an M0 image, and optional parameters such as a mask image, PLD (Post Labeling Delay) values, and LD (Labeling Duration) values. The output includes the CBF map, normalized CBF map, and ATT map. - -## Usage - -To run the script, use the following command: - -```bash -asltk_cbf pcasl m0 [mask] [out_folder] --pld PLD [PLD ...] --ld LD [LD ...] [--verbose] [--file_fmt [FILE_FMT]] [-h] [options] -``` - -## General description - -The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: - -```bash -usage: CBF/ATT Mapping pcasl m0 [mask] [out_folder] --pld PLD [PLD ...] --ld LD [LD ...] -[--file_fmt [FILE_FMT]] [--verbose] [-h] - - -Python script to calculate the basic CBF and ATT maps from ASL data. - -Required parameters: - pcasl ASL raw data obtained from the MRI scanner. This must be the basic PLD ASL MRI acquisition - protocol. - m0 M0 image reference used to calculate the ASL signal. - out_folder The output folder that is the reference to save all the output images in the script. The - images selected to be saved are given as tags in the script caller, e.g. the options - --cbf_map and --att_map. By default, the TblGM map is placed in the output folder with the - name tblgm_map.nii.gz - --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers - --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. - -Optional parameters: - mask Image mask defining the ROI where the calculations must be done. Any pixel value different - from zero will be assumed as the ROI area. Outside the mask (value=0) will be ignored. If - not provided, the entire image space will be calculated. - --verbose Show more details thoughout the processing. - --file_fmt [FILE_FMT] - The file format that will be used to save the output images. It is not allowed image - compression (ex: .gz, .zip, etc). Default is nii, but it can be choosen: mha, nrrd. -``` \ No newline at end of file diff --git a/docs/scripts/generate_sub_asl_image.md b/docs/scripts/generate_sub_asl_image.md deleted file mode 100644 index 2442156..0000000 --- a/docs/scripts/generate_sub_asl_image.md +++ /dev/null @@ -1,66 +0,0 @@ -# Generate Subtracted ASL Image Script (Hadamard acquisition) - -This documentation provides an overview of the `generate_subtracted_asl_image.py` script, which assists in reconstructing the ASL image already subtracted from control and tagged volumes. The script assumes that the ASL raw data was acquired using MRI imaging protocols based on [Hadamard matrix](https://en.wikipedia.org/wiki/Hadamard_matrix) acquisition. - -## Overview - -The `generate_subtracted_asl_image.py` script processes ASL data to generate subtracted ASL images. The script takes ASL raw data, optional parameters such as PLD (Post Labeling Delay) values, LD (Labeling Duration) values, TE (Time of Echo) values, and DW (Diffusion Weights) values. The output includes the subtracted ASL image. - -## Usage - -To run the script, use the following command: - -```bash -asltk_hadamard datafolder [--matrix_order MATRIX_ORDER] [--dynamic_vols DYNAMIC_VOLS] [--pld PLD [PLD ...]] [--ld LD [LD ...]] [--output_folder [OUTPUT_FOLDER]] [--mask [MASK]] [--te TE [TE ...]] [--dw DW [DW ...]] [--file_fmt FILE_FMT] [--verbose] [-h] -``` - -## General description - -The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: - -```bash -usage: Generate Subtracted ASL Image datafolder [--matrix_order MATRIX_ORDER] [--dynamic_vols DYNAMIC_VOLS] -[--pld PLD [PLD ...]] [--ld LD [LD ...]] [--output_folder [OUTPUT_FOLDER]] [--mask [MASK]] -[--te TE [TE ...]] [--dw DW [DW ...]] [--file_fmt FILE_FMT] [--verbose] [-h] - -Python script to assist in reconstructing the ASL image already subtract from control and tagged volumes. This -script assumes that the ASL raw data was acquired using a MRI imaging protocols based on Hadamard matrix -acquisition. There are some default values for the PLD and LD, but the user can inform the values used in the MRI -protocol. Please, be aware about the default values and inform the correct values used in the MRI protocol. - -Required parameters: - datafolder Folder containing the ASL raw data obtained from the MRI scanner. This folder must have the - Nifti files converted from the DICOM files. By default the output file name adopted is - pcasl.(file_fmt), where file_fmt is the file format informed in the parameter --file_fmt. - TIP: One can use other tools such dcm2nii to convert DICOM data to Nifti. - --matrix_order MATRIX_ORDER - Informs the Hadamar matrix size used in the MRI imaging protocol. This must be a positive - power-of-two integer (n^2). - --dynamic_vols DYNAMIC_VOLS - Informs the number of dynamic volumes used in the MRI acquisition. - --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers. If not passed, - the default values will be used. - --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. If not passed, the - default values will be used. - -Optional parameters: - --output_folder [OUTPUT_FOLDER] - The output folder that is the reference to save the output image. By default, the output - image will be saved in the same folder as the input data. If informed, the output image - will be saved in the folder informed. - --mask [MASK] Image mask defining the ROI where the calculations must be done. Any pixel value different - from zero will be assumed as the ROI area. Outside the mask (value=0) will be ignored. If - not provided, the entire image space will be calculated. - --te TE [TE ...] Time of Echos (TE), arranged in a sequence of float numbers. This is only required for - multi-TE ASL data. This sequence of values must be in accordance with the number of volumes - acquired in the MRI protocol. - --dw DW [DW ...] Diffusion weights (DW), arranged in a sequence of float numbers. This is only required for - multi-DW ASL data. This sequence of values must be in accordance with the number of volumes - acquired in the MRI protocol. - --file_fmt FILE_FMT Define the file format to load the ASL data in the datafolder parameter and also be used - for saving the output image. The default is Nifti format (nii). File formats allowed: nii, - mha, nrrd. TIP: This file format depends on the output of the DICOM converter tool used, - then it is important to check the output format of the tool used to convert the DICOM files - to Nifti files. - --verbose Show more details thoughout the processing. -``` \ No newline at end of file diff --git a/docs/scripts/multi_te_script.md b/docs/scripts/multi_te_script.md deleted file mode 100644 index b0e5347..0000000 --- a/docs/scripts/multi_te_script.md +++ /dev/null @@ -1,55 +0,0 @@ -# Multi-TE ASL Mapping Script - -This documentation provides an overview of the `te_asl.py` script, which is used to calculate the Multi-TE ASL map for the T1 relaxation exchange between blood and Gray Matter (GM). - -## Overview - -The `te_asl.py` script processes ASL data to generate the T1 relaxation exchange between blood and Gray Matter (T1blGM) map and, also as an additional information, it can export the CBF (Cerebral Blood Flow), normalized CBF and ATT (Arterial Transit Time) maps. - -The script takes ASL raw data, an M0 image, and optional parameters such as a mask image, PLD (Post Labeling Delay) values, LD (Labeling Duration) values, and TE (Time of Echo) values. The output includes the CBF map, normalized CBF map, ATT map, and T1blGM map. - -## Usage - -To run the script, use the following command: - -```bash -asltk_te_asl pcasl m0 [mask] [out_folder] [--cbf [CBF]] [--att [ATT]] --pld PLD PLD ...] --ld LD [LD ...] --te TE [TE ...] [--file_fmt [FILE_FMT]] [--verbose] [-h] -``` - -## General description - -The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: - -```bash -usage: Multi-TE ASL Mapping pcasl m0 [mask] [out_folder] -[--cbf [CBF]] [--att [ATT]] --pld PLD [PLD ...] ---ld LD [LD ...] --te TE [TE ...] [--verbose] [--file_fmt [FILE_FMT]] [-h] - -Python script to calculate the Multi-TE ASL map for the T1 relaxation exchange between blood and Gray Matter (GM). - -Required parameters: - pcasl ASL raw data obtained from the MRI scanner. This must be the multi-TE ASL MRI acquisition - protocol. - m0 M0 image reference used to calculate the ASL signal. - out_folder The output folder that is the reference to save all the output images in the script. The - images selected to be saved are given as tags in the script caller, e.g. the options - --cbf_map and --att_map. By default, the TblGM map is placed in the output folder with the - name tblgm_map.nii.gz - --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers - --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. - --te TE [TE ...] Time of Echos (TE), arranged in a sequence of float numbers. - -Optional parameters: - mask Image mask defining the ROI where the calculations must be done. Any pixel value different - from zero will be assumed as the ROI area. Outside the mask (value=0) will be ignored. If - not provided, the entire image space will be calculated. - --cbf [CBF] The CBF map that is provided to skip this step in the MultiTE-ASL calculation. If CBF is - not provided, than a CBF map is calculated at the runtime. Important: The CBF passed here - is with the original voxel scale, i.e. without voxel normalization. - --att [ATT] The ATT map that is provided to skip this step in the MultiTE-ASL calculation. If ATT is - not provided, than a ATT map is calculated at the runtime. - --verbose Show more details thoughout the processing. - --file_fmt [FILE_FMT] - The file format that will be used to save the output images. It is not allowed image - compression (ex: .gz, .zip, etc). Default is nii, but it can be choosen: mha, nrrd. -``` \ No newline at end of file diff --git a/docs/scripts/script_methods.md b/docs/scripts/script_methods.md new file mode 100644 index 0000000..75831ef --- /dev/null +++ b/docs/scripts/script_methods.md @@ -0,0 +1,213 @@ +# ASLtk Scripts + +## CBF/ATT Mapping Script + +This documentation provides an overview of the `cbf.py` script, which is used to calculate the basic CBF (Cerebral Blood Flow) and ATT (Arterial Transit Time) maps from ASL (Arterial Spin Labeling) data. + +### Overview + +The `cbf.py` script processes ASL data to generate CBF and ATT maps. The script takes ASL raw data, an M0 image, and optional parameters such as a mask image, PLD (Post Labeling Delay) values, and LD (Labeling Duration) values. The output includes the CBF map, normalized CBF map, and ATT map. + +### Usage + +To run the script, use the following command: + +```bash +asltk_cbf pcasl m0 [mask] [out_folder] --pld PLD [PLD ...] --ld LD [LD ...] [--verbose] [--file_fmt [FILE_FMT]] [-h] [options] +``` + +### General description + +The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: + +```bash +usage: CBF/ATT Mapping pcasl m0 [mask] [out_folder] --pld PLD [PLD ...] --ld LD [LD ...] +[--file_fmt [FILE_FMT]] [--verbose] [-h] + + +Python script to calculate the basic CBF and ATT maps from ASL data. + +Required parameters: + pcasl ASL raw data obtained from the MRI scanner. This must be the basic PLD ASL MRI acquisition + protocol. + m0 M0 image reference used to calculate the ASL signal. + out_folder The output folder that is the reference to save all the output images in the script. The + images selected to be saved are given as tags in the script caller, e.g. the options + --cbf_map and --att_map. By default, the TblGM map is placed in the output folder with the + name tblgm_map.nii.gz + --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers + --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. + +Optional parameters: + mask Image mask defining the ROI where the calculations must be done. Any pixel value different + from zero will be assumed as the ROI area. Outside the mask (value=0) will be ignored. If + not provided, the entire image space will be calculated. + --verbose Show more details thoughout the processing. + --file_fmt [FILE_FMT] + The file format that will be used to save the output images. It is not allowed image + compression (ex: .gz, .zip, etc). Default is nii, but it can be choosen: mha, nrrd. +``` + +## Multi-TE ASL Mapping Script + +This documentation provides an overview of the `te_asl.py` script, which is used to calculate the Multi-TE ASL map for the T1 relaxation exchange between blood and Gray Matter (GM). + +### Overview + +The `te_asl.py` script processes ASL data to generate the T1 relaxation exchange between blood and Gray Matter (T1blGM) map and, also as an additional information, it can export the CBF (Cerebral Blood Flow), normalized CBF and ATT (Arterial Transit Time) maps. + +The script takes ASL raw data, an M0 image, and optional parameters such as a mask image, PLD (Post Labeling Delay) values, LD (Labeling Duration) values, and TE (Time of Echo) values. The output includes the CBF map, normalized CBF map, ATT map, and T1blGM map. + +### Usage + +To run the script, use the following command: + +```bash +asltk_te_asl pcasl m0 [mask] [out_folder] [--cbf [CBF]] [--att [ATT]] --pld PLD PLD ...] --ld LD [LD ...] --te TE [TE ...] [--file_fmt [FILE_FMT]] [--verbose] [-h] +``` + +### General description + +The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: + +```bash +usage: Multi-TE ASL Mapping pcasl m0 [mask] [out_folder] +[--cbf [CBF]] [--att [ATT]] --pld PLD [PLD ...] +--ld LD [LD ...] --te TE [TE ...] [--verbose] [--file_fmt [FILE_FMT]] [-h] + +Python script to calculate the Multi-TE ASL map for the T1 relaxation exchange between blood and Gray Matter (GM). + +Required parameters: + pcasl ASL raw data obtained from the MRI scanner. This must be the multi-TE ASL MRI acquisition + protocol. + m0 M0 image reference used to calculate the ASL signal. + out_folder The output folder that is the reference to save all the output images in the script. The + images selected to be saved are given as tags in the script caller, e.g. the options + --cbf_map and --att_map. By default, the TblGM map is placed in the output folder with the + name tblgm_map.nii.gz + --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers + --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. + --te TE [TE ...] Time of Echos (TE), arranged in a sequence of float numbers. + +Optional parameters: + mask Image mask defining the ROI where the calculations must be done. Any pixel value different + from zero will be assumed as the ROI area. Outside the mask (value=0) will be ignored. If + not provided, the entire image space will be calculated. + --cbf [CBF] The CBF map that is provided to skip this step in the MultiTE-ASL calculation. If CBF is + not provided, than a CBF map is calculated at the runtime. Important: The CBF passed here + is with the original voxel scale, i.e. without voxel normalization. + --att [ATT] The ATT map that is provided to skip this step in the MultiTE-ASL calculation. If ATT is + not provided, than a ATT map is calculated at the runtime. + --verbose Show more details thoughout the processing. + --file_fmt [FILE_FMT] + The file format that will be used to save the output images. It is not allowed image + compression (ex: .gz, .zip, etc). Default is nii, but it can be choosen: mha, nrrd. +``` + +## Generate Subtracted ASL Image Script (Hadamard acquisition) + +This documentation provides an overview of the `generate_subtracted_asl_image.py` script, which assists in reconstructing the ASL image already subtracted from control and tagged volumes. The script assumes that the ASL raw data was acquired using MRI imaging protocols based on [Hadamard matrix](https://en.wikipedia.org/wiki/Hadamard_matrix) acquisition. + +### Overview + +The `generate_subtracted_asl_image.py` script processes ASL data to generate subtracted ASL images. The script takes ASL raw data, optional parameters such as PLD (Post Labeling Delay) values, LD (Labeling Duration) values, TE (Time of Echo) values, and DW (Diffusion Weights) values. The output includes the subtracted ASL image. + +### Usage + +To run the script, use the following command: + +```bash +asltk_hadamard datafolder [--matrix_order MATRIX_ORDER] [--dynamic_vols DYNAMIC_VOLS] [--pld PLD [PLD ...]] [--ld LD [LD ...]] [--output_folder [OUTPUT_FOLDER]] [--mask [MASK]] [--te TE [TE ...]] [--dw DW [DW ...]] [--file_fmt FILE_FMT] [--verbose] [-h] +``` + +### General description + +The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: + +```bash +usage: Generate Subtracted ASL Image datafolder [--matrix_order MATRIX_ORDER] [--dynamic_vols DYNAMIC_VOLS] +[--pld PLD [PLD ...]] [--ld LD [LD ...]] [--output_folder [OUTPUT_FOLDER]] [--mask [MASK]] +[--te TE [TE ...]] [--dw DW [DW ...]] [--file_fmt FILE_FMT] [--verbose] [-h] + +Python script to assist in reconstructing the ASL image already subtract from control and tagged volumes. This +script assumes that the ASL raw data was acquired using a MRI imaging protocols based on Hadamard matrix +acquisition. There are some default values for the PLD and LD, but the user can inform the values used in the MRI +protocol. Please, be aware about the default values and inform the correct values used in the MRI protocol. + +Required parameters: + datafolder Folder containing the ASL raw data obtained from the MRI scanner. This folder must have the + Nifti files converted from the DICOM files. By default the output file name adopted is + pcasl.(file_fmt), where file_fmt is the file format informed in the parameter --file_fmt. + TIP: One can use other tools such dcm2nii to convert DICOM data to Nifti. + --matrix_order MATRIX_ORDER + Informs the Hadamar matrix size used in the MRI imaging protocol. This must be a positive + power-of-two integer (n^2). + --dynamic_vols DYNAMIC_VOLS + Informs the number of dynamic volumes used in the MRI acquisition. + --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers. If not passed, + the default values will be used. + --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. If not passed, the + default values will be used. + +Optional parameters: + --output_folder [OUTPUT_FOLDER] + The output folder that is the reference to save the output image. By default, the output + image will be saved in the same folder as the input data. If informed, the output image + will be saved in the folder informed. + --mask [MASK] Image mask defining the ROI where the calculations must be done. Any pixel value different + from zero will be assumed as the ROI area. Outside the mask (value=0) will be ignored. If + not provided, the entire image space will be calculated. + --te TE [TE ...] Time of Echos (TE), arranged in a sequence of float numbers. This is only required for + multi-TE ASL data. This sequence of values must be in accordance with the number of volumes + acquired in the MRI protocol. + --dw DW [DW ...] Diffusion weights (DW), arranged in a sequence of float numbers. This is only required for + multi-DW ASL data. This sequence of values must be in accordance with the number of volumes + acquired in the MRI protocol. + --file_fmt FILE_FMT Define the file format to load the ASL data in the datafolder parameter and also be used + for saving the output image. The default is Nifti format (nii). File formats allowed: nii, + mha, nrrd. TIP: This file format depends on the output of the DICOM converter tool used, + then it is important to check the output format of the tool used to convert the DICOM files + to Nifti files. + --verbose Show more details thoughout the processing. +``` + +## T2 Scalar Mapping Script + +This documentation provides an overview of the `t2_maps.py` script, which is used to calculate the T2 scalar maps from multi echo (Multi-TE) ASL (Arterial Spin Labeling) data. + +### Overview + +The `t2_maps.py` script processes ASL data to generate T2 scalar maps. The script takes ASL raw data, an M0 image, and optional parameters such as a mask image, PLD (Post Labeling Delay) values, and LD (Labeling Duration) values. The output includes the T2 maps for each PLD value. + +### Usage + +To run the script, use the following command: + +```bash +asltk_cbf pcasl m0 [mask] [out_folder] --pld PLD [PLD ...] --ld LD [LD ...] [--verbose] [--file_fmt [FILE_FMT]] [-h] [options] +``` + +### General description + +The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: + +```bash +usage: T2 Scalar Mapping from ASL Multi-TE ASLData [-h] [--pld PLD [PLD ...]] [--ld LD [LD ...]] [--te TE [TE ...]] [--verbose] [--file_fmt [FILE_FMT]] pcasl m0 [mask] [out_folder] + +Python script to calculate the T2 scalar map from the ASL Multi-TE ASLData. + +Required parameters: + pcasl ASL raw data obtained from the MRI scanner. This must be the multi-TE ASL MRI acquisition protocol. + m0 M0 image reference used to calculate the ASL signal. + out_folder The output folder that is the reference to save all the output images in the script. + +Optional parameters: + mask Image mask defining the ROI where the calculations must be done. Any pixel value different from zero will be assumed as the ROI area. Outside the mask (value=0) will be + ignored. If not provided, the entire image space will be calculated. + --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers. If not passed, the default values will be used. + --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. If not passed, the default values will be used. + --te TE [TE ...] Time of Echos (TE), arranged in a sequence of float numbers. If not passed, the default values will be used. + --verbose Show more details thoughout the processing. + --file_fmt [FILE_FMT] + The file format that will be used to save the output images. It is not allowed image compression (ex: .gz, .zip, etc). Default is nii, but it can be choosen: mha, nrrd. +``` \ No newline at end of file diff --git a/docs/scripts/t2_script.md b/docs/scripts/t2_script.md deleted file mode 100644 index a2be406..0000000 --- a/docs/scripts/t2_script.md +++ /dev/null @@ -1,40 +0,0 @@ -# T2 Scalar Mapping Script - -This documentation provides an overview of the `t2_maps.py` script, which is used to calculate the T2 scalar maps from multi echo (Multi-TE) ASL (Arterial Spin Labeling) data. - -## Overview - -The `t2_maps.py` script processes ASL data to generate T2 scalar maps. The script takes ASL raw data, an M0 image, and optional parameters such as a mask image, PLD (Post Labeling Delay) values, and LD (Labeling Duration) values. The output includes the T2 maps for each PLD value. - -## Usage - -To run the script, use the following command: - -```bash -asltk_cbf pcasl m0 [mask] [out_folder] --pld PLD [PLD ...] --ld LD [LD ...] [--verbose] [--file_fmt [FILE_FMT]] [-h] [options] -``` - -## General description - -The full description of the script and more details about the necessary/optional parameters can be found by calling `--help` option: - -```bash -usage: T2 Scalar Mapping from ASL Multi-TE ASLData [-h] [--pld PLD [PLD ...]] [--ld LD [LD ...]] [--te TE [TE ...]] [--verbose] [--file_fmt [FILE_FMT]] pcasl m0 [mask] [out_folder] - -Python script to calculate the T2 scalar map from the ASL Multi-TE ASLData. - -Required parameters: - pcasl ASL raw data obtained from the MRI scanner. This must be the multi-TE ASL MRI acquisition protocol. - m0 M0 image reference used to calculate the ASL signal. - out_folder The output folder that is the reference to save all the output images in the script. - -Optional parameters: - mask Image mask defining the ROI where the calculations must be done. Any pixel value different from zero will be assumed as the ROI area. Outside the mask (value=0) will be - ignored. If not provided, the entire image space will be calculated. - --pld PLD [PLD ...] Posts Labeling Delay (PLD) trend, arranged in a sequence of float numbers. If not passed, the default values will be used. - --ld LD [LD ...] Labeling Duration trend (LD), arranged in a sequence of float numbers. If not passed, the default values will be used. - --te TE [TE ...] Time of Echos (TE), arranged in a sequence of float numbers. If not passed, the default values will be used. - --verbose Show more details thoughout the processing. - --file_fmt [FILE_FMT] - The file format that will be used to save the output images. It is not allowed image compression (ex: .gz, .zip, etc). Default is nii, but it can be choosen: mha, nrrd. -``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index d3750c4..eb7f20b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,16 +44,15 @@ nav: - 'getting_started.md' - 'examples/workflow_examples.md' - 'faq.md' - - 'api/data.md' - - 'api/reports.md' - 'api/asldata.md' - - 'api/reconstruction.md' - 'api/utils.md' - 'logging.md' - - 'scripts/cbf_script.md' - - 'scripts/multi_te_script.md' - - 'scripts/generate_sub_asl_image.md' - - 'scripts/t2_script.md' + - 'api/data.md' + - 'api/reports.md' + - 'api/models.md' + - 'api/reconstruction.md' + - 'api/registration.md' + - 'scripts/script_methods.md' - 'contribute.md' plugins: