SPM/BIDS

__NOTOC__ Brain Imaging Data Structure The Brain Imaging Data Structure (BIDS) is a simple and intuitive way to organise and describe neuroimaging and behavioural data. Standard specification Current release Current draft Validator BIDS Validator: online or from the command line bids-validator. Discussion Forums Google Groups NeuroStars Tutorials BIDS Examples BIDS Starter Kit Publications The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments. Gorgolewski K.J., Auer T., Calhoun V.D., Craddock R.C., Das S., Duff E.P., Flandin G., Ghosh S.S., Glatard T., Halchenko Y.O., Handwerker D.A., Hanke M., Keator D., Li X., Michael Z., Maumet C., Nichols B.N., Nichols T.E., Pellman J., Poline J.-B., Rokem A., Schaefer G., Sochat V., Triplett W., Turner J.A., Varoquaux G. & Poldrack R.A. Scientific Data 3, 160044 (2016). BIDS apps: Improving ease of use, accessibility, and reproducibility of neuroimaging data analysis methods. Gorgolewski K.J., Alfaro-Almagro F., Auer T., Bellec P., Capota M., Chakravarty M.M., Churchill N.W., Cohen A.L., Craddock R.C., Devenyi G.A., Eklund A., Esteban O., Flandin G., Ghosh S.S., Guntupalli J.S., Jenkinson M., Keshavan A., Kiar G., Liem F., Raamana P.R., Raffelt D., Steele C.J., Quirion P.-O., Smith R.E., Strother S.C., Varoquaux G., Wang Y., Yarkoni T. & Poldrack R.A. PLoS Computational Biology 13(3):e1005209 (2017). MEG-BIDS, the brain imaging data structure extended to magnetoencephalography. Niso G., Gorgolewski K.J., Bock E., Brooks T.L., Flandin G., Gramfort A., Henson R.N., Jas M., Litvak V., Moreau J.T., Oostenveld R., Schoffelen J.-M., Tadel F., Wexler J. & Baillet S. Scientific Data 5, 180110 (2018). EEG-BIDS, an extension to the brain imaging data structure for electroencephalography. Pernet C.R., Appelhoff S., Gorgolewski K.J., Flandin G., Phillips C., Delorme A. & Oostenveld R. Scientific Data 6, 103 (2019) . BIDS Tools in SPM/MATLAB SPM provides a number of functionalities (MATLAB/Octave functions) to facilitate the creation or use of datasets formatted according to BIDS. JSON files A JSON file can be read/written using spm_jsonread and spm_jsonwrite. >> type sub-01_task-rest_bold.json { "RepetitionTime": 3.0, "Instruction": "Lie still and keep your eyes open" } >> bold = spm_jsonread('sub-01_task-rest_bold.json') bold = RepetitionTime: 3 Instruction: 'Lie still and keep your eyes open' >> descr = struct('Name','My Dataset','BIDSVersion','1.0.2') descr = Name: 'My Dataset' BIDSVersion: '1.0.2' >> spm_jsonwrite('dataset_description.json',descr, struct('indent',' ')); >> type dataset_description.json { "Name": "My Dataset", "BIDSVersion": "1.0.2" } These functions are also independently available in JSONio, a JSON library for MATLAB and Octave. They are compatible with MATLAB's jsonencode and jsondecode. TSV files A tab-separated values (TSV) file can be read/written using spm_load and spm_save. >> type task-Checkerboard_acq-TR645_events.tsv onset duration trial_type 0 20 Fixation 20 20 Checkerboard 40 20 Fixation 60 20 Checkerboard 80 20 Fixation 100 20 Checkerboard >> events = spm_load('task-Checkerboard_acq-TR645_events.tsv') events = onset: [6x1 double] duration: [6x1 double] trial_type: {6x1 cell} >> p = struct('participant_id',{{'sub-01','sub-02'}}, 'sex',{{'M','F'}}, 'age',[28 21]) p = participant_id: {'sub-01' 'sub-02'} sex: {'M' 'F'} age: [28 21] >> spm_save('participants.tsv',p) >> type participants.tsv participant_id sex age sub-01 M 28 sub-02 F 21 These functions are compatible with MATLAB table array and handle gzip compression transparently. >> participant_id = {'sub-01'; 'sub-02'}; >> sex = {'M'; 'F'}; >> age = [28 21]'; >> p = table(participant_id,sex,age); >> spm_save('participants.tsv.gz',p) >> spm_load('participants.tsv.gz') ans = participant_id: {2x1 cell} sex: {2x1 cell} age: [2x1 double] NIfTI files NIfTI files can be read/written using spm_vol or @nifti. >> S = nifti('sub-2475376__T1w.nii') S = NIFTI object: 1-by-1 dat: [256x256x192 file_array] mat: [4x4 double] mat_intent: 'Scanner' mat0: [4x4 double] mat0_intent: 'Scanner' descrip: 'MR' >> F = nifti('sub-2475376_task-Checkerboard_bold.nii') F = NIFTI object: 1-by-1 dat: [4-D file_array] mat: [4x4 double] mat_intent: 'Scanner' mat0: [4x4 double] mat0_intent: 'Scanner' timing: [1x1 struct] descrip: '4D image' >> F.timing.tspace ans = 1.4000 By default, SPM does not support compressed NIfTI files (.nii.gz) but MATLAB/Octave provide gzip/gunzip functions if needed and they are also available through the batch interface from BasicIO > File Operations > Gunzip Files. BIDS parser and queries A data directory organised according to BIDS can be parsed with spm_BIDS. Here is an example using the ds007 dataset: >> % Parse BIDS directory >> BIDS = spm_BIDS('/data/BIDS-examples/ds007'); >> % Make general queries about the dataset >> spm_BIDS(BIDS,'subjects') ans = '01' '02' '03' '04' '05' '06' '07' '08' '09' '10' '11' '12' '13' '14' '15' '16' '17' '18' '19' '20' >> spm_BIDS(BIDS,'sessions') ans = Empty cell array: 1-by-0 >> spm_BIDS(BIDS,'runs') ans = '01' '02' >> spm_BIDS(BIDS,'tasks') ans = 'stopsignalwithletternaming' 'stopsignalwithmanualresponse' 'stopsignalwithpseudowordnaming' >> spm_BIDS(BIDS,'types') ans = 'T1w' 'bold' 'events' 'inplaneT2' >> spm_BIDS(BIDS,'modalities') ans = 'anat' 'func' >> % Make more specific queries >> spm_BIDS(BIDS,'runs','type','T1w') ans = Empty cell array: 1-by-0 >> spm_BIDS(BIDS,'runs','type','bold') ans = '01' '02' >> % Get the NIfTI file for subject '05', run '02' and task 'stopsignalwithmanualresponse': >> spm_BIDS(BIDS,'data','sub','05','run','02','task','stopsignalwithmanualresponse','type','bold') ans = '/data/ds007/sub-05/func/sub-05_task-stopsignalwithmanualresponse_run-02_bold.nii.gz' >> % and corresponding metadata, including TR: >> spm_BIDS(BIDS,'metadata','sub','05','run','02','task','stopsignalwithmanualresponse','type','bold') ans = RepetitionTime: 2 TaskName: 'stop signal with manual response' >> % Get the T1-weighted images from all subjects: >> spm_BIDS(BIDS,'data','type','T1w') ans = '/data/ds007/sub-01/anat/sub-01_T1w.nii.gz' '/data/ds007/sub-02/anat/sub-02_T1w.nii.gz' '/data/ds007/sub-03/anat/sub-03_T1w.nii.gz' '/data/ds007/sub-04/anat/sub-04_T1w.nii.gz' '/data/ds007/sub-05/anat/sub-05_T1w.nii.gz' '/data/ds007/sub-06/anat/sub-06_T1w.nii.gz' '/data/ds007/sub-07/anat/sub-07_T1w.nii.gz' '/data/ds007/sub-08/anat/sub-08_T1w.nii.gz' '/data/ds007/sub-09/anat/sub-09_T1w.nii.gz' '/data/ds007/sub-10/anat/sub-10_T1w.nii.gz' '/data/ds007/sub-11/anat/sub-11_T1w.nii.gz' '/data/ds007/sub-12/anat/sub-12_T1w.nii.gz' '/data/ds007/sub-13/anat/sub-13_T1w.nii.gz' '/data/ds007/sub-14/anat/sub-14_T1w.nii.gz' '/data/ds007/sub-15/anat/sub-15_T1w.nii.gz' '/data/ds007/sub-16/anat/sub-16_T1w.nii.gz' '/data/ds007/sub-17/anat/sub-17_T1w.nii.gz' '/data/ds007/sub-18/anat/sub-18_T1w.nii.gz' '/data/ds007/sub-19/anat/sub-19_T1w.nii.gz' '/data/ds007/sub-20/anat/sub-20_T1w.nii.gz' Formatting datasets into BIDS Helper functions spm_mkdir and spm_copy might come handy, as well as previously mentionned spm_save and spm_jsonwrite. For example, the following piece of code using spm_mkdir: >> spm_mkdir('/data/bids',{'sub-2475376','sub-5489652'},{'ses-1','ses-2'},'func'); >> spm_mkdir('/data/bids',{'sub-2475376','sub-5489652'},'ses-1','anat'); creates this directory hierarchy: /data └── bids ├── sub-2475376 │   ├── ses-1 │   │   ├── anat │   │   └── func │   └── ses-2 │   └── func └── sub-5489652 ├── ses-1 │   ├── anat │   └── func └── ses-2 └── func while spm_copy makes it easier to copy files and their attached metadata (e.g. sidecar JSON files) with compression on the fly. >> ls sub-2475376_task-rest_bold.json sub-2475376_task-rest_bold.nii.gz >> spm_copy('sub-2475376_task-rest_bold.nii.gz','/derivatives', 'nifti',true, 'gunzip',true) >> ls /derivatives sub-2475376_task-rest_bold.json sub-2475376_task-rest_bold.nii See also these options in the batch interface: The DICOM Import batch module has an option to create metadata sidecar JSON files: matlabbatch{1}.spm.util.import.dicom.convopts.meta = true; The 3D to 4D File Conversion batch module has an option to store the TR in the NIfTI header: matlabbatch{1}.spm.util.cat.RT = TR; See also SPM BIDS-App