8. Walk-through Demo

This tutorial guides you through two example exercises designed to help them become familiarized with performing BrainSuite BIDS App’s participant-level processing and BrainSuite Dashboard quality control. The first exercise uses the Docker version of BrainSuite BIDS App whereas the second uses the Singularity version. The approximate time required for running entire participant-level pipeline is 1.5 hours [~10 minutes for CSE, ~20 minutes for BDP, ~45 minutes for SVREG (BDP and SVREG run in parallel), and ~35 minutes for BFP] per subject. Depending on your computer’s specifications, the processing times will vary.

This walk-through uses employs data and files from our GitHub repository, which include:

• A small subset (data from 4 participants) of the publicly available Amsterdam Open MRI Collection’s Population Imaging of Psychology 2 (AOMIC-PIOP2) dataset available from OpenNeuro. Modalities include T1-weighted (T1-w), diffusion MRI (dMRI), resting-state functional MRI (rs-fMRI).

• A JSON file containing parameters for T1-weighted, dMRI, and rs-fMRI processing.

• Two text files required for running FSL’s eddy (index.txt and acqp.txt). These files contain information regarding acquisition parameters for the diffusion MRI data. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide.

This tutorial will also enable you to display intermediate outputs using the BrainSuite Dashboard. An example of the output produced from this dataset is available here.

8.1. Prerequisites

1. Download the required files from our GitHub repository by one of two ways (not required to do both):

   • Download the zip file. The total size of this zip file is about 385MB. Once the zip file has completed downloading, please unzip it and rename the folder from BrainSuiteBIDSAppSampleData-master to BrainSuiteBIDSAppSampleData for ease of use, since this will make the folder name compatible with the instructions below.

   • Clone the repository by running the following in the terminal. The download size is around 776MB.

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

2. Install container technologies.

   • To run the Docker-based tutorial, please install Docker from here. For Linux, you may have to perform additional post-installation steps.

   • To run the Singularity-based tutorial, please install here.

8.2. Using Docker-based BrainSuite BIDS App

In this exercise, you will run participant-level processing and BrainSuite Dashboard using the Docker-based BrainSuite BIDS App. For more information regarding each argument, please refer to the “Command-line interface using Docker” section in the “Running participant-level BrainSuite BIDS App” page.

8.2.1. Run Participant-Level Processing

1. Pull the BrainSuite BIDS App image from the DockerHub repository. Open terminal and run:

   docker pull bids/brainsuite:v23a
   

This command line call will download the Docker-based BrainSuite BIDS App (about 17GB total).

1. Run structural, difussion, and function MRI processing for all 4 subjects OR one subject.

   • Process all 4 subjects:

     docker run -ti --rm \
     -v /path/to/BrainSuiteBIDSAppSampleData/:/BrainSuiteBIDSAppSampleData:ro \
     -v /path/to/output/:/output \
     bids/brainsuite:v23a \
     /BrainSuiteBIDSAppSampleData/AOMIC-PIOP2 /output participant \
     --preprocspec /BrainSuiteBIDSAppSampleData/preprocspec.json
     

     where you must modify:

     • /path/to/BrainSuiteBIDSAppSampleData : the path of the location of BrainSuiteBIDSAppSampleData that is downloaded onto your computer.

     • /path/to/output : the path to where you would like the output files to be written.

   Note

   If you run the above command line without --preprocspec /BrainSuiteBIDSAppSampleData/preprocspec.json, BrainSuite BIDS App will run with all default settings. The /BrainSuiteBIDSAppSampleData/preprocspec.json file contains parameters that have been modified to produce optimal results for this exercise.

   • Process a single subject:

     docker run -ti --rm \
     -v /path/to/BrainSuiteBIDSAppSampleData/:/BrainSuiteBIDSAppSampleData:ro \
     -v /path/to/output/:/output \
     bids/brainsuite:v23a \
     /BrainSuiteBIDSAppSampleData/AOMIC-PIOP2 /output participant \
     --participant_label 0015 \
     --preprocspec /BrainSuiteBIDSAppSampleData/preprocspec.json
     

     where you must modify:

     • /path/to/BrainSuiteBIDSAppSampleData : the path of the location of BrainSuiteBIDSAppSampleData that is downloaded onto your computer.

     • /path/to/output : the path to where you would like the output files to be written. If you are currently processing all 4 subjects from the above command line call, then this output directory path should differ from the one used above to prevent the programs from accessing the same files simultaneously.

     where you can optionally modify:

     • 0015 : the subject ID of the dataset to process. To process a different subject dataset, please change this to 0017, 0035, or 0065.

   Note

   If you would like to run select stages (i.e. CSE, SVREG, BDP, or BFP), you can do so by using the --stages argument of the BrainSuite BIDS App. Multiple stages can be specified by writing a space-delimited string of stage names (i.e. --stages CSE SVREG).

8.2.2. Run BrainSuite Dashboard

1. While participant-level processing is running, open up a separate terminal and run the BrainSuite Dashboard:

   docker run -ti --rm \
     -p 9095:9095 \
     -v /path/to/BrainSuiteBIDSAppSampleData/:/BrainSuiteBIDSAppSampleData:ro \
     -v /path/to/output/:/output \
     bids/brainsuite:v23a \
     /BrainSuiteBIDSAppSampleData/AOMIC-PIOP2 /output participant \
     --stages DASHBOARD --localWebserver
   

where you must modify:

• /path/to/BrainSuiteBIDSAppSampleData : the path of the location of BrainSuiteBIDSAppSampleData that is downloaded onto your computer.

• /path/to/output/ : the output directory where the outputs from the participant-level processing are being written or has been written.

Important

If you are running a remote desktop or any other connections, please check that you are not using the same port as the one you have chosen to expose, as defined in -p (i.e. port 9999 in -p 9999:9095). Using the same port number may disconnect the active connections using this specific port.

To view the BrainSuite Dashboard for real-time updates on the participant-level processing, open a web browser and navigate to: http://127.0.0.1:9095. You can still launch the BrainSuite Dashboard after the participant-level processing is completed, but it will not show real-time updates, since processing has ended.

8.3. Using Singularity-based BrainSuite BIDS App

This exercise is similar to the Docker-based tutorial above, except it uses the Singularity-based BrainSuite BIDS App. In this exercise, you will run participant-level processing and BrainSuite Dashboard using the Singularity-based BrainSuite BIDS App. For more information regarding each argument, please refer to the “Command-line interface using Singularity” section in the “Running participant-level BrainSuite BIDS App” page.

8.3.1. Run Participant-Level Processing

1. Download a pre-built Singularity-based BrainSuite BIDS App from here. This Singularity image is about 6.6GB.

2. Modify the paths in indexFile and acqpFile fields in the preprocspec.json file (located in the BrainSuiteBIDSAppSampleData directory). Please edit these paths to point to the correct locations on your computer.

3. Run structural, difussion, and function MRI processing for all 4 subjects OR one subject.

   • Process all 4 subjects:

     singularity run /path/to/bids_brainsuite_v23a.simg \
             /path/to/BrainSuiteBIDSAppSampleData/ /path/to/output/ participant \
             --preprocspec /path/to/BrainSuiteBIDSAppSampleData/preprocspec.json
     

     where you must modify:

     • /path/to/bids_brainsuite_v23a.simg : path to the Singularity-based BrainSuite BIDS App image.

     • /path/to/BrainSuiteBIDSAppSampleData : the path of the location of BrainSuiteBIDSAppSampleData that is downloaded onto your computer.

     • /path/to/output : the path to where you would like the output files to be written.

   Note

   If you run the above command line without --preprocspec /path/to/BrainSuiteBIDSAppSampleData/preprocspec.json, BrainSuite BIDS App will run with all default settings. The /BrainSuiteBIDSAppSampleData/preprocspec.json file contains parameters that have been modified to produce optimal results for this exercise.

   • Process a single subject:

     singularity run /path/to/bids_brainsuite_v23a.simg \
             /path/to/BrainSuiteBIDSAppSampleData/ /path/to/output/ participant \
             --participant_label 0015 \
             --preprocspec /BrainSuiteBIDSAppSampleData/preprocspec.json
     

     where you must modify:

     • /path/to/bids_brainsuite_v23a.simg : path to the Singularity-based BrainSuite BIDS App image.

     • /path/to/BrainSuiteBIDSAppSampleData : the path of the location of BrainSuiteBIDSAppSampleData that is downloaded onto your computer.

     • /path/to/output : the path to where you would like the output files to be written.

     where you can optionally modify:

     • 0015 : the subject ID of the dataset to process. To process a different subject dataset, please change this to 0017, 0035, or 0065.

Note

If you would like to run select stages (i.e. CSE, SVREG, BDP, or BFP), you can do so by using the --stages argument of the BrainSuite BIDS App. Multiple stages can be specified by writing a space-delimited string of stage names (i.e. --stages CSE SVREG).

8.3.2. Run BrainSuite Dashboard

1. While participant-level processing is running, open up a separate terminal and run the BrainSuite Dashboard:

   singularity run bids_brainsuite_v23a.simg \
       /path/to/BrainSuiteBIDSAppSampleData/ /path/to/output/ participant \
       --stages DASHBOARD \
       --localWebserver
   

where you must modify:

• /path/to/BrainSuiteBIDSAppSampleData : the path of the location of BrainSuiteBIDSAppSampleData that is downloaded onto your computer.

• /path/to/output/ : the output directory where the outputs from the participant-level processing are being written or has been written.

Important

If you are running a remote desktop or any other connections, please check that you are not using the same port as the default (9095) or the one you have chosen with the --port argument. Using the same port number may disconnect the active connections using this specific port. To change the port number, please use the --port argument (i.e. --port 9999).

To view the BrainSuite Dashboard for real-time updates on the participant-level processing, open a web browser and navigate to: http://127.0.0.1:9095. You can still launch the BrainSuite Dashboard after the participant-level processing is completed, but it will not show real-time updates, since processing has ended.

8.4. Citation and License for AOMIC-PIOP2 Dataset

• Citation for the complete AOMIC-PIOP2 dataset:

  • Snoek, L., van der Miesen, M. M., Van Der Leij, A., Beemsterboer, T., Eigenhuis, A., & Steven Scholte, H. (2020). AOMIC-PIOP2. OpenNeuro. [Dataset] doi: 10.18112/openneuro.ds002790.v2.0.0

• Citation for the dataset paper:

  • Snoek, L., van der Miesen, M. M., Beemsterboer, T., Van Der Leij, A., Eigenhuis, A., & Steven Scholte, H. (2021). The Amsterdam Open MRI Collection, a set of multimodal MRI datasets for individual difference analyses. Scientific data, 8(1), 85.

• AOMIC-PIOP2 Dataset License

  • CC0 These data are freely available under a CC0 license.