-
Notifications
You must be signed in to change notification settings - Fork 1
Home
This wiki takes you through step by step a DICOM to NIfTI conversion using heudiconv which is a DICOM to BIDS convertor. The heudiconv program can be found at this link to download, along with some information and instructions.
In summary, you run the heudiconv program on your dicom files, passing along with it a "heuristic" python (.py ending) file, which contains criteria for identifying specific images in your DICOM folder for the conversion,
e.g. for DTI scans, you can specify which files to convert:- you might only want to convert the main data files, and not the scanner generated FA maps. You may want to convert the blip-up and blip-down files and give them a certain name (that is BIDS compatible).
If you are doing fMRI the heuristic file is where you can identify your different tasks or run numbers.
On the main page you can download a heuristic file that I've made for the DPRC study - which contains a range of image types (T1, T2, FLAIR, resting state, field map, ASL, DTI, SWI). Or you can find more examples here if you click on the heuristics folder.
-
Get docker - if you are not sure how to do this you can ask Centre for eReserach to help (eresearch-vm@list.auckland.ac.nz)
-
Pull the docker container that allows you to run heudiconv, by typing:
docker pull nipy/heudiconv
docker allows you to run heudiconv without installing all the dependencies (other programs it needs to run), if you want to run it without docker you will need: python 2.7, nipype, dcmstack and dcm2niix installed.
- install git on your machine
This is not essential for downloading the .py heuristic file on the main "code" page, but will be useful in the future for sharing any code or changes you make.
e.g. search for “git client windows” or ask CeR about installing on your VM.
dicominfo.tsv contains all the fields you can use in the heuristic file to uniquely identify images for conversion.
Run the following line in the directory where you have your subject DICOM folder (my folder is called PQC_ADPRC_20170925, replace this with your folder name)
docker run --rm -it -v $PWD:/data nipy/heudiconv -d /data/{subject}/* -s PQC_ADPRC_20170925 -f /heuristics/convertall.py -c dcm2niix -o /data/output
In the above command line:
docker run --rm -it
--rm is to remove the container after running the following command and -it is to run in interactive terminal
-v $PWD:/data nipy/heudiconv
-v is for volume and is saying to assign the current directory (PWD is print working directory) to a folder called /data in the container
-
nipy/heudiconvis running the heuidiconv container, text after this point is how you would run the heudiconv program if you weren't using docker. -
-d /data/{subject}/*
where -d '{subject}/*' finds all the DICOM files ({subject} expands to the subject ID (see next bullet) so that the expression will match any files, that start with the subject ID.
-s PQC_ADPRC_20170925
specifies a subject ID for the conversion. NB see here where it states that this could be a list of multiple IDs - presumably if wanted to convert more than 1 subject at a time. I have not checked this yet. For a large number of subjects you would probably want to script this, or the input is a list of IDS
-f ~/heuristics/convertall.py
uses a heuristic for this conversion called convertall.py, i.e. will try to convert all files, BUT as we've set
-c dcm2niix
is saying to use the file convertor dcm2niix (I have not tried any others at this stage). You could also have here -c none if you know that you just want to generate the dicom.tsv file first, without the NIfTI images (since you will probably want to rename them anyway).
Using -c dcm2niix we will generate some folders and files to get us started, but as we're using convertall.py we haven't specified any unique identifiers for naming the NIfTI files yet...
-o /data/output
specifies where to output the files to, here it's a new directory called "output" within the current one, but this could be anywhere you wish.
now if you type
ls
you will see the output folder has been generated, and if you type
ls output/
it contains another folder with the same name, output/PQC_ADPRC_20170925/ and within it are NIfTI images, but not with very sensible names...
A quick way to look at them (if you have FSL installed) will be e.g.
fslview output/PQC_ADPRC_20170925/run001-1.nii.gz &
but we want to access the dicominfo.tsv file. So if you now type:
ls -a output/
for list all, you will see a hidden directory called .heudiconv. In
output/.heudiconv/PQC_ADPRC_20170925/info/
is a dicominfo.tsv file containing information about all DICOM images in the folder you specified, with the subject headings that are the same as the fields in seqinfo in the heuristic file (stay with me, all will become clear)
I have found this is easiest to read in excel, but importing the tsv file with tab as deliminator so separate entry in each column, See here, but you can view it in text editor on your machine, e.g. pluma
pluma output/.heudiconv/PQC_ADPRC_20170925/info/dicominfo.tsv &
You will see in the current directory that a copy of convertall.py has been made. You could use this as the starting point for your heuristic file, but it's not very useful as has no criteria set for converting the files. On the main page, under code, you can download my heuristic file, called DPRC_WIP.py, and my dicmoinfo.xls file by typing
git clone https://github.com/Neuroimaging-RG/BIDS_conversion.git
You can used this file as a starting point for your study heuristic file, and just edit it with information from the dicominfo.tsv you just generated. There are also lots of examples of other heuristic files here, for example see banda-bids.py for 4 different fMRI tasks with the MB and reference scan and how to name them and some syntax to use to name multiple similar files.
NB you are editing a python file, which can be finickity to about spaces and tabbing. Where possible don't paste in what looks like blank space as these may have other hidden characters.
Now we are ready to run the conversion! The command line below is similar to what we ran above to generate the dicominfo.tsv, but now, we are mounting two volumes to the container,
-v $PWD:/data_current is where the working directory is, as before, but the 2nd one is new:
-v /data/SCRIPTS/BIDS_conversion/DPRC_WIP.py is where I'm keeping my heuristic files, and assigning it to :/data_current/DPRC_WIP.py in the container. And now -f /data_current/DPRC_WIP.py is feeding in our study specific heuristic
docker run --rm -it -v $PWD:/data_current -v /data/SCRIPTS/BIDS_conversion/DPRC_WIP.py:/data_current/DPRC_WIP.py nipy/heudiconv -d /data_current/{subject}/* -s PQC_ADPRC_20170925 -f /data_current/DPRC_WIP.py -c dcm2niix -o /data_current/output
You should now see that the files are named more sensibly then when we used convertall.py and are BIDs compatible*!
*see issues tab on subject names
if you use -b and --minmeta option for the conversion (see below for e.g.) then -b flag generates a json file with BIDS keys, and --minmeta flag restricts the json file to ONLY BIDS keys. I've had a quick look at this and e.g. the func data json file is huge if you just use -b option, but with minmeta is a lot smaller but presumably contains all the information you need.
From the main heuidiconv BIDS page "Without --minmeta, the json file and the associated Nifti file contains DICOM metadata extracted using dicomstack. "
adding -b --minmeta as options to line above:
docker run --rm -it -v $PWD:/data_current -v /data/SCRIPTS/BIDS_conversion/DPRC_WIP.py:/data_current/DPRC_WIP.py nipy/heudiconv -d /data_current/{subject}/* -s PQC_ADPRC_20170925 -f /data_current/DPRC_WIP.py -c dcm2niix -b --minmeta -o /data_current/output