This repository contains code for quantifying and removing scanner-induced noise from fMRI data using the BrainDancer Dynamic Phantom. Details about the dynamic phantom and analysis algorithms are provided in the accompanying manuscript:https://www.sciencedirect.com/science/article/pii/S1053811920310697?dgcid=rss_sd_all
Author: Rajat Kumar, [email protected]; [email protected]
- Download/Clone the repository.
- Install Conda: https://docs.conda.io/projects/conda/en/latest/user-guide/install/.
- Install the Environment: conda env create -f environment.yml -n BrainDancer
Before any data-analysis, the phantom data should be corrected for spatial intensity non-uniformity (INU). We recommend using the N4ITK algorithm implemented in ANTs Toolbox. Download and installation is available from: http://stnava.github.io/ANTs/. B-Spline fitting and convergence parameter should be chosen carefully and is highly dependent on main MR field strength and acquisition protocol used.
To denoise fMRI data from scanner-induced variance, follow the steps below (Jupyter Notebooks are preferred for the analysis):
- Run Example_TimeSeriesExtraction.ipynb: This file provides a skeleton code for generating the ground-truth data and extracts the voxel time-series from fMRI output. Needs phantom-log file obtained from your BrainDancer device, slice-acquistion order of your acquistion protocol in csv format, and INU-corrected fMRI measurement in nifti format.
Visual inspection and decision making when running Example_TimeSeriesExtraction.ipynb
After slice selection, if you observe no contours for a slice - the default threshold being used is incorrect for your dataset. The program will prompt you to enter a new threshold.
-
Run Example_TrainingCNN.ipynb: This implements training of CNN for learning noise characteristics. It requires three nifti files that were generated in step 1 output (measured fMRI data, ground-truth data and masks).
-
Run Example_Denoising.ipynb: This implements data denoising using the trained CNN. It requires data to be denoised (phantom or human) as numpy array and the .h5 trained weights file from step 2.
-
Run Example_TimeSeriesExtraction.ipynb: This file provides a skeleton code for generating the ground-truth data and extracts the voxel time-series from fMRI output. Needs phantom-log file obtained from your BrainDancer device, slice-acquistion order of your acquistion protocol in csv format, and INU-corrected fMRI measurement in nifti format.
-
Run Example_DataQualityAssesment.ipynb: This file provides code for calculating data quality metrics namely – Standardized SNR (ST-SNR), Dynamic Fidelity and Scanner Instability, as defined in Kumar et. al.. It requires three nifti files that were generated in step 1 output (measured fMRI data, ground-truth data and masks).
- Analysis routines for static phantoms - Temporal Signal-to-Fluctuation-Noise Ratio (SFNR), Weisskoff plot "Radius of Decorrelation".
- Analysis routines for instability measurement using the FBIRN phantom, with two flip angle measurement method.
- Colored noise based motion sequence generator for the phantom.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.