T1S0_To_WF

This repository contains an example analysis pipeline and relevant scripts used in the study: "Mapping a Reproducible Water Fraction and T1 using MP2RAGE and Variable Flip Angle Quantitative MRI Protocols".

Overview

This pipeline estimates Water Fraction (WF) maps from quantitative MRI (qMRI) data.

The pipeline is based on quantitative T1 and S0/M0 maps, which can be estimated using one of two T1 mapping acquisition protocols:

• Variable Flip Angle (VFA)
• MP2RAGE

After the T1 and S0/M0 maps are generated, the pipeline estimates a Proton Density (PD) map and then calibrates the PD map to generate a Water Fraction (WF) map.

Pipeline steps

The pipeline includes the following main steps:

1. Estimation of T1 and S0/M0 maps from VFA or MP2RAGE data.
2. Estimation of a Proton Density (PD) map from the T1 and S0/M0 maps.
3. Calibration of the PD map to generate a Water Fraction (WF) map.

For VFA data, T1 and S0 estimation is performed using the mrQ package.

For MP2RAGE data, the pipeline uses the UNI, INV1 and INV2 images together with the MP2RAGE acquisition parameters. The UNI image is used to correct the INV1 and INV2 images before estimating T1, S0/M0 and R1 maps with an MP2RAGE dictionary matching approach.

Repository contents

The repository includes:

• T1S0_to_WF.m — an example script demonstrating the full pipeline from T1/S0 estimation to WF calculation.
• Scripts and tools for T1 and S0/M0 estimation from both VFA and MP2RAGE acquisitions.
• Functions for PD estimation.
• calibratePDmap.m — a function used to calibrate PD maps and generate WF maps.

Input requirements

Before running the PD and WF estimation steps, all required maps and masks must be aligned and defined in the same spatial space.

The required inputs include:

• T1 map
• S0/M0 map
• Binary brain mask
• Tissue segmentation file

The brain mask should contain:

• 0 outside the brain
• 1 inside the brain

The tissue segmentation file should be ordered as follows:

• WM = 1
• CSF = 2
• GM = 3
• CTX = 4

The CSF label is used during the WF calibration step.

Example data

The example data include:

• T1 and S0/M0 maps
• Brain mask
• Tissue segmentation
• Expected WF output
• CSF segmentation used for WF calibration

Dependencies

The scripts rely on functions and tools from the following repositories. Please make sure they are installed and added to your MATLAB path before running the pipeline:

• mrQ: https://github.com/mezera/mrQ/tree/master
• MP2RAGE-related-scripts: https://github.com/JosePMarques/MP2RAGE-related-scripts/tree/master
• Vistasoft: https://github.com/vistalab/vistasoft
• SPM8: https://github.com/spm/spm8

Citation

If you use this pipeline, please cite:

Mama, E., Shaharabani, R., Marques, J. P., & Mezer, A. A. (2026). Mapping a reproducible water fraction and T1 using MP2RAGE and variable flip angle quantitative MRI protocols. Magnetic Resonance in Medicine, 95(2), 1002–1016. https://doi.org/10.1002/mrm.70096