Data processing

Below we summarize the procedures and parameters used to process the BIDS input data described here through ABCD-BIDS and QSIPrep pipelines to produce processed derivative. Please see Feczko et al. (2021) for details.

Processing & Analytic Standards

Pipelines used for ABCC processing follow guidelines based on principles and utilities developed by NMIND aimed at promoting reproducibility and standardization in neuroimaging tools (Kiar et al., 2023). Among these is the NMIND Coding Standards Checklist, a comprehensive framework for evaluating the quality of a tool’s documentation, infrastructure, and testing capabilities against open, community-developed, scientific software-development standards. Badge ratings for all tools that complete this review process can be viewed at Evaluated Tools. Software utilized for the ABCC release must undergo NMIND peer review and be published with a DOI. At a minimum, tools must meet the standards equivalent to the Bronze badge in the rating system. Please see the NMIND ratings for ABCD-BIDS and QSIPrep pipelines as follows:

ABCD-BIDS Pipeline

The ABCD-BIDS pipeline is available on GitHub, OSF, and DockerHub at the time of this release as the abcd-hcp-pipeline. It is a BIDS App which takes BIDS input data and uses the methods from both the Human Connectome Project’s minimal preprocessing pipeline (Glasser et al., 2013) and the DCAN Labs resting state fMRI analysis tools to output preprocessed MRI data in both volume and surface spaces. Please see the ABCD-BIDS pipeline webpage for a full overview of this pipeline.

ABCC data was processed through the ABCD-BIDS pipeline in two different ways with the following command and parameters.

For the structural pipeline up to the post-Freesurfer stage:

singularity run --cleanenv \
  -B ${data_dir}/bids_dataset:/bids_dir \
  -B ${data_dir}/derivatives/abcd-hcp-pipeline_v0.1.4:/output_dir \
  -B ${run_dir}/license.txt:/opt/freesurfer/license.txt \
  -B ${run_dir}/ABCD_BIDS_cleaning.json:/ABCD_BIDS_cleaning.json \
  /ABCD-BIDS/abcd-hcp-pipeline_R2019a-test_07222024a.sif \
  /bids_dir /output_dir \
  --freesurfer-license /opt/freesurfer/license.txt \
  --participant-label ${subject_id} \
  --stages "PreFreeSurfer:PostFreeSurfer" \
  --custom-clean /ABCD_BIDS_cleaning.json \
  --ignore func \
  --ncpus 8

For the full pipeline (including all stages):

env -i ${singualrity} run \
  -B ${data_dir}/bids_dataset:/bids_dir \
  -B ${data_dir}/derivatives/abcd-hcp-pipeline_v0.1.4:/output_dir \
  -B ${run_dir}/license.txt:/opt/freesurfer/license.txt \
  -B ${run_dir}/ABCD_BIDS_cleaning.json:/ABCD_BIDS_cleaning.json \
  /ABCD-BIDS/abcd-hcp-pipeline_R2019a-test_07222024a.sif \
  /bids_dir /output_dir \
  --freesurfer-license /opt/freesurfer/license.txt \
  --participant-label ${subject_id} \
  --stages "PreFreeSurfer:CustomClean" \
  --bandstop 18.582 25.726 \
  --custom-clean /ABCD_BIDS_cleaning.json \
  --ncpus 8

Additional Details

Distortion Correction
A single optimal pair of positive (posterior to anterior) and negative (anterior to posterior) spin echo field maps are utilized to correct for distortions in the phase encoding direction of ALL anatomical and functional acquisitions using FSL’s topup (see section on BIDS Conversion for details on fmap pair selection)

Respiratory Motion Filter
In working with ABCD data, we have found that a respiratory artifact is produced within multi-band data (Fair et al., 2020). While this artifact occurs outside the brain, it can affect estimates of frame alignment, leading to inappropriate motion censoring. By filtering the frequencies (18.582 to 25.726 breaths per minute) of the respiratory signal from the motion realignment data (during the DCANBoldProc stage), our respiratory motion filter produces better estimates of FD.

Resolved ABCD-BIDS Pipeline Processing Issues

The following issues occurred while processing the ABCD MRI data through the ABCD-BIDS pipeline. They have been resolved for the current release data, but are included here for additional guidance for those who may wish to process the data themselves:

Fieldmap Dimension Mismatch in TopupPreprocessingAll.sh (GE Only)
Description: The spin echo fieldmap has different dimensions than the scout image in a portion of GE sessions, causing a preprocessing error.
Solution: Resize the fieldmaps (fmaps) using the bold file as the reference size.
Steps to Resolve:
Run the following command: flirt -in "$fmap_file" -ref "$func_run" -out "$output_file" -applyisoxfm 2.4
Incorrect Fieldmap Assignment in FMRIVolume Step
Description: The wrong fieldmap is being assigned, leading to processing errors during the FMRIVolume step.
Solution: Update the fieldmap JSON files to include the correct runs that were missed during previous steps.
FNIRT Read Error - Insufficient Volumes
Description: FNIRT requires at least three volumes to process. This error occurs when functional data is incomplete or corrupted.
Solution: Skip the functional pipeline and run only the anatomical pipeline for affected cases.
Issue: Index Error in anat_only Cases
Description: In anat_only cases, fmap JSON files interfere with the pipeline, causing index errors.
Solution: Sync only the anat folder for such cases temporarily.

Software

QSIPrep

QSIPrep configures pipelines for processing diffusion-weighted MRI (dMRI or DWI) data. For more information see the QSIPrep documentation. This is the command used to run ABCC subjects through QSIPrep preprocessing:

singularity run --cleanenv -B ${PWD} \
  pennlinc-containers/.datalad/environments/qsiprep-0-16-1/image \
  inputs/data \
  prep \
  participant \
  -w ${PWD}/.git/wkdir \
  --n_cpus 8 \
  --stop-on-first-crash \
  --fs-license-file code/license.txt \
  --skip-bids-validation \
  --participant-label "$subid" \
  --unringing-method mrdegibbs \
  --output-resolution 1.7 \
  --eddy-config code/eddy_params.json \
  --notrack

Contents of code/eddy_params.json

{
  "flm": "linear",
  "slm": "linear",
  "fep": false,
  "interp": "spline",
  "nvoxhp": 1000,
  "fudge_factor": 10,
  "dont_sep_offs_move": false,
  "dont_peas": false,
  "niter": 5,
  "method": "jac",
  "repol": true,
  "num_threads": 1,
  "is_shelled": true,
  "use_cuda": false,
  "cnr_maps": true,
  "residuals": false,
  "output_type": "NIFTI_GZ",
  "args": ""
}

QSIRecon

QSIRecon configures pipelines for reconstructing and modeling preprocessed diffusion-weighted MRI data. For more information see the QSIRecon documentation. The following command was used to run ABCC subjects through QSIRecon reconstruction

singularity run \
    --containall \
    -B ${PWD} \
    -B "${TEMPLATEFLOW_HOME}:/templateflow_home" \
    --env "TEMPLATEFLOW_HOME=/templateflow_home" \
    ${SIMG} \
    ${PWD}/qsiprep \
    ${PWD}/results \
    participant \
    -w ${PWD}/wkdir \
    --report-output-level session \
    --stop-on-first-crash \
    --fs-license-file ${PWD}/license.txt \
    --participant-label "$subid" \
    --recon-spec ${PWD}/ABCD_Recon.yml \
    --notrack -v -v \
    --nthreads ${NSLOTS} \
    --omp-nthreads ${NSLOTS}

Contents of ABCD_Recon.yml

name: ABCD_Recon
nodes:
# NODDI with WM parameters
-   action: fit_noddi
    input: qsirecon
    name: fit_noddi_wm
    parameters:
        dIso: 0.003
        dPar: 0.0017
        isExvivo: false
    qsirecon_suffix: wmNODDI
    software: AMICO
# NODDI with GM parameters
-   action: fit_noddi
    input: qsirecon
    name: fit_noddi_gm
    parameters:
        dIso: 0.003
        dPar: 0.0011
        isExvivo: false
    qsirecon_suffix: gmNODDI
    software: AMICO
# DIPY diffusion kurtosis modeling
-   action: DKI_reconstruction
    input: qsirecon
    name: dipy_dki
    parameters:
        write_fibgz: false
        write_mif: false
    qsirecon_suffix: DIPYDKI
    software: Dipy
# TORTOISE MAPMRI w/ small b-val tensor fit
-   action: estimate
    input: qsirecon
    name: tortoise_dtmapmri
    parameters:
        big_delta: null
        estimate_mapmri:
            map_order: 4
        estimate_tensor:
            bval_cutoff: 1200
            write_cs: true
        estimate_tensor_separately: true
        small_delta: null
    qsirecon_suffix: TORTOISE_model-MAPMRI
    software: TORTOISE
# Fit the GQI model to the data
-   action: reconstruction
    input: qsirecon
    name: dsistudio_gqi
    parameters:
        method: gqi
    qsirecon_suffix: DSIStudioGQI
    software: DSI Studio
# Get 3D images of DSI Studio's scalar maps
-   action: export
    input: dsistudio_gqi
    name: gqi_scalars
    qsirecon_suffix: DSIStudioGQI
    software: DSI Studio
 # Perform the registration using the GQI-based QA+ISO
-   action: autotrack_registration
    input: dsistudio_gqi
    name: autotrack_gqi_registration
    # qsirecon_suffix: Don't include here - the map.gz is saved in autotrack
    software: DSI Studio
# Do MSMT on all shells
-   action: csd
    software: MRTrix3
    input: qsirecon
    name: msmt_csd
    parameters:
        fod:
            algorithm: msmt_csd
            max_sh:
            - 8
            - 8
            - 8
        mtnormalize: true
        response:
            algorithm: dhollander
    qsirecon_suffix: MSMTAutoTrack
# Merge the FOD fib file and the map file
-   action: fod_fib_merge
    name: create_fod_fib_msmt
    # to include the fib file AND the map file
    input: autotrack_gqi_registration
    csd_input: msmt_csd
    # outputs include the FOD fib file and the map file is passed through
    qsirecon_suffix: MSMTAutoTrack
    parameters:
        model: msmt
# Execute AutoTrack
-   action: autotrack
    input: create_fod_fib_msmt
    name: autotrack_fod_msmt
    parameters:
        tolerance: 22,26,30
        track_id: Association,Projection,Commissure,Cerebellum
        track_voxel_ratio: 2.0
        yield_rate: 1.0e-06
        model: msmt
    qsirecon_suffix: MSMTAutoTrack
    software: DSI Studio
# Map scalars to bundles
-   action: bundle_map
    input: autotrack_fod_msmt
    name: bundle_means
    scalars_from:
    - fit_noddi_wm
    - dipy_dki
    - tortoise_dtmapmri
    - gqi_scalars
    software: qsirecon
# Map scalars to MNI
-   action: template_map
    input: qsirecon
    name: template_map
    parameters:
        interpolation: NearestNeighbor
    scalars_from:
    - fit_noddi_wm
    - fit_noddi_gm
    - dipy_dki
    - tortoise_dtmapmri
    - gqi_scalars
    software: qsirecon

References

Fair, D. A., Miranda-Dominguez, O., Snyder, A. Z., Perrone, A., Earl, E. A., Van, A. N., Koller, J. M., Feczko, E., Tisdall, M. D., Van Der Kouwe, A., Klein, R. L., Mirro, A. E., Hampton, J. M., Adeyemo, B., Laumann, T. O., Gratton, C., Greene, D. J., Schlaggar, B. L., Hagler, D. J., … Dosenbach, N. U. F. (2020). NeuroImage, 208, 116400. https://doi.org/10.1016/j.neuroimage.2019.116400

Feczko, E., Conan, G., Marek, S., Tervo-Clemmens, B., Cordova, M., Doyle, O., Earl, E., Perrone, A., Sturgeon, D., Klein, R., Harman, G., Kilamovich, D., Hermosillo, R., Miranda-Dominguez, O., Adebimpe, A., Bertolero, M., Cieslak, M., Covitz, S., Hendrickson, T., … Fair, D. A. (2021). https://doi.org/10.1101/2021.07.09.451638

Glasser, M. F., Sotiropoulos, S. N., Wilson, J. A., Coalson, T. S., Fischl, B., Andersson, J. L., Xu, J., Jbabdi, S., Webster, M., Polimeni, J. R., Van Essen, D. C., & Jenkinson, M. (2013). NeuroImage, 80, 105–124. https://doi.org/10.1016/j.neuroimage.2013.04.127

Kiar, G., Clucas, J., Feczko, E., Goncalves, M., Jarecka, D., Markiewicz, C. J., Halchenko, Y. O., Hermosillo, R., Li, X., Miranda-Dominguez, O., Ghosh, S., Poldrack, R. A., Satterthwaite, T. D., Milham, M. P., & Fair, D. (2023). Nature Human Behaviour, 7(7), 1027–1028. https://doi.org/10.1038/s41562-023-01647-0