Skip to content

ukb-to-bids – Conversion of the UK Biobank (UKB) to BIDS

Description reproduced from the UK Biobank webpage

UK Biobank is a large-scale biomedical database and research resource, containing in-depth genetic and health information from half a million UK participants. The database is regularly augmented with additional data and is globally accessible to approved researchers undertaking vital research into the most common and life-threatening diseases. It is a major contributor to the advancement of modern medicine it and has led to the discovery of several scientific advances and numerous treatments to improve human health.


If you installed the core of Clinica, this converter needs the dcm2niix package.

Downloading UK Biobank

The UK Biobank to BIDS converter assumes that the user has already applied to get access to the data and that the imaging and clinical data have already been downloaded locally.

The imaging data can be downloaded and extracted using this tutorial. The clinical data can be extracted using the information from this repository.

Be careful, the file clinical_data.csv needs to contain the following informations about the subject: sex, year of birth, age at recruitment, age at sessions (there are two columns as there are two imaging sessions). The names of the columns should be kept as they are when downloaded using ukbconv using options csv.

Supported modalities

Please note that this converter processes the following modalities : - T1W (nifti) - T2 Flair (nifti) - DWI (nifti) - SWI (nifti) - tfMRI (dicom) - rsfMRI (dicom)


Whenever is possible, the converter uses the rawest files found. This decision allows the user to choose the processing needed. When available the converter get the associated json.

Modality Chosen image(s)  Justification
T1W T1.nii.gz Defaced and cropped so there is no neck. The rawest image would be the simply defaced one, but brain studies usually are not interested in the region of the neck. No other corrections are included.
T2 Flair T2_FLAIR.nii.gz Defaced and cropped so there is no neck. The reasons for choosing this image are the same as for T1.
DWI AP/PAnii.gz It is the rawest images we can get. bvals and bvec are also available.
rsfMRI rsfMRI.dcm Since the nii.gz version doesn't always include a json and in consideration for it's usage, we convert the dicom.
tfMRI tfMRI.dcm Same as rsfMRI.
SWI SWI.nii.gz Combined coil version. We would get a rawer version, but dcm2niix has trouble handling the slices direction, so it is simpler to go with this version. In addition, SWI modality is not fully integrated to BIDS specification and some changes may be coming. A simple version is available in the current version of this converter.

Using the converter

The converter can be run with the following command line:



  • DATASET_DIRECTORY is the path to the original UK BIobank imaging directory, whose content should look like:

  • CLINICAL_DATA_DIRECTORY is the path to the directory containing the clinical CSV file.

  • BIDS_DIRECTORY is the path to the output directory where the BIDS-converted version of UK Biobank will be stored.


In order to improve the readability, the BIDS subject ID is different from the original UK Biobank ID and is defined as follows:

sub-UKB+ original numerical ID of the subject


If the original subject ID is 0001, the final BIDS ID will be sub-UKB0001.

Citing this converter in your paper

Example of paragraph:

The UK Biobank data have been curated and converted to the Brain Imaging Data Structure (BIDS) format [Gorgolewski et al., 2016] using Clinica [Routier et al.; Samper-González et al., 2018].


Easily access the papers cited on this page on Zotero.