PyDesigner v1.0: A Pythonic Implementation of the DESIGNER Pipeline for Diffusion Magnetic Resonance Imaging

The PyDesigner software applies multiple image correction steps to raw diffusion data and generates outputs used to improve accuracy over the raw files when conducting analysis. Each step available in the pipeline has been previously validated through peer-reviewed publications5,6,7,8,9,10,11 as discussed in the introduction. The outputs from the software can be used in analyses such as tractography profiles, connectivity matrices, voxel-wise analyses, ROI analyses, fODF analyses, TBSS, and fixel-based analyses. The software website23 lists all output files generated during the preprocessing pipeline. After each prompt is run, the console will output a description of all completed processes. There are 3 types of output files: processing files, metrics, and quality control. The output directory structure is shown in Figure 1. These files are available when using standard preprocessing (refer to section 7 of the protocol). If the user requires more advanced usage (refer to section 8 of the protocol), the output files available will be dependent on which processes were completed. Figure 1: Visual representation of the PyDesigner pipeline. Preprocessing begins by providing an input 4D DWI to PyDesigner (top left), which then undergoes MP-PCA denoising to yield a denoised 4D DWI and a 3D noise map. The denoised 4D DWI then undergoes Gibbs ringing correction, Rician bias correction, TOPUP, eddy current correction, and outlier correction. A brain mask is then computed for subsequent steps, outlier detection, and tensor fitting to speed up computations by performing them within the brain mask only. Outputs can be found in subdirectories in the main subject processing folder – intermediate_nifti, metrics, and metrics_qc. Note that the screenshots of PyDesigner outputs are not meant to be an exhaustive list of all possible outputs but rather to provide a schematic visual example of what users can expect. Outputs, both final outputs and intermediate files, will vary based on user input data and processing flags employed. Please click here to view a larger version of this figure. Processing Processing files are used during the PyDesigner pipeline and are stored in the root output directory. For each preprocessing step, intermediate DWI files are saved in the output folder "intermediate_nifti" as shown in Figure 1. These files should be referenced when addressing any issues with processing or outputs to evaluate each step of the pipeline separately. Figure 2: Optimal and suboptimal intermediate DWI NifTI files. The figure shows the intermediate NIfTI file for each image correction step of the PyDesigner pipeline. The top row is an example of optimal intermediate file outputs using data from a healthy adult brain, the middle row is an example of optimal intermediate file outputs using data from a pathological brain (meningioma), and the bottom row displays suboptimal intermediate file outputs using data from a healthy adult brain with a susceptibility artifact unrelated to brain structure or health. Please click here to view a larger version of this figure. Metrics This folder contains all the parametric maps that PyDesigner calculates (see Figure 1). This includes parametric maps for DTI/DKI, fiber ball imaging (FBI)/ fiber ball white matter (FBWM), and white matter tract integrity (WMTI) metrics (Table 1)16. Table 1: Expected range of values for DTI/DKI and FBI/FBWM metrics. The table includes a list of robust DTI, DKI, FBI, and FBWM metrics generated by PyDesigner and their expected value ranges. The required sequences and b-values(s/mm2) to derive each metric are also listed. The DTI metrics listed are FA, MD, AD, and RD. The DKI metrics listed are MK, AK, RK, and KFA. The FBI metric listed is FAA. The FBWM metrics listed are AWF, DA, DE_AX, DE_RAD, and FAE. Users can conduct visual and value quality control (QC) of the mean diffusivity (MD), fractional anisotropy (FA), and mean kurtosis (MK) metrics to identify suboptimal results. If these metrics are suboptimal by the standards described below, users should look at each intermediate file described in Figure 2 to determine which preprocessing step was unsuccessful. Visual QC is used to identify suboptimal results (e.g., tensor fitting issues, and artifacts). We recommend using ImageJ for visual QC to ensure no manipulation is done to the image via software defaults. The top row of Figure 3 shows typical MD, FA, and MK metric maps using a biologically plausible threshold of 0-3 µm2/ms, 0-1 µm2/ms, and 0-2 µm2/ms, respectively (Figure 3 [Top row]). The MD map should have the highest values in the ventricles and high values in cortical grey matter (Figure 3A [Top row]). The FA map should have apparent white matter tracts that are clear throughout the brain (Figure 3B [Top row]). The MK map should have high values in WM and lower values in the grey matter and CSF (Figure 3C [Top row]). Figure 3D [Top row] is an example of a metric map with tensor fitting issues, which results in clusters of zero-value voxels. If any issues occur, review the log_command.json file to find any preprocessing errors. Review the intermediate files to determine the specific error. For help troubleshooting, submit a request on the PyDesigner GitHub page. Value quality control is used to identify if the voxels of a given metric map are relatively uniform between subjects for each dataset. The expected value range for each map and dataset is dependent on the data and the PyDesigner parameters. In our test dataset, we had consistent peaks in the 8000 to 10,000, 2500 to 4000, and 5000 to 13,000 ranges for MD, FA, and MK, respectively, using FSLeyes default histogram binning. The bottom row of Figure 3 provides examples of histogram variability. Table 1 contains the expected x-axis values for these metrics. Higher or lower voxels are characteristic of the dataset or indicate an artifact or preprocessing issue (Figure 3D [Bottom row]). Figure 3: Example metric maps and histograms from PyDesigner with optimal and suboptimal results. The top row shows examples of single-subject MD, FA, and MK maps used for visual QC. The bottom row shows multi-subject histograms used for value QC. (A-C) Typical examples of metric maps and histograms that pass visual and value quality control. Each blue line on the histograms for each metric type represents an individual dataset. Note that each dataset follows a similar curve and falls within a similar range. (D) An example of a metric map that does not pass visual or value quality control. Note how the red line on the histogram shows a curve that differs from that of A-C. The zero voxels circled on this metric map are due to tensor fitting issues during preprocessing (Panel D, top row). This histogram is an example of generally higher or lower voxels in a dataset than expected (Panel D, bottom row). Please click here to view a larger version of this figure. Quality control Once PyDesigner has processed the data, the metrics_qc folder (see Figure 1) should be used to identify suboptimal datasets. For each dataset, PyDesigner outputs three plots used for quality control. Figure 4: PyDesigner-generated QC histogramsfor optimal and suboptimal datasets. SNR, intervolume head motion, and outlier histograms generated by PyDesigner. Both rows represent data from a healthy adult brain. The top row is an example of quality control histograms for an optimal dataset. The bottom row shows quality control outputs of a suboptimal dataset with a susceptibility artifact unrelated to brain structure or health. Please note that the text size of the labels in the default outputs from PyDesigner is smaller than they will appear in this figure. We have increased the text size in this figure for readability. Please click here to view a larger version of this figure. The head_motion graphs in Figure 4 show head displacement relative to the first volume and the previous volume. As seen in Figure 4 (panel 1), head displacement is typically small and PyDesigner adjusts for these motion artifacts in the standard processing pipeline using the FSL program Eddy along with TOPUP for motion and eddy current motion correction9. For suboptimal datasets, the head_motion graph may appear empty, as shown in Figure 4 (panel 4). This indicates that eddy current motion correction was unsuccessful therefore the PyDesigner was unable to output a graph. The Eddy current correction log files can be found in the eddy subfolder within the metrics_qc folder (see Figure 1). The signal-to-noise ratio (SNR) graph displays 3 plots. Each plot is for a different b-value and shows both the preprocessed and raw data. For an optimal dataset, the raw data SNR peak should be ≥5 (Figure 4 [panel 2]). Suboptimal datasets will have a raw data SNR peak of ≤3 (Figure 4 [panel 5]). Ideally, users should see that the SNR peak for all b-values increases slightly but not dramatically. The outlier plot is found in the fitting folder within metrics_qc and shows the percentage of outliers in the dataset (Figure 4 [panel 3 and 6]). A good dataset should have a low percentage of outliers, typically less than 5% (Figure 4 [panel 3]). A suboptimal dataset will have a large percentage of outliers, as shown in Figure 4 (panel 6). Example dataset results Once PyDesigner has finished processing the example dataset, all outputs should be contained within the "PyDesigner_Outputs" folder. These outputs can be compared with those found in the "derivatives" folder packaged with the example dataset downloaded from OpenNeuro (processed on MacOS 12.4). If the software runs correctly, the file structure of "PyDesigner_Outputs" and "derivatives" will be exactly the same. Likewise, the SNR, head motion, and outlier plots found in the subfolder "metrics_qc" should match those in Figure 5A. Metric maps (found in the subfolder "metrics") can be compared via imaging software such as FSLeyes, MRIcron, ImageJ, etc. Histograms of FA, MD, and MK values from preprocessed/metrics can be seen in Figure 5B. Note that all metric histograms shown in Figure 5B are scaled based on suggested metric value scales in Table 1. Figure 5: Example Data Metric and Metric QC Histograms. (A) SNR, intervolume head motion, and outlier histograms generated by PyDesigner for the example data downloaded from OpenNeuro. Note that text size has been increased on the plots in this figure for readability. (B) Single subject metric maps histograms of voxel value counts for FA, MD, and MK for the same dataset, visualized through FSLeyes v6.0. Please click here to view a larger version of this figure. Figure 6: DTI and DKI maps derived from PyDesigner, DESIGNER, DKE, and DIPY. Tensor fitting was performed with Kapp > 0 constraint in PyDesigner, DESIGNER5, and Diffusional Kurtosis Estimator (DKE)27, whereas unconstrained fitting was used in Diffusion Imaging in Python (DIPY)28 due to software limitations. The units for MD are squared micrometers per millisecond (µm2/ms), while the other metrics are dimensionless. Dropouts due to a generic problem from Gibbs ringing correction can be seen in MK maps produced by DESIGNER, DKE, and DIPY. This figure has been reproduced with permission from Dhiman et al.29. Please click here to view a larger version of this figure. Figure 7: Comparison of FA, MD, and MK across pipelines. The distribution of computed values for FA, MD, and MK from PyDesigner, DESIGNER5, DKE27, and DIPY28 in CSF-excluded brains are similar across most voxels. Metric map calculation across methods is comparable. This figure has been reproduced with permission from Dhiman et al.29. Please click here to view a larger version of this figure.