Heudiconv across multiple sessions


Does anyone have a simple example of a heudiconv command inputting multiple sessions? I may be missing something obvious, but I am not able to get the command below to work.

setenv TEST 001
setenv SUBJ sub-$TEST
setenv DATA /autofs/cluster/<path to data>
setenv WORK /autofs/cluster/<path to personal folder>
setenv IMAGE /autofs/cluster/<path to singularity image>
setenv SINGULARITY <path to singularity command
mkdir /scratch/raw_dicom && cp -r $DATA/dicom/$SUBJ /scratch/raw_dicom/
mkdir /scratch/heuristic && cp -r $WORK/heudiconv/heuristics/FSMAP/*convert*.py /scratch/heuristic/

$SINGULARITY exec --bind '/scratch:/scratch' $IMAGE \
/neurodocker/startup.sh heudiconv \
-d '/scratch/raw_dicom/{subject}/ses-{session}/*/MR.*' \
-s $TEST \
-ss 01 02 \
-f /scratch/heuristic/FSMAP_convert_ses-01.py \
-c dcm2niix -b --minmeta \
-o /scratch/$SUBJ

This returns the error:

usage: heudiconv [-h] [--version]
             [-d DICOM_DIR_TEMPLATE | --files [FILES [FILES ...]]]
             [-s [SUBJS [SUBJS ...]]] [-c {dcm2niix,none}] [-o OUTDIR]
             [-a CONV_OUTDIR] [--anon-cmd ANON_CMD] -f HEURISTIC_FILE [-p]
             [-ss SESSION] [-b] [--overwrite] [--datalad] [--dbg]
             [--command {treat-json,ls,populate-templates}]
             [-g {studyUID,accession_number}] [--minmeta] [-q QUEUE]
             [--sbargs SBATCH_ARGS]
heudiconv: error: unrecognized arguments: 02

This is obviously something simple, but I couldn’t find much documentation on multi session conversion, so thought I would ask!



@jordan_theriault currently we only support one input for the session flag, so you’ll have to call heudiconv twice if you want to convert ses-01 and ses-02

1 Like


Ahh thanks for the clarification. The Github documentation and the usage message (above) suggest that session can be used, so it might be helpful to correct those when you have a chance.

Thanks again!



The usage message just says what it does support - a single session definition: [-ss SESSION], compare to --files for example of an option accepting multiple inputs: --files [FILES [FILES ...]]

But your heuristic (in infotoids) could deduce session identifier for every accession, so if the path you pointed has multiple accessions, it could assign corresponding multiple/different sessions to each accession it is to process. See e.g. ReproIn heuristic – we are typically assigning session identifier to the scout scan. It also supports _ses-{date} and _ses+ identifiers so session would either correspond to the date (used for our QA phantom scans) or just incremented each time correspondingly.

Hope this helps

1 Like


Hi, Mathias,

Heudiconv is really great! I also hope to use it automatically deal with multiple session of multiple subjects.

Seems that one solution is to use for loop in bash to run multiple session & multiple participant (as you mentioned in Heudiconv on multiple subjects).

I am still new to Linux (only use Linux recently for heudicov, fmriprep, and Nipype), so I am wondering, are there some example bash code/files that I can imitate?



@hcp4715 Only example I could readily find was in a slideshow:



Hi, @rwblair,

Many thanks for your source!
Will update how it goes :wink:



Hi, I have included an example call in our new documentation, here’s the link


Hope that can help

1 Like


Hi, @mgxd Thanks for your help.
That example is a bit more complicated to me, because currently I am still trying to test the whole BIDS-fmriprep thing on my own laptop.

I used (for the first time) bash’s for loop to solve my problem now, maybe looks very inefficient, but easy to understand.

But I have other problems that not relevant to this topic, just post it here in case that you guys have some suggestion: https://github.com/nipy/heudiconv/issues/126#issuecomment-481432209

Below is my current code, just in case it may give other beginners some hints:

for subject in {001..003}; 
    #subjDir+="${subject}"   # get the subject folder
    #echo "${subjDir}"
    #echo ${subject}
    for session in {1..3}; 
        sesId+="${session}" #$(echo "${session: -2}")  # get the last two characters of session folder
        #echo ${subject}
        #echo ${session}
        #echo ${sesId}
        # take care of the space in the [ ] after if
	if [ ${sesId} == "d1" ]; then
	elif [ ${sesId} == "d2" ]; then
        elif [ ${sesId} == "d3" ]; then
	#echo ${heuristicFile}
	docker run --rm -it \
	-v /media/hcp4715/USB1/Data/RepDopa/BIDS_test:/base nipy/heudiconv:latest \
	-d /base/Dicom/sub-{subject}/ses-{session}/*/* \
	-o /base/Nifti/ \
	-f convertall \
	-s ${subject} \
	-ss ${sesId} \
	-c none \
	-b --overwrite --minmeta