How dcm2bids-session plugin works to output data in BIDS structure?

Skip to first unread message


Jul 13, 2020, 2:46:47 AM7/13/20
to xnat_discussion

I have managed to run up the docker version of XNAT with plugin of dcm2bids-session installed, then I try with a small subject dicom data (which is uploaded by upload-assistant. 

The data layout in xnat-data for this subject looks like this:


In the web UI, just launch the plugin as 


Then run it with overwrite true


It replies that container launch successfully. Take a look on the xnat-data and one RESOURCES/BIDS directory is added but the other data remains the same.


Use to check, it failed for this output is not in BIDS format.
Just find some logs under archive\CONTAINER_EXEC and attach files: stdout.log, stderr.log.

Have checked xnat discussion group for such kind of topic like this!topic/xnat_discussion/YSTPkd617co and the but these posts are quite old (2017 or 2018) , I wonder they are still applicable. 

So, how to make it works? 

Thanks for your help. 



Jul 15, 2020, 11:10:18 PM7/15/20
to xnat_discussion
This section of your log:

Get site-wide BIDS map
Could not read site-wide BIDS map
Get project BIDS map if one exists
Could not read project BIDS map

 indicates that you are missing a BIDS mapping configuration in your XNAT. You will need to put values into a config using the REST API. These values will tell the script running in the dcm2bids-session container how to map your scan types to BIDS types.
  1. Figure out what all your scan types are (by looking at the scans on your sessions in XNAT). For example, this might be something like MPRAGE.
  2. Look at the BIDS spec and figure out what all the BIDS types are for your scans. For instance, your MPRAGE scan would map to the BIDS type T1W.
  3. Write all these values to a file, with the following structure:
{"series_description": "YOUR_SCAN_TYPE_1", "bidsname": "BIDS_TYPE_1"},
  {"series_description": "YOUR_SCAN_TYPE_2", "bidsname": "BIDS_TYPE_2"},
  {"series_description": "YOUR_SCAN_TYPE_N", "bidsname": "BIDS_TYPE_N"}

You can use the attached file as a starting point. It has the correct JSON structure and comes pre-loaded with a lot of scan types. 

 4. Use a REST client to PUT this up to the following config URL: {YOUR_XNAT}/data/projects/{YOUR_PROJECT}/config/bids/bidsmap. For instance, here is a command for curl:

$ curl -u {YOUR_USERNAME}:{YOUR_PASSWORD} -d @/path/to/file/with/bids/mapping -X PUT '{YOUR_XNAT}/data/projects/{YOUR_PROJECT}/config/bids/bidsmap?inbody=true'

Verify the config is present by GETing the config.

$ curl -u {YOUR_USERNAME}:{YOUR_PASSWORD} '{YOUR_XNAT}/data/projects/{YOUR_PROJECT}/config/bids/bidsmap'

5. Check the stdout.log file after running again to see if you missed any scan types.



Jul 17, 2020, 8:52:29 PM7/17/20
to xnat_discussion
Thank you Matt, you help me a lot. 

It works except that I should use this command for upload bids map file:  curl -u xxx:yyy --upload-file "/data/bidsmap.json" -X PUT 'xnat_ip/data/projects/1/config/bids/bidsmap?inbody=true'     

Should this kind of instruction be put on XNAT wiki page? I could not find it there but it should be helpful for newbie. 

Three questions are still open:
1. /data/xnat/build has similar converted BIDS data as that in docker's xnat-data/archive, is the former the intermediate output while the latter is the final result?  It looks like that because in  /data/xnat/build the directory names are some random number such as a29459f1-25ef-4a3a-9001-7862e841479f. 

2. For bidsmap json, could it be automatically generated from the DICOM? I guess it could not because series description is filled in by MR operator manually, which could be incorrect. (Ask this because I am a coder , not a medical expert). So, consider a copy of data in hand which series description is filled in non-strict format, how could I figure out the what it is for bidsmap? 

3. For docker images, what is the difference between dcm2bids-session and bids-mriqc ? Are they serving the same purpose?

Reply all
Reply to author
0 new messages