BIDS

The PennSIVE BIDS pipeline is based on the Brain Imaging Data Structure (BIDS) standards. For more details about the BIDS process and guidelines, please refer to the [BIDS page - LINK HERE].

This pipeline provides convenient heuristic customization through an RShiny app to organize data into BIDS format. It uses heudiconv for DICOM to NIFTI conversion.

Usage

This pipeline contains three stages: 1) Heuristic: prepares heuristic template, 2) Customization: launches RShiny app for heuristic customization, and 3) BIDS: runs DICOM to NIfTI conversion and format into BIDS structure.

This pipeline must be run through a container, either Singularity on a cluster or Docker locally. Steps 1 and 3 can be run in individual or batch mode, meaning you can specify a certain subject and session or run the pipeline for all subjects in the folder, respectively. Step 2 must be run in batch mode.

These examples will run the pipeline in batch mode on the cluster via Singularity. To run individually or locally with Docker, set --mode individual, or -c docker, respectively.

Step 1. Heuristic

This step prepares the heuristic file by copying the template to a template folder, as well as each subject and session folder. These files will be edited in Step 2: Customization.

Required flags:

-m or --mainpath: path to parent data folder
--toolpath: path to pipeline folder

Other flags:

-p or --participant: participant ID (only needed for individual mode)
--ses: session ID (only needed for individual mode)
--step: step of pipeline - heuristic, customization, bids. Default is heuristic
--mode: run pipeline individually or batch. Default is individual
-c or --container: which container to use: singularity, docker. Default is docker
--sinpath: path to singularity image (only needed if using singularity container - don't need to specify if using takim cluster)
--dockerpath: path to docker image (only needed if using docker container)
-h or --help: show help message

bash /path/to/PennSIVE_neuro_pip/pipelines/bids/code/bash/bids_curation.sh -m /path/to/project --mode batch -c singularity --toolpath /path/to/PennSIVE_neuro_pip

Step 2. Customization

In this step, an RShiny app will launch to customize the heuristic template created in the last step. **This step only runs in batch mode and does not need a container specification. If you are unable to connect to the app from your terminal, try running this step in VSCode.

Required flags:

-m or --mainpath: path to parent data folder
--step: step of pipeline - heuristic, customization, bids. Default is heuristic. This step is customization
--toolpath: path to pipeline folder

Other flags:

-h or --help: show help message

bash /path/to/PennSIVE_neuro_pip/pipelines/bids/code/bash/bids_curation.sh -m /path/to/project --step customization --toolpath /path/to/PennSIVE_neuro_pip

Using the app:

The Shiny app allows you to edit the heuristic file for all subjects in the original_data folder or for each subject individually.

To begin, under Choose Python Script, load in the heuristic.py file in the template folder.

To review each subjects' DICOM info and edit the heuristic on a subject-level basis, the DICOM Info Review will load each subject's info by clicking Next and Previous in the DICOM Selection. Edits can be made in the Update Heuristic Script section and finalized by clicking Update Script.

Group-level changes to the heuristic can be made by edits to the Update Heuristic Script section, and when finished, clicking Update All Scripts. This will apply those changes to all subjects in the folder.

Step 3. BIDS

This step runs DICOM to NIfTI conversion and format into BIDS structure based on the heuristic files edited in Step 2.

Required flags:

-m or --mainpath: path to parent data folder
--step: step of pipeline - heuristic, customization, bids. Default is heuristic. This step is bids
--toolpath: path to pipeline folder

Other flags:

-p or --participant: participant ID (only needed for individual mode)
--ses: session ID (only needed for individual mode)
--mode: run pipeline individually or batch. Default is individual
-c or --container: which container to use: singularity, docker. Default is docker
--sinpath: path to singularity image (only needed if using singularity container - don't need to specify if using takim cluster)
--dockerpath: path to docker image (only needed if using docker container)
-h or --help: show help message

bash /path/to/PennSIVE_neuro_pip/pipelines/bids/code/bash/bids_curation.sh -m /path/to/project --step bids --mode batch -c singularity --toolpath /path/to/PennSIVE_neuro_pip