12. Reproducing the Preprint Results

If you would like to fully reproduce the results that we present in the BrainSuite BIDS App bioRxiv preprint (Kim et al., 2023), please follow the instructions below. All necessary TSV and JSON files are available from our BrainSuiteBIDSAppPaperData GitHub repository. The imaging data are publicly available on OpenNeuro.

Note

Please note that the following instructions use the Singularity-based BrainSuite BIDS App, because we recommend using a multi-user high performance computing (HPC) system to for processing these large datasets (imaging data from a total of 442 participants) and perform these analyses. Multi-user systems often do not permit Docker due to security reasons.

12.1. Prerequisites

1. Install Singularity:

   • You (or your IT support) can install Singularity as described here.

2. Download the pre-built Singularity-based BrainSuite BIDS App image:

   • A pre-built Singularity version of the BrainSuite BIDS App image is available here.

   Note

   If you would like to convert the Docker-based BrainSuite BIDS App image into a Singularity image instead, please see Section 2.2.3. “Converting Docker image to Singularity image” on our Installation page.

3. Download the imaging datasets from OpenNeuro:

   1. AOMIC-PIOP1 v2.0.0 (MRI data from 216 participants)

   2. AOMIC-PIOP2 v2.0.0 (MRI data from 226 participants)

4. Download the additional files for running the processing and analyses from our BrainSuiteBIDSAppPaperData GitHub repository. You can do so by completing one of the following steps:

   • Use git to clone the repository:

     git clone https://github.com/BrainSuite/BrainSuiteBIDSAppPaperData.git
     

   • Download the contents of the repository as a zip file. Unzip this file and rename the folder from BrainSuiteBIDSAppPaperData-master to BrainSuiteBIDSAppPaperData (this renaming step is simply to match the folder names in the instructions below).

5. (Optional but recommended) Set variables defining paths to the Singularity image, AOMIC PIOP dataset folders, output folders, and BrainSuiteBIDSAppPaperData directory. Please note that you have to modify the paths for each variable:

   BRAINSUITEBIDSAPP=/path/to/BrainSuiteBIDSApp
   BrainSuiteBIDSAppPaperData=/path/to/BrainSuiteBIDSAppPaperData
   AOMIC_PIOP1_INPUT=/path/to/AOMIC-PIOP1
   AOMIC_PIOP2_INPUT=/path/to/AOMIC-PIOP2
   AOMIC_PIOP1_OUTPUT=/path/to/AOMIC-PIOP1-output
   AOMIC_PIOP2_OUTPUT=/path/to/AOMIC-PIOP2-output
   QCDIR_AOMIC_PIOP1=/path/to/QC-AOMIC-PIOP1-directory
   QCDIR_AOMIC_PIOP2=/path/to/QC-AOMIC-PIOP2-directory
   ALL_AOMIC_OUTPUT=/path/to/combined-AOMIC-PIOP-output
   

where:

• /path/to/BrainSuiteBIDSApp : path to your Singularity-based BrainSuite BIDS App.

• /path/to/BrainSuiteBIDSAppPaperData : path to your BrainSuiteBIDSAppPaperData folder (downloaded from our BrainSuiteBIDSAppPaperData GitHub repository).

• /path/to/AOMIC-PIOP1 : the path to your AOMIC-PIOP1 study directory (when downloaded from OpenNeuro, the folder name is usually ds002785).

• /path/to/AOMIC-PIOP2 : the path to your AOMIC-PIOP2 study directory (when downloaded from OpenNeuro, the folder name is usualy ds002790).

• /path/to/AOMIC-PIOP1-output : where you would like your AOMIC-PIOP1 processing outputs to be written.

• /path/to/AOMIC-PIOP2-output : where you would like your AOMIC-PIOP2 processing outputs to be written.

• /path/to/QC-AOMIC-PIOP1-directory : where you would like the AOMIC-PIOP1 QC files and snapshot images to be written.

• /path/to/QC-AOMIC-PIOP2-directory : where you would like the AOMIC-PIOP2 QC files and snapshot images to be written.

• /path/to/combined-AOMIC-PIOP-output : the path to your combined output directory, where AOMIC-PIOP1 and AOMIC-PIOP2 processing outputs are placed together (see Step 1 in “Run group-level analysis” below for more detail).

12.2. Launch BrainSuite Dashboard

Launch the BrainSuite Dashboard to start monitoring the participant-level processes. You will need to launch two separate BrainSuite BIDS Apps to monitor AOMIC-PIOP1 and AOMIC-PIOP2 processing.

• If your institution already has a running web server, please follow these instructions:

  • To run BrainSuite Dashboard to monitor AOMIC-PIOP1 processing:

    singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $AOMIC_PIOP1_OUTPUT participant \
        --QCdir $QCDIR_AOMIC_PIOP1 --stages DASHBOARD
    

  • Open up another, separate terminal and run BrainSuite Dashboard to monitor AOMIC-PIOP2 processing:

    singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP2_INPUT $AOMIC_PIOP2_OUTPUT participant \
        --QCdir $QCDIR_AOMIC_PIOP2 --stages DASHBOARD
    

• If your institution does NOT have a running web server, please follow these instructions:

  • To run BrainSuite Dashboard to monitor AOMIC-PIOP1 processing by launching a local web server from BrainSuite BIDS App using the argument --localWebserver:

    singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $AOMIC_PIOP1_OUTPUT participant \
        --QCdir $QCDIR_AOMIC_PIOP1 --stages DASHBOARD --localWebserver
    

  • Open up another, separate terminal and run BrainSuite Dashboard with a different port number to monitor AOMIC-PIOP2 processing:

    singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP2_INPUT $AOMIC_PIOP2_OUTPUT participant \
        --QCdir $QCDIR_AOMIC_PIOP2 --stages DASHBOARD --localWebserver --port 9096
    

Note

The second command-line call for BrainSuite Dashboard (for AOMIC-PIOP2), using BrainSuite BIDS App’s local web server, employs a different port number. This is to prevent disconnections if the first BrainSuite Dashboard (for AOMIC-PIOP1) is still running and occupying the default port number (9095).

12.3. Run participant-level processing

To run participant-level processing, you will need to launch separate BrainSuite BIDS Apps (separate from the BrainSuite Dashboards). The following instructions will first process structural, diffusion, and functional MRI data of all subjects. Then 13 of these subjects will be re-run using modified parameters.

Tip

If your Singularity image cannot see your files on your system, try adding --bind /path/to/folder after singularity run.

1. Modify the paths in indexFile and acqpFile fields in all the JSON files (located in the BrainSuiteBIDSAppPaperData/preprocspecs directory). Please edit these paths to point to the correct locations on your computer.

2. Run participant-level processing on all subjects in AOMIC-PIOP1 and AOMIC-PIOP2 datasets using the preprocspecs.json file:

   1. To process the AOMIC-PIOP1 dataset:

      singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $AOMIC_PIOP1_OUTPUT participant \
          --QCdir $QCDIR_AOMIC_PIOP1 --preprocspec ${BrainSuiteBIDSAppPaperData}/preprocspecs/preprocspecs.json
      

   2. To process the AOMIC-PIOP2 dataset:

      singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP2_INPUT $AOMIC_PIOP2_OUTPUT participant \
          --QCdir $QCDIR_AOMIC_PIOP2 --preprocspec ${BrainSuiteBIDSAppPaperData}/preprocspecs/preprocspecs.json
      

3. After all of AOMIC-PIOP1 and AOMIC-PIOP2 datasets have completed processing, run the 13 subjects with special cases:

   1. Cases requiring modifications in the BrainSuite Anatomical Pipeline

      • Four subjects did not successfully complete the participant-level processing and required modification of parameters in the cerebrum labeling stage. Specifically:

        • During the cerebrum labeling stage, a labeled atlas is mapped onto the subject brain to identify the cerebrum, cerebellum and other structures. Seven subjects required parameter adjustments to improve this registration step:

          • 0106 (PIOP1) required initializing with centroids turned off, registration cost function set to least squares with intensity rescaling, and linear convergence set to 0.1.

          • 0185 and 0186 (both PIOP1) required initializing with centroids turned off and linear convergence set to 0.1.

          • 0189 (PIOP2) required linear convergence set to 0.1.

      • Three subjects did not successfully complete the participant-level processing and required modification of parameters in the skull stripping stage. Specifically:

        • During the skull-stripping stage, the automated parameters are selected. However, for the following 3 cases, automated parameter selection is turned off and settings are manually modified:

          • 0157 (PIOP1) required diffusion constant to be set to 30 and edge detection constant to be set to 0.57.

          • 0179 (PIOP1) required diffusion constant to be set to 30 and edge detection constant to be set to 0.58.

          • 0041 (PIOP2) required diffusion constant to be set to 22 and edge detection constant to be set to 0.70.

      • AOMIC-PIOP1: Re-run 5 subjects in AOMIC-PIOP1 (0106, 0157, 0179, 0185, and 0186) using their corresponding preprocspec.json files:

        singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $AOMIC_PIOP1_OUTPUT participant \
            --participant_label ${ID} \
            --QCdir $QCDIR_AOMIC_PIOP1 \
            --preprocspec ${BrainSuiteBIDSAppPaperData}/preprocspecs/piop1/sub-${ID}_preprocspec.json
        

        where ${ID} is 0106, 0157, 0179, 0185, and 0186.

      • AOMIC-PIOP2: Re-run 2 subjects in AOMIC-PIOP2 (0041 and 0189) using their corresponding preprocspec.json files:

        singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP2_INPUT $AOMIC_PIOP2_OUTPUT participant \
            --participant_label ${ID} \
            --QCdir $QCDIR_AOMIC_PIOP2 \
            --preprocspec ${BrainSuiteBIDSAppPaperData}/preprocspecs/piop2/sub-${ID}_preprocspec.json
        

        where ${ID} is 0041 and 0189.

   2. Cases requiring a modifications in the BrainSuite Functional Pipeline

      • Five subjects did not successfully complete the participant-level processing and required modification of parameters in the USC rigid registration stage of the BrainSuite Functional Pipeline. These subjects required the correlation ratio cost function for the registration.

      • AOMIC-PIOP1 and AOMIC-PIOP2. Re-run 6 subjects in PIOP1 (0129) and PIOP2 (0040, 0116, 0141, 0198, and 0217) with the uscrigid.json file:

        singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $AOMIC_PIOP1_OUTPUT participant \
            --participant_label 0129 \
            --QCdir $QCDIR_AOMIC_PIOP1 \
            --preprocspec ${BrainSuiteBIDSAppPaperData}/preprocspecs/uscrigid.json
        
        singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP2_INPUT $AOMIC_PIOP2_OUTPUT participant \
            --participant_label 0040 0116 0141 0198 0217 \
            --QCdir $QCDIR_AOMIC_PIOP2 \
            --preprocspec ${BrainSuiteBIDSAppPaperData}/preprocspecs/uscrigid.json
        

12.4. Run group-level analysis

1. After all datasets have finished processing, combine both outputs into one directory (where the path is the one you defined in ALL_AOMIC_OUTPUT=/path/to/combined-AOMIC-PIOP-output), with PIOP1 and PIOP2 appended to the subject IDs (e.g., sub-0001PIOP1, sub-0001PIOP2). You will also have to rename the file names to reflect these new subject IDs.

   Note

   Output folders and files have to be combined into a single directory, because BrainSuite BIDS App expects the outputs to be in one single directory.

2. Modify the path to your aomic-piop_06202023.tsv file (located in the BrainSuiteBIDSAppPaperData/demogTSV/ folder) in all the modelspec JSON files in BrainSuiteBIDSAppPaperData/modelspecs/ folder. The JSON fields you need to modify are tsv_fname fields. For example,

   ...
   "tsv_fname": "/path/to/BrainSuiteBIDSAppPaperData/demogTSV/aomic-piop_06202023.tsv",
   ...
   

3. Run all five group analyses:

   2. Run cortical thickness analysis using modelspec_sba.json. This modelspec file specifies an ANOVA model that tests the main effect of Raven’s score on cortical thickness while controlling for age and scanner on the female cohort:

      singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $ALL_AOMIC_OUTPUT group \
          --modelspec ${BrainSuiteBIDSAppPaperData}/modelspecs/modelspec_sba.json \
          --analysistype STRUCT
      

   3. Run ROI-based analysis using modelspec_roi.json. This modelspec file specifies an ANOVA model that tests the main effect of Raven’s score on left pars opercularis while controlling for age and scanner on the female cohort:

      singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $ALL_AOMIC_OUTPUT group \
          --modelspec ${BrainSuiteBIDSAppPaperData}/modelspecs/modelspec_roi.json \
          --analysistype STRUCT
      

   4. Run tensor-based morphometry analysis using modelspec_tbm.json. This modelspec file specifies an ANOVA model that tests the main effect of Raven’s score on tensor-based morphometry analysis while controlling for age and scanner on the female cohort:

      singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $ALL_AOMIC_OUTPUT group \
          --modelspec ${BrainSuiteBIDSAppPaperData}/modelspecs/modelspec_tbm.json \
          --analysistype STRUCT
      

   6. Run functional connectivity analysis using modelspec_fmri.json. This modelspec file specifies an ANOVA model that tests the main effect of Raven’s score on functional connectivity while controlling for age and scanner using atlas-based linear regression on the female cohort:

      singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $ALL_AOMIC_OUTPUT group \
          --modelspec ${BrainSuiteBIDSAppPaperData}/modelspecs/modelspec_fmri.json \
          --analysistype FUNC
      

   5. Run fractional anisotropy analysis using modelspec_dba.json. This modelspec file specifies a t-test that looks at the difference in fractional anisotropy values across males and females:

      singularity run $BRAINSUITEBIDSAPP $AOMIC_PIOP1_INPUT $ALL_AOMIC_OUTPUT group \
          --modelspec ${BrainSuiteBIDSAppPaperData}/modelspecs/modelspec_dba.json \
          --analysistype STRUCT