Behavior and Neuroimaging Core User Manual
  • About
  • Infrastructure Overview
  • XNAT
    • Getting Started
    • Accessing XNAT
    • BIDS Ready Protocols
    • New XNAT projects
    • Uploading Data
    • Downloading Data
  • Demo Dataset
    • Introduction
    • How to access it
    • Protocol Information
    • Basic analysis example: checks task
  • XNAT to BIDS
    • Getting Started
    • XNAT2BIDS Software
    • Exporting to BIDS using Oscar
      • Oscar Utility Script
        • Running xnat2bids using default configuration
        • Running xnat2bids with a custom configuration
        • Syncing your XNAT project & Oscar data directory
        • Extra tools & features
      • Step-wise via Interact Session
    • BIDS Validation
      • Oscar
      • Docker
    • Converting non-MR data
      • Physiological data
      • EEG data
  • XNAT TO BIDS (Legacy)
    • Oscar SBATCH Scripts
  • BIDS and BIDS Containers
    • Introduction to BIDS
    • mriqc
    • fmriprep
    • BIDS to NIMH Data Archive (NDA)
  • Analysis Pipelines
    • Freesurfer
    • 🚧CONN Toolbox
    • FSL topup and eddy
    • Tractography: DSI Studio
    • Brown University MRS Data Collection and Preprocessing Protocol
    • LC Model
      • Installation
      • Example Run
      • Running LCModel on your own data
    • Quantitative Susceptibility Mapping (QSM)
  • Standalone Tools
    • Multi-session spectroscopy with voxalign
    • dicomsort: a tool to organize DICOM files
    • ironmap
    • convert enhanced multi-frame DICOMs to legacy single-frame
    • DICOM anonymization
  • MRF GUIDES
    • MRI simulator room
      • Motion Trainer: Balloon Task
      • Simulating scanner triggers
    • Stimulus display & response collection
    • Eyetracking at the scanner
    • Exporting data via scannershare
    • EEG in the scanner
    • Exporting spectroscopy RDA files
  • Community
    • MRF/BNC user community meetings
Powered by GitBook
On this page
  • Preparing your data
  • Step 1: Get MR data into valid BIDS format
  • Step 2: Convert behavioral data into BIDS format
  • Step 3: Add stimulus information and stimulus files
  • Step 4: Create GUIDs and BIDS ID-to-GUID mapping file
  • Step 5: (optional) Create NDA Experiment IDs and BIDS task name - to NDA Experiment ID mapping file
  • Step 6: (optional) Create or copy a csv with additional data
  • Installing BIDS2NDA and the NDA validator
  • Running the BIDS to NDA conversion
  • Validating the NDA-formatted data
  • Tips

Was this helpful?

  1. BIDS and BIDS Containers

BIDS to NIMH Data Archive (NDA)

PreviousfmriprepNextFreesurfer

Last updated 4 months ago

Was this helpful?

To help users comply with data sharing requirements from the NIMH, we are extending that automatically converts BIDS-formatted MR data into the format required by the NIMH. This tool is a work in progress, so please get in touch with any issues or suggested features!


Preparing your data

Step 1: Get MR data into valid

If you are using XNAT and have worked with us to set up your protocol to be , follow to pull your data from XNAT to Oscar and automatically convert it into BIDS format.

Step 2: Convert behavioral data into BIDS format

If you are converting fMRI task data, you will need to do some additional work to also convert your behavioral data into the . You can find an example using our demodat dataset .

Step 3: Add stimulus information and stimulus files

If you have stimulus files that you would also like to include in your upload to the NDA, make sure to include stimulus information in the stim_file column of your _events.tsv files like this:

The BIDS spec assumes that these files live in a "stimuli" folder at the top level of your BIDS directory like this:

If you want to organize the stimuli further, you can have subfolders within your "stimuli" folder, and then include the subfolder in the stim_file field. For example, if you want to put all the stimuli sub-001 saw in a folder called "001" within the "stimuli" folder, your events.tsv file would have 001/001_stim1.png, etc. in the stim_file column.

Step 4: Create GUIDs and BIDS ID-to-GUID mapping file

001 - LJFOIJWEL 002 - LKJSFIJLW

Save this file (i.e. guids.txt) in the same folder as your BIDS directory, but not inside the BIDS directory.

Step 5: (optional) Create NDA Experiment IDs and BIDS task name - to NDA Experiment ID mapping file

checks - 9990 rest - 9991

Save this file (i.e. expIDs.txt) in the same folder as your BIDS directory, but not inside the BIDS directory. If you don't provide this file in the BIDS2NDA conversion, the experiment_id column in the output image03.csv file will be left blank and you will need to fill it in manually for any fMRI rows.

Step 6: (optional) Create or copy a csv with additional data

Sometimes there is information that is missing or incorrect from the automatic BIDS conversion, that you may have available from another source. For example, the BIDS conversion approximates the interview_age in months from the age in years in the BIDS data. This age needs to exactly match any other data uploaded for the same participant (i.e. ndar_subject01.csv), so our bids2nda conversion tool allows you to specify a csv with additional data you would like to use to modify the image03.csv file.

Save this csv in the same folder as your BIDS directory, but not inside the BIDS directory.


Installing BIDS2NDA and the NDA validator

  1. Change to your home directory cd ~

  2. Create a new python environment called "bids2nda" python -m venv bids2nda

  3. Activate the new environment source ~/bids2nda/bin/activate

  4. Install our version of the BIDS to NDA conversion tool pip install https://github.com/brown-bnc/bids2nda/archive/master.zip


Running the BIDS to NDA conversion

  1. First, make sure that you are in your bids2nda environment. It should say (bids2nda) in front of your terminal command prompt. If it does not, activate the environment with source ~/bids2nda/bin/activate

  2. Change to your directory that contains your BIDS directory, GUID mapping file, and experiment ID mapping file.

  3. Make a new directory for your NDA-formatted data

    mkdir nda_output

  4. bids2nda bids guids.txt nda_output -e expIDs.txt --lookup_csv ndar_subject01.csv --lookup_fields interview_age The -e, --lookup_csv, and --lookup_fields are optional. In this example, we are grabbing the interview age in months from the ndar_subject01.csv file and using it to fill in the interview_age column in the image03.csv file.

  5. If successful, you should see the message "Metadata extraction complete.", and the nda_output folder should contain one image03.csv file and a series of .metadata.zip files. These zip files are referenced in the data_file2 column of the image03.csv and will ultimately be uploaded with your data. They contain:

    1. The BIDS json sidecars that go along with each of your NIFTIs

    2. the _events.tsv behavioral files

    3. any stimulus files you supplied

We are working on a fix, but for now the photomet_interpret field of the image03.csv file will need to be filled in manually if you are converting any "enhanced" DICOM files (i.e. data collected post- scanner upgrade to XA30). The correct value is likely MONOCHROME2, but double-check your DICOM header for the (0028,0004) | Photometric Interpretation field to make sure this is true for your data.


Validating the NDA-formatted data

To run the validator tool supplied by the NDA:

  1. Change directory to your new NDA output folder cd nda_output

  2. Run the validator, passing in the new image03.csv file vtcmd image03.csv

  3. The tool will print information about whether or not your data passed validation. If it failed, open the validation report and address any identified issues.


Tips

  1. Make sure your dataset is BIDS-valid. The conversion tool will attempt to add any files in your BIDS directory that follow the sub-*.nii.gz pattern, so any extra files in your BIDS directory (from analyses, etc.) may cause errors.

  2. If you are uploading data to the NDA in batches, you'll need to temporarily copy just the data for the current upload into a separate BIDS directory, so that the tool doesn't attempt to parse any previously uploaded data. When you do that, make sure to also copy over the participants.tsv file and edit it to only contain the participants for the current upload.

  3. If you manually modify the participants.tsv file (in MATLAB especially), be careful that it retains its tab-delimited format. Otherwise, it will not be read in properly.

NIMH requires that each participant be assigned a . Once you have done this for each participant, you need to create a text file that contains each of your BIDS subject IDs and the associated GUIDs. If my BIDS directory has folders for sub-001 and sub-002, my GUID mapping file would look like this:

The NDA requires that every experiment be , and when approved, it will be assigned an ID number. Each task that your participants complete will need its own approved experiment ID (including resting state). Once you have received your experiment ID(s), you will need to create another mapping text file - this one providing the mapping between the task names in your fMRI BIDS filenames (i.e. sub-001_ses-01_task-checks_run-01_bold.nii.gz) and your approved experiment ID numbers. For example, if my participants completed a "checks" task that was assigned an ID of 9990, and a "rest" resting state scan that was assigned an ID of 9991, my experiment ID mapping file would look like this:

To install in a :

Install the that will let us test whether the data is NDA-compliant pip install nda-tools

Launch the

"Global Unique Identifier" or GUID, created with their tool
defined
Python virtual environment on Oscar
NDA validator
BIDS to NDA converter
a tool from the BIDS folks
BIDS format
BIDS-friendly
these steps
_events.tsv files required by BIDS
here
Including stimuli in your BIDS structure