Created mkdocs for ASL_functionalities_test_report_Github.docx

.gitignore

@@ -0,0 +1,48 @@
+# Dependencies
+node_modules
+__pycache__
+venv
+.venv
+
+# Build files
+build
+site
+
+# Distribution files
+dist
+mkdocs_material.egg-info
+
+# Caches and logs
+*.cpuprofile
+*.log
+*.tsbuildinfo
+.cache
+.eslintcache
+__pycache__
+
+# Examples
+example
+example.zip
+
+# -----------------------------------------------------------------------------
+# General
+# -----------------------------------------------------------------------------
+
+# Never ignore .gitkeep files
+!**/.gitkeep
+
+# macOS internals
+.DS_Store
+
+# Temporary files
+TODO
+tmp
+
+# Temporary folder
+temp_dir/
+venv/
+
+# IDEs & Editors
+.idea
+*~
+.vscode

README.md

@@ -18,3 +18,5 @@ We received contributions from different groups, including：
 ## What we have presented here!
 The source code has been reviewed by our team and the functionalities are being separated and documented. However, one function  may have dependences on other functions within the repository. So, in this git repository, all functions will be preseneted within their original repo.
 
+## Documentation
+We have also hosted a documentation for [ASL_functionalities_test_report_Github.docx](ASL_functionalities_test_report_Github.docx) under the `docs` directory.

docs/additional_tools.md

@@ -0,0 +1,7 @@
+# Any additional functionalities with appropriate description
+
+### Function name: `ASL_calculateDiffMap`
+*   **Description:** Calculate difference map and write out the .img/.hdr files
+*   **Inputs:** `path_temp`, `asl_paras`
+*   **Outputs:** difference image and header files
+*   **Syntax:** `ASL_calculateDiffMap(path_temp,asl_paras)`

docs/assets/stylesheets/extra.css

@@ -0,0 +1,8 @@
+.md-grid {
+    max-width: 85vw;
+}
+
+.md-header__button.md-logo{
+    padding-bottom: 18px;
+    scale: 1.2;
+}

docs/brain_extraction.md

@@ -0,0 +1,29 @@
+# Brain extraction/skull stripping
+
+### Function name: `ASLtbx_createbrainmask.m`
+*   **Description:** use a single threshold to extract the brain, can manually change the threshold by the user
+*   **Inputs:** full path to the input image as `P='C:\Users\...\M02.nii';`
+*   **Outputs:** a brain mask file named 'brainmask.nii' with the same path as input
+*   **Syntax:** `maskimg=ASLtbx_createbrainmask(P)`
+
+!!! warning "Notes"
+    This file needs modification: It seems `spm_write_vol` cannot write the mask well when the mask is only 0 and 1. Added several lines for modification.
+
+---
+
+### Function name: `batch_create_mask.m`
+*   **Description:** Use a single threshold to extract the brain region, can manually change the threshold by the user
+*   **Inputs:** full path to the input image as `PF='C:\Users\...\M02.nii';`
+*   **Outputs:** a brain mask file named 'mask_perf_cbf.img' with the same path as input
+*   **Syntax:**
+
+!!! note "Notes"
+    This script seems to be one code from a whole pipeline. Therefore, there is dependency on passing the file path and subjects. But if we only took the core code for the test, this function is the same as the previous function . And need the same modification as in previous script.
+
+---
+
+### Function name: `ASL_getBrainMask.m`
+*   **Description:** motion correction
+*   **Inputs:** `imgtpm`, `imgfile`, `flag_addrealignmsk`
+*   **Outputs:** two masks are generated: `brnmsk_dspl` (datatype, logical), used for cbf map display; `brnmsk_clcu` (datatype, logical), used for glo_cbf calculation.
+*   **Syntax:** `[brnmsk_dspl, brnmsk_clcu] = ASL_getBrainMask(imgtpm,imgfile,flag_addrealignmsk)`

docs/cbf_quantification.md

@@ -0,0 +1,59 @@
+# Cerebral Blood Flow (CBF) quantification (please specify the model used)
+
+### Function name: `asl_perf_subtract.m` / `asl_perf_subtractMB.m`
+*   **Description:** For CASL and PASL, generate the difference and calculate the perfusion images from control/label and M0 images
+*   **Inputs:** Please see the description in the MATLAB code for detailed information.
+*   **Outputs:** Will output CBF maps into the path you defined
+*   **Syntax:** One example for PASL quantification. Both `P` and `M0img` are paths for control/label and M0 images: `FAIR='C:\Users\...\FAIR_CL.nii'`.
+    ```matlab
+    perfnum =  asl_perf_subtract(FAIR,1, 0, 0, [0 0 1 0 0 1 0 1 0 0], ...
+                                 0.5, 0, 0.9, 1, 2, 0.8, 45, 20, M0img);
+    perfnum =  asl_perf_subtractMB(FAIR,1, 0, 0, [0 0 1 0 0 1 0 1 0 0], ...
+                                 0.5, 0, 0.9, 1, 2, 0.8, 45, 20, M0img);
+    ```
+
+---
+
+### Function name: `ASLQuantificationPCASL.m`
+*   **Description:** For pCASL, calculate the perfusion maps with difference images, M0 and related parameters according to the 2015 ASL white paper
+*   **Inputs:** `data`, `M0` and `mask` should be the matrix for pCASL difference, proton density and brain mask images
+*   **Outputs:** Will generate CBF maps in MATLAB workspace
+*   **Syntax:** `[output, output_nantmean, NANCOUNTMASK] = ASLQuantificationPCASL(data, M0, 1.8, 1.8,1.6, 0.9, 0.6,'no','',14, 1, mask, 'yes', 'yesfigure');`
+
+!!! note "Notes"
+    This script needs small modification as shown in the script.
+
+---
+
+### Function name: `batch_calc_rcbf.m`
+*   **Description:** Calculate the normalized perfusion maps divided by the mean flow
+*   **Inputs:** Choose perfusion maps and mask in the pop out windows
+*   **Outputs:** Will generate normalized CBF maps in same path as original CBF maps
+*   **Syntax:** Just run the whole script, no function to call.
+
+!!! note "Notes"
+    This script seems to be one code from a whole pipeline. Therefore, there is dependency on passing the file path and subjects with spm batch system. But can use the core code lines as a separate function.
+
+---
+
+### Function name: `ASLDeltaM.m`
+*   **Description:** Calculate the difference images from the control and label images
+*   **Inputs:** `CTRL` and `TAG` are matrix values from the control and label images of ASL images, `method` can be any value as shown in the script
+*   **Outputs:** Output will be a matrix for difference images in MATLAB workspace
+*   **Syntax:** `Output=ASLDeltaM(CTRL,TAG,'PairWise');`
+
+---
+
+### Function name: `batch_perf_subtract.m`
+*   **Description:** batch file for the same function as `asl_perf_subtract.m`
+
+---
+
+### Function name: `ASL_calculateCBFmap.m`
+*   **Description:** This function obtains CBF value in the unit of ml/100g/min
+*   **Inputs:** `path_temp`: the paths of the ASL images, `asl_paras`: the parameters of the ASL images
+*   **Outputs:** a CBF map in `.img` format is created in the specified path
+*   **Syntax:** `ASL_calculateCBFmap(path_temp,asl_paras)`
+
+!!! note "Notes"
+    The images are in `.img` format, instead of dicom or nifti.

docs/co_registration.md

@@ -0,0 +1,23 @@
+# Co-registration of ASL images to high resolution T1-weighted, T2-weighted, and/or FLAIR images
+
+### Function name: `ASLtbx_spmcoreg.m`
+*   **Description:** using spm for registering source and allimgs to target.
+*   **Inputs:** `target`, `source`, `allimgs`
+*   **Outputs:** co-registered images
+*   **Syntax:** `[output]=ASLtbx_spmcoreg(target, source, allimgs)`
+
+---
+
+### Function name: `ASL_coreg`
+*   **Description:** coregister source to target and apply transform matrix to source and varargin
+*   **Inputs:** `target`, `source`, `varargin`
+*   **Outputs:** co-registered images and transformation matrix
+*   **Syntax:** `ASL_coreg(target,source,varargin)`
+
+---
+
+### Function name: `spm_reslice_yli`
+*   **Description:** similar to spm_reslice, does co-registration
+*   **Inputs:** `P` - matrix or cell array of filenames flags - a structure containing various options.
+*   **Outputs:** co-registered image files to the same subdirectory with a prefix.
+*   **Syntax:** `spm_reslice_yli(P,flags)`

docs/deep_learning.md

@@ -0,0 +1,55 @@
+# Deep learning-based method (Any application relevant to ASL)
+
+### File name: `test_ADNI_w_ft_0630.py`
+*   **Description:** Denoise ASL data in ADNI dataset with fine-tuning model presented in “Improving Sensitivity of Arterial Spin Labeling Perfusion MRI in Alzheimer's Disease Using Transfer Learning of Deep Learning-Based ASL Denoising”.
+*   **Inputs:**
+    To keep the script easy to run we just hard coded the input within the script. There are three inputs you will need to run the script.
+    1.  A “subjectlist_valid.txt” file with subject name.
+    2.  A directory containing all the subjects that need to be denoised. Each folder in this directory is one subject. In each subject folder, there are three subfolders i.e., “ASL”, “ANAT”, and “ANAT_DL_mask”. “ASL” folder contains ASL data in native space. “ANAT” folder contains the structural images for preprocessing the data e.g., registration or normalization. “ANAT_DL_mask” contains the gray matter, white matter, and the cerebrospinal fluid.
+    3.  A trained deep learning model.
+*   **Outputs:** Denoised ASL data in each subject’s “ASL” folder.
+*   **Syntax:** `python test_ADNI_w_ft_0630.py`
+
+---
+
+### File name: `test_ADNI_w_Direct_FT_0630.py`
+*   **Description:** Denoise ASL data in ADNI dataset with direct transfer learning model presented in “Improving Sensitivity of Arterial Spin Labeling Perfusion MRI in Alzheimer's Disease Using Transfer Learning of Deep Learning-Based ASL Denoising”. The main difference between this script and “test_ADNI_w_ft_0630.py” is that the models used for denoising are different.
+*   **Inputs:**
+    To keep the script easy to run we just hard coded the input within the script. There are three inputs you will need to run the script.
+    1.  A “subjectlist_valid.txt” file with subject name.
+    2.  A directory containing all the subjects that need to be denoised. Each folder in this directory is one subject. In each subject folder, there are three subfolders i.e., “ASL”, “ANAT”, and “ANAT_DL_mask”. “ASL” folder contains ASL data in native space. “ANAT” folder contains the structural images for preprocessing the data e.g., registration or normalization. “ANAT_DL_mask” contains the gray matter, white matter, and the cerebrospinal fluid.
+    3.  A trained deep learning model.
+*   **Outputs:** Denoised ASL data in each subject’s “ASL” folder.
+*   **Syntax:** `python test_ADNI_w_Direct_FT_0630.py`
+
+---
+
+### Function name: `read_subject_list`
+*   **Description:** This is a helper function used in “test_ADNI_w_Direct_FT_0630.py” and “test_ADNI_w_ft_0630.py”. The function is used to read the subject list in a “.txt” file.
+*   **Inputs:** A “.txt” file with each line denotes a subject name.
+*   **Outputs:** A list of all subjects.
+*   **Syntax:** `content = read_subject_list('subjectlist_valid.txt')`
+
+---
+
+### Function name: `get_subj_c123`
+*   **Description:** This is a helper function used in “test_ADNI_w_Direct_FT_0630.py” and “test_ADNI_w_ft_0630.py”. The function is used to get the gray matter, white matter, and the cerebrospinal fluid of each subject.
+*   **Inputs:** A subject name and a folder containing the subject name.
+*   **Outputs:** A mask with the gray matter, the white matter, and the cerebrospinal fluid.
+*   **Syntax:** `mask = get_subj_c123(subject_name, folder_name)`
+
+---
+
+### Function name: `parse_args`
+*   **Description:** Parser for command-line options, arguments and sub-commands. The function is used to set up the deep learning model’s folder and name.
+*   **Inputs:** A directory of the deep learning model and the model’s file name.
+*   **Outputs:** An instance of the parser.
+*   **Syntax:** `args = parse_args()`
+
+---
+
+### Function name: `predict_nii_w_masks_rbk`
+*   **Description:** The function is used to denoise all the subjects’ ASL data within a folder by using a deep learning model.
+*   **Inputs:** A deep learning model, the root folder of all subjects, and the name of the denoised results.
+*   **Outputs:** Denoised results.
+*   **Syntax:** `predict_nii_w_masks_rbk(model,root_folder,save_name)`

docs/denoising.md

@@ -0,0 +1,31 @@
+# Outlier removal or Denoising
+
+### Function name: `ASLtbx_aoc`
+*   **Description:** It adaptively removes CBF volumes from the CBF time series and averages the remaining volume to obtain the meanCBF map. The removal is based on estimated motion, and correlation between individual CBF volumes and mean CBF map. Algorithm based on https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3777751/
+*   **Inputs:** CBF time series and optionally: text file with the estimated motion parameters realigning the raw ASL time series, brain mask in the ASL space, an algorithm specific threshold parameter (default 0.17) and number of iterations (default 2)
+*   **Outputs:** Outlier volume numbers. Also generates the estimated CBF map obtained after outlier removal.
+*   **Syntax:**
+    ```
+    ASLtbx_aoc(cbfimgs, motionfile, maskimg, th, iter)
+    ```
+    See the help section of the code for details.
+    Use the `batch_outlier_clean` to call the function
+
+---
+
+### Function name: `ASLtbx_aocSL`
+*   **Description:** It adaptively removes slices from CBF volumes in the CBF time series and averages the remaining slices and volumes to obtain the mean CBF map. Algorithm is based on https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3777751/
+*   **Inputs:** CBF time series, `c1img` and `c2img` (GM and WM tissue probability maps obtained from SPM segmentation of high resolution T1 image, coregistered and downsampled to the ASL space), `masking` (brain mask in the ASL space), `th` (a threshold parameter, default =0.17, better to not change), `motionfile` (test file with the estimated motion parameters realigning the raw ASL time series)
+*   **Outputs:** `oidx`: identified outliers. Also generates the estimated CBF map obtained after outlier removal.
+*   **Syntax:** `ASLtbx_aocSL(cbfimgs, c1img, c2img, maskimg, th, motionfile)`
+
+---
+
+### Function name: `batch_SCORE_clean.m`
+*   **Description:** Calculate
+*   **Inputs:** The path of perfusion maps, GM, WM and CSF Probability maps.
+*   **Outputs:** Will
+*   **Syntax:** Just run the whole script, no function to call. But does need to include the `SCORE_denoising.m` function.
+
+!!! note "Notes"
+    This script seems to be one code from a whole pipeline. Therefore, there is dependency on passing the file path and subjects with spm batch system. But can use the core code lines as a separate function.

docs/index.md

@@ -0,0 +1,5 @@
+# Task Force 2.2: ASL Functionalities-Test Report
+
+Welcome to the documentation for the ASL Toolbox.  
+
+This documentation is generated from [ASL_functionalities_test_report_Github.docx](https://github.com/OSIPI/TF2.2_OSIPI-ASL-toolbox/blob/main/ASL_functionalities_test_report_Github.docx)

docs/motion_correction.md

@@ -0,0 +1,15 @@
+# Motion Correction
+
+### Function name: `batch_realign.m`
+*   **Description:** realigns raw EPI images using SPM realignment tools
+*   **Inputs:** 4D NIfTI
+*   **Outputs:** This script seems to be one code from a whole pipeline. Therefore, there is dependency on passing the file path and subjects.
+*   **Syntax:** DNA
+
+---
+
+### Function name: `ASL_realign.m`
+*   **Description:** motion correction
+*   **Inputs:** `path_temp`: the path of the ASL image, `name_asl`:name of the ASL image
+*   **Outputs:** Generates realigned images from the time series
+*   **Syntax:** `P = ASL_realign(path_temp, name_asl)`

docs/normalization.md

@@ -0,0 +1,21 @@
+# Normalization to common template (e.g., MNI space)
+
+### Function name: `ASLtbx_spm12normest`
+*   **Description:** Normalize the structural image to the standard template (TPM.nii) using spm12 functions.
+*   **Inputs:** `strucimg` should be paths of the target structural images
+*   **Outputs:** normalized structural images in the assigned folder
+*   **Syntax:** `ASLtbx_spm12normest(strucimg)`
+
+!!! note "Notes"
+    The whole script runs fine, however, the normalized image is black and white.
+
+---
+
+### Function name: `ASLtbx_spm12normest`
+*   **Description:** Normalize the structural image to the standard template (TPM.nii) using spm12 functions.
+*   **Inputs:** `strucimg` should be paths of the target structural images
+*   **Outputs:** normalized structural images in the assigned folder
+*   **Syntax:** `ASLtbx_spm12normest(strucimg)`
+
+!!! note "Notes"
+    The whole script runs fine, however, the normalized image is black and white.

docs/roi_creation.md

@@ -0,0 +1,7 @@
+# Create ROIs
+
+### Function name: `roipoly.m`
+*   **Description:** selects a polygonal region of interest within an image, this function should be similar to MATLAB’s built-in function “roipoly”.
+*   **Inputs:** A 2D image file name
+*   **Outputs:** returns a binary image that can be used as a mask for masked filtering, returns the polygon coordinates
+*   **Syntax:** `[BW, xi, yi] = roipoly(‘image.jpeg’);`

docs/segmentation.md

@@ -0,0 +1,7 @@
+# Segmentation of high-resolution images (Grey Matter and White Matter)
+
+### Function name: `ASLtbx_spmnsegment`
+*   **Description:** Probabilistically segment the high resolution T1 images
+*   **Inputs:** High resolution T1 image
+*   **Outputs:** Probabilistic segmentations of GM, WM and CSF (file names starting with `c1`, `c2` and `c3`)
+*   **Syntax:** `ASLtbx_spmnsegment(full_path_of_T1_Image)`

docs/smoothing.md

@@ -0,0 +1,15 @@
+# Smoothing
+
+### Function name: `ASLtbx_smoothing`
+*   **Description:** smoothes an image, returns the smoothed image
+*   **Inputs:** image path, and a kernel size
+*   **Outputs:** smoothed image, written as a different file
+*   **Syntax:** `ASLtbx_smoothing(‘image.nii’, 2)`
+
+---
+
+### Function name: `batch_smooth_wconfile` and `batch_smooth`
+*   **Description:** A code from pipeline. Needs dependency from the spm batch. It uses spm_smooth to smooth a number of files.
+*   **Inputs:** path of the images
+*   **Outputs:** smoothed images
+*   **Syntax:** As this is part of the pipeline, just run the script, no function to call