The secure, cloud-based service via a browser interface for the semi-automated mapping of entire MRI scanning sessions (DICOM files) to the Brain Imaging Data Structure (BIDS) standard.

This is the developmental repository for a semi-automated BIDS web service that allows users to upload to a secure server a directory containing DICOM (or dcm2niix output) files from an MRI scanner to be converted to BIDS.

Unlike other DICOM to BIDS converters, ezBIDS eliminates the need for the command line and heuristic/configuration setup.

dcm2niix is used to transform the DICOM files into a directory structure of NIfTI files. After that, an inferential process analyzes the directory structure and sidecars generated by dcm2niix to infer as much information as possible about the data. A browser user interface then presents the users with a first guess about the mapping of the directory strcuture to the BIDS format. Finally, users provided with the opportunity to verify the first guess and modify the information provided as needed so as to best match the final BIDS structure.

Data from all major scanner vendors can be directly uploaded to ezBIDS.

Users do not need to organize their uploaded data in any specific manner, so long as the data is non-anonymized. The uploaded data can contain any number of sub-folders, and users and may compress (e.g. zip, tar) their upload directory if users so choose. ezBIDS permits two types of data uploads:

1. DICOM files - Only DICOMs should be included in the upload. No specific organizational structure is required.
2. dcm2niix generated output (i.e. NIFTI, json, bval, and bvec) files - Only these files (no DICOMs) should be included in the upload. We strongly recommend that the dcm2niix output not be anonymized (i.e. include -ba n in the dcm2niix command), in which case, no specific organizational structure is required.

Should users feel the need to anonymize their data before uploading, we strongly recommend that subjects (and sessions) be organized into subject (and session) folders, with explicit labeling of the subject (and session) IDs (e.g. /MRI_data/sub-01/ses-01/DICOMS). Failure to do so for non-anonymized data will result in additional work.

ezBIDS provides options for the defacing of anatomical acquisitions.

The BIDS output can be downloaded back to the user's computer, or uploaded to open repositories such as brainlife.io, or in the future, OpenNeuro.

A video demonstration of how to use ezBIDS can be found here

To access the ezBIDS web service, please visit https://brainlife.io/ezbids (Chrome or Firefox broswer preferred).

(optional reading, if interested in the backend API workflow)

1. Uploading Data

When a user starts uploading data, ezBIDS will create a new session using (post)/session API. A session organize each ezBIDS upload/conversion process. For each session, a new DB/session collection is created with the mongo ID as session ID, and create a unique working directory using the sessionID on the backend server where all uploaded data is stored. When all files are successfully uploaded, client makes (patch)/session/uploaded/:session_id API call and set the session state to "uploaded" to let the ezBIDS handler knows that the session is ready to being preprocessing.

2. Preprocessing Data

The backend server polls for uploaded sessions, and when it finds "uploaded" session, it will launch the preprocessing script. It sets the session state to "preprocessing". It basically unzip all zipped files, run dcm2niix and create a list file containing all the nifti and sidecar json. analyzer.py uses this to analyze each nifti files and at the end create ezBIDS.json. When the preprocessing completes, the session state will be set to "analyzed". The preprocessing step then load ezBIDS.json json and copy the content to DB/ezBIDS collection (not session collection) under original key.

3. User interact with the session via web UI.

Web UI detects the preprocessing completed by polling for session state, and load the content of ezBIDS.json via (get)/download/:session_id/ezBIDS.json API. User then view / correct the content of ezBIDS.json.

4. (optionally) User request for defacing

Before user finalizes editing the information, they are given chance to deface anatomical images. When user requests defacing, the UI will make (post)/session/:sessino_id/deface API call with a list of images to deface. The backend stores this information as deface.json in the workdir and set the session state to "deface". The backend defacing handler looks "deface" state session and set it to "defacing" and launch deface.sh script. Once defacing is completed, it will set the session state to "defaced".

deface.sh create the following files under the workdir.

• deface.finished (list the anatomy files defaced successfully)
• deface.failed (list the anatomy files that failed defacing)

UI polls these files to determine which files are successfully defaced (or not). When defacing is completed, the status will be set to "defaced". User can then choose if they want to use the defaced version of anatomy file or not (each object will have a field named defaceSelection set to either "original" or "defaced" to indicate which image to use).

5. Finalize

When user clicks "finalize" button, UI makes an API call for (post)/session/:session_id/finalize API. The UI passes the following content from the memory ($root).

{
    datasetDescription: this.datasetDescription,
    readme: this.readme,
    participantsColumn: this.participantsColumn,
    subjects: this.subjects, //for phenotype
    objects: this.objects,
    entityMappings,
}

The API then store this information as finalized.json in workdir, and copy the content to DB/ezBIDS collection under updated key (to contrast with original key). The session status will be set to "finalized". This kicks off finalized handler on the server side and the handler reset the status to "bidsing" and run bids.sh script to generate the bids structure according to the information stored at the object level. Once it finishes, the session status will be set to "finished".

6. User download BIDS

Once session status becomes "finished", user will be then allowed to download the final "bids" directory via the download API, or send to other cloud resources

• Soichi Hayashi
• Daniel Levitas
• Franco Pestilli

brainlife.io is publicly funded and for the sustainability of the project it is helpful to Acknowledge the use of the platform. We kindly ask that you acknowledge the funding below in your code and publications. Copy and past the following lines into your repository when using this code.

We ask that you the following articles when publishing papers that used data, code or other resources created by the brainlife.io community.

1. Avesani, P., McPherson, B., Hayashi, S. et al. The open diffusion data derivatives, brain data upcycling via integrated publishing of derivatives and reproducible open cloud services. Sci Data 6, 69 (2019). https://doi.org/10.1038/s41597-019-0073-y

Copyright © 2020 brainlife.io at University of Texas at Austin and Indiana University