Session renaming during HeuDiConv conversion

Hi bids/heudiconv experts,
I am currently trying to convert some large datasets, and it is organized as dataset/subject/modality/time/imageID/*.dicom
The information of session name is not in the folder name and rename the dicom folder will take huge amount of time. I need to look for the exact name of session in another tabular data file datainfo.tsv, there is one to one correspondence between imageID and the desired session name.
I understand the best way to do this might be using the, read the tsv and match with subject or imageID, but I have no idea how to do it here, any suggestions/ tutorials/code examples?

The work around plan I used was use date (first 8 digits of time) as a temporary session name and renamed all the files after the conversion.

not sure which would be the closest for you, but indeed you “just” need to create your own heuristic to establish session indicator based on some other metadata you could match in tsv?
Have a pick at existing heuristics at heudiconv/heudiconv/heuristics at master · nipy/heudiconv · GitHub ?

And alternative is it feed session indicator from outside since heudiconv has command line parameter for it:

  -ss SESSION, --ses SESSION
                        Session for longitudinal study_sessions. Default is

so you can write a script which reads needed info from .tsv and calls heudiconv with the corresponding --ses

Thanks for your instant reply and the link to the existing heuristics. My heuristic file is here:, and I am currently passing the first 8 digit of time as session string using --ses, like --ses 20220202 as the temporary session string, and change the session string 20220202 to V01 with another script. I am wondering whether I can do the change of session name inside the heuristics.

sorry, no time for a turnkey answer ATM but it must be possible since in reproin we do that in infotoids returning at locator (folder prefix pretty much), session and subject

Great thanks! Need some time to investigate. :grinning: