renaming subjects

Skip to first unread message

Jonathan Winawer

Aug 2, 2021, 10:32:40 AM8/2/21
to bids-discussion
Dear All,

If one has a BIDS dataset with many subjects and would like to rename some or all of the subjects, are there automated tools to do so? Renaming a subject requires changing the names of many files as well as the contents of some files. 

I asked a related question in 2019 and the answer seemed to be "no". But I am wondering if something might have been developed since then.


Ross Blair

Aug 2, 2021, 1:29:33 PM8/2/21
Hey Jon,

No one has purpose built a tool to my knowledge. What operating system are you on? Many linux distros have or even ship with a rename command thats quite nice, takes perl regular expressions. Here I ran it on ds001 in bids-examples with '-n' to not make any changes but print what it would do:

~/projects/bids-examples/ds001 $ find . -exec rename -n -e 's/sub-16/sub-2222/g' {} \;
rename(./sub-16, ./sub-2222)
rename(./sub-16/func, ./sub-2222/func)
rename(./sub-16/func/sub-16_task-balloonanalogrisktask_run-01_events.tsv, ./sub-2222/func/sub-2222_task-balloonanalogrisktask_run-01_events.tsv)
rename(./sub-16/func/sub-16_task-balloonanalogrisktask_run-03_events.tsv, ./sub-2222/func/sub-2222_task-balloonanalogrisktask_run-03_events.tsv)
rename(./sub-16/func/sub-16_task-balloonanalogrisktask_run-02_events.tsv, ./sub-2222/func/sub-2222_task-balloonanalogrisktask_run-02_events.tsv)
rename(./sub-16/func/sub-16_task-balloonanalogrisktask_run-01_bold.nii.gz, ./sub-2222/func/sub-2222_task-balloonanalogrisktask_run-01_bold.nii.gz)
rename(./sub-16/func/sub-16_task-balloonanalogrisktask_run-03_bold.nii.gz, ./sub-2222/func/sub-2222_task-balloonanalogrisktask_run-03_bold.nii.gz)
rename(./sub-16/func/sub-16_task-balloonanalogrisktask_run-02_bold.nii.gz, ./sub-2222/func/sub-2222_task-balloonanalogrisktask_run-02_bold.nii.gz)
rename(./sub-16/anat, ./sub-2222/anat)
rename(./sub-16/anat/sub-16_T1w.nii.gz, ./sub-2222/anat/sub-2222_T1w.nii.gz)
rename(./sub-16/anat/sub-16_inplaneT2.nii.gz, ./sub-2222/anat/sub-2222_inplaneT2.nii.gz)

One caveat is that theres an older utility also called rename that didn't used perl shipped by the linux kernel team. Need to check the man page for rename on your system to confirm which version is installed. Not sure what the state of rename on macs is.

Then to fix subject names in files we'd need to run a find exec with sed, I can come up with an example for that too if its an approach you might be interested in.

    - Ross

We are all colleagues working together to shape brain imaging for tomorrow, please be respectful, gracious, and patient with your fellow group members.
You received this message because you are subscribed to the Google Groups "bids-discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to
To view this discussion on the web visit

Ross Blair

Aug 2, 2021, 1:57:17 PM8/2/21
Came up with a oneliner to take a list of old subject names and new subject names and rename the files and then run sed. It goes without saying this is a potentially destructive one liner use at your own risk. I'm sure there are many many edge cases it doesn't cover, and could be tightened up in many ways. Backup your data before running etc, etc. One issue for example is that the sed runs on all filetypes so if for any reason the old subject name shows up coincidentally in a compressed file randomly it'll get replaced and ruin the file, unlikely but possible.
while IFS=, read -r old new; do find . -exec rename -n -e "s/$old/$new/g" {} \; &&  find -type f . -exec sed "s/$old/$new/g" {} \; ; done < rename.csv
Using a filename 'rename.csv' for redirection to feed it list of search/replacements:

~/projects/bids-examples/ds001 $ cat rename.csv

The command I posted still has '-n' in the rename command which will need to be removed to make the changes, and it does not have the '-i' flag in the sed command. '-i' does the search replace in place on the files, default is to print corrected text to stdout.

    - Ross

Jonathan A Winawer

Aug 2, 2021, 3:51:16 PM8/2/21
Thanks. Yes, we thought about a shell script. But in addition to file names and folder names, there is also some file content. For example, there are a number of tsv files and json files that include the subject code. This too, can be scripted. But it will take some work, especially to make sure it is robust. I would think that some code could piggy back on the validator to accomplish this, since the validator seems to crawl the file contents as well as the file names and detect inconsistencies if they exist.


Jonathan Winawer
Associate Professor of Psychology and Neural Science

New York University
6 Washington Place
New York, NY, 10003
Reply all
Reply to author
0 new messages