Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tissue fraction modulated ICVF and OD maps #218

Open
wants to merge 16 commits into
base: main
Choose a base branch
from

Conversation

araikes
Copy link
Collaborator

@araikes araikes commented Mar 20, 2025

Changes proposed in this pull request

Parker et al (https://doi.org/10.1016/j.neuroimage.2021.118749) proposed a tissue fraction modulation approach for NODDI metrics to reduce bias in ROI-associated mean computations. Modulation is just {NDI,OD} * (1 - ISOVF). AMICO has these as output options through a global flag, along with the (N)RMSE maps from the fitting. This PR enables outputting of these 4 maps when running NODDI. Addresses #217.

Includes citations for Parker et al and fixes some typos in the reports (generally) and in the AMICO specific reports as well.

Outputs from a test run:

├── ses-01
│   ├── dwi
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_config.pickle.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ICVF_dwimap.json
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ICVF_dwimap.nii.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ICVFmodulated_dwimap.json
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ICVFmodulated_dwimap.nii.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ISOVF_dwimap.json
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ISOVF_dwimap.nii.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-OD_dwimap.json
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-OD_dwimap.nii.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ODmodulated_dwimap.json
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-ODmodulated_dwimap.nii.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-direction_dwi.fib.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-direction_dwimap.json
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-direction_dwimap.nii.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-nrmse_dwimap.json
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-nrmse_dwimap.nii.gz
│   │   ├── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-rmse_dwimap.json
│   │   └── sub-002_ses-01_dir-AP_space-ACPC_model-noddi_param-rmse_dwimap.nii.gz
│   ├── figures
│   │   ├── sub-002_ses-01_desc-about_T1w.html
│   │   ├── sub-002_ses-01_desc-summary_T1w.html
│   │   └── sub-002_ses-01_dir-AP_space-ACPC_desc-NODDI_peaks.png
│   └── sub-002_ses-01.html
├── ses-02
│   ├── dwi
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_config.pickle.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ICVF_dwimap.json
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ICVF_dwimap.nii.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ICVFmodulated_dwimap.json
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ICVFmodulated_dwimap.nii.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ISOVF_dwimap.json
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ISOVF_dwimap.nii.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-OD_dwimap.json
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-OD_dwimap.nii.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ODmodulated_dwimap.json
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-ODmodulated_dwimap.nii.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-direction_dwi.fib.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-direction_dwimap.json
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-direction_dwimap.nii.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-nrmse_dwimap.json
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-nrmse_dwimap.nii.gz
│   │   ├── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-rmse_dwimap.json
│   │   └── sub-002_ses-02_dir-AP_space-ACPC_model-noddi_param-rmse_dwimap.nii.gz
│   ├── figures
│   │   ├── sub-002_ses-02_desc-about_T1w.html
│   │   ├── sub-002_ses-02_desc-summary_T1w.html
│   │   └── sub-002_ses-02_dir-AP_space-ACPC_desc-NODDI_peaks.png
│   └── sub-002_ses-02.html
└── sub-002.html

Top row: Unmodulated ICVF (left) and OD (right)
Bottom row: Modulated ICVF (left) and OD (right)

image

Documentation that should be reviewed

Need to check docs. I tried to edit them but I'm not sure if I was successful. Probably also needs to be an explanation somewhere that the modulated maps should not, themselves be directly analyzed (per Parker et al) but rather the mean computed per region on them and then re-divided by the mean tissue fraction to get back to the original scale. Can do this when I know whether any of the documentation editing was successful.

araikes added 11 commits March 20, 2025 09:54
- AMICO produces ICVF and OD maps modulated by the non isotropic tissue fraction. This makes these available.

- AMICO also produces (N)RMSE maps of the observed vs predicted signal. Saving these enables QC and other assessments of parameter selection.
Change naming structure so that "desc" isn't used.
@araikes
Copy link
Collaborator Author

araikes commented Mar 20, 2025

It would probably be helpful to also have an output for the tissue fraction, but AMICO doesn't save that and I wasn't sure how to accomplish.

Internally for AMICO, tf = 1 - fwf but that's not retained in its outputs.

Left: ISOVF; Right: TF

image

@tsalo
Copy link
Member

tsalo commented Mar 25, 2025

It looks like the only remaining change is to the list of output files that is checked agaisnt in the Recon_AMICO test. I also noticed that you capitalized some of the parameters in the filenames, which is a breaking change.

@tsalo tsalo added the enhancement New feature or request label Mar 25, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants