{"id":18143691,"url":"https://github.com/remi-gau/bids_cookbook","last_synced_at":"2025-04-23T01:06:57.417Z","repository":{"id":37900696,"uuid":"393011927","full_name":"Remi-Gau/bids_cookbook","owner":"Remi-Gau","description":"A simple recipe to convert your neuroimaging data into a BIDS dataset.","archived":false,"fork":false,"pushed_at":"2024-10-08T08:16:07.000Z","size":1244,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-23T01:06:50.348Z","etag":null,"topics":["bids","data","eeg","fmri","matlab","meg","spm12","tutorial"],"latest_commit_sha":null,"homepage":"https://remi-gau.github.io/bids_cookbook","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Remi-Gau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-08-05T11:11:48.000Z","updated_at":"2024-10-08T08:16:10.000Z","dependencies_parsed_at":"2024-04-09T07:34:07.045Z","dependency_job_id":"c2365876-f1f0-4176-a9fd-42cee8823dcb","html_url":"https://github.com/Remi-Gau/bids_cookbook","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Remi-Gau%2Fbids_cookbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Remi-Gau%2Fbids_cookbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Remi-Gau%2Fbids_cookbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Remi-Gau%2Fbids_cookbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Remi-Gau","download_url":"https://codeload.github.com/Remi-Gau/bids_cookbook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250349055,"owners_count":21415914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bids","data","eeg","fmri","matlab","meg","spm12","tutorial"],"created_at":"2024-11-01T19:08:31.917Z","updated_at":"2025-04-23T01:06:57.400Z","avatar_url":"https://github.com/Remi-Gau.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7111042.svg)](https://doi.org/10.5281/zenodo.7111042)\n[![License: CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)\n\n\u003c!-- TODO\n- conversion script for MEG events\n- link to BEPs have a look and contribute\n- use BEPs to organize yet unsupported data\n--\u003e\n\n\u003ch1 style=\"width: 120%\"\u003e Preparing a BIDS dataset by hand and from scratch \u003c/h1\u003e\n\n\u003ccenter\u003e\n\u003ch3 style=\"color:red;\"\u003e\n  ⚠️ Note that this is purely for learning purposes and it is NOT recommended to BIDSify real datasets by hand . ⚠️\n\u003c/h3\u003e\n\u003c/center\u003e\n\n\u003ch2 id=\"TOC\"\u003e Table of content \u003c/h2\u003e\n\n- [Ingredients](#ingredients-and-tools)\n- [Recipe](#recipe)\n  - [Preheat the oven: folder structure](#preheat)\n  - [Starters: anatomical data](#starters)\n  - [Main course: functional data](#main-course)\n  - [Dessert: defacing, QA...](#dessert)\n- [Useful links](#useful-links)\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003eCLICK ME\u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n\n... to see what I hide !!!\n\n\u003ccenter\u003e\n\u003ca href=\"https://twitter.com/RemiGau/status/1115513296134778880\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://pbs.twimg.com/media/D3sYRfhWkAAlevT?format=jpg\u0026name=small\" width=\"500\" /\u003e\n\u003c/a\u003e\n\u003c/center\u003e\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## Ingredients and tools\n\nGet them fresh from your local ~~market~~:\n\n- MRI scanner 🧲\n- EEG amplifier 🌩\n- MEG squid [🦑](https://theupturnedmicroscope.com/comic/squid/)\n- ...\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003e 🧠 some \u003ccode\u003esource\u003c/code\u003e data to be converted into BIDS \u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n  \u003cp\u003e\n    We will work with the\n    \u003ca href=\"https://www.fil.ion.ucl.ac.uk/spm/data/mmfaces/\" target=\"_blank\"\u003e\n    multi-modal face dataset from SPM\n    \u003c/a\u003e.\n  \u003c/p\u003e\n  \u003cp\u003e\n      Very often MRI source data will be in a DICOM format and will require to be converted.\n      Here the MRI data is in \"3D\" Nifti format \u003ccode\u003e.hdr/.img\u003c/code\u003e and\n      we will need to change that to a \"4D\" Nifti \u003ccode\u003e.nii\u003c/code\u003e format.\n  \u003c/p\u003e\n  \u003cp\u003e\n    This dataset contains EEG, MEG and fMRI data on the same subject within the same paradigm.\n    We also extracted some of the information about the data from the SPM manual\n    and put it into the \u003ccode\u003esource/README.md\u003c/code\u003e.\n  \u003c/p\u003e\n  \u003cp\u003e\n    Similarly when you have DICOM data, it is usually a good idea\n    to keep the PDF of MRI acquisition parameters with your source data.\n  \u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003e 🖋 a text editor \u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n    Several common options top choose from:\n    \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"https://code.visualstudio.com\" target=\"_blank\"\u003eVisual Studio code\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"https://www.sublimetext.com/\" target=\"_blank\"\u003eSublime\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"https://atom.io/\" target=\"_blank\"\u003eAtom\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003eNotepad does not really count.\u003c/li\u003e\n    \u003c/ul\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003e ♻ some format conversion tools \u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n    \u003cp\u003e\n      For the MRI data we will be using some of the SPM built-in functions\n      to convert Nifti files into the proper format.\n    \u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003e 📥 [OPTIONAL] BIDS validator \u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n  \u003cul\u003e\n      \u003cli\u003eInstall \u003ca href=\"https://nodejs.org\" target=\"_blank\"\u003eNode.js\u003c/a\u003e (at least version 12.12.0).\u003c/li\u003e\n      \u003cli\u003eUpdate \u003ccode\u003enpm\u003c/code\u003e to be at least version 7 (\u003ccode\u003enpm install --global npm@^7\u003c/code\u003e)\u003c/li\u003e\n      \u003cli\u003eFrom a terminal run \u003ccode\u003enpm install -g bids-validator\u003c/code\u003e\u003c/li\u003e\n      \u003cli\u003eRun \u003ccode\u003ebids-validator\u003c/code\u003e to start validating datasets.\u003c/li\u003e\n  \u003c/ul\u003e\n  See the full instruction \u003ca href=\"https://www.npmjs.com/package/bids-validator#quickstart\" target=\"_blank\"\u003ehere.\u003c/a\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e \u003cb\u003e\n    \u003cimg  src=\"https://raw.githubusercontent.com/datalad/artwork/master/logos/logo_solo.svg\"\n          height=\"14\"\n          style=\"padding: 0; margin: 0\"/\u003e\n    [OPTIONAL] Datalad to version control your data\n  \u003c/b\u003e \u003c/summary\u003e \u003cbr\u003e\n  \u003cp\u003e\n    You can follow the installation instruction in the\n    \u003ca href=\"http://handbook.datalad.org/en/latest/intro/installation.html\" target=\"_blank\"\u003e\n      Datalad handbook.\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003e 🐳 [OPTIONAL] Docker \u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n  \u003cp\u003e\n    Check the install instruction for your system\n    \u003ca href=\"https://docs.docker.com/get-docker/\" target=\"_blank\"\u003e\n      here.\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## Recipe\n\n\u003ch3 id=\"preheat\"\u003e1. Preheat the oven: creating folders\u003c/h3\u003e\n\n- Create a `raw` folder to host your BIDS data and inside it create:\n\n  - a `sourcedata` folder and put your `source` data in it\n  - a `code/conversion` folder and put this `README.md` in it\n  - a subject folder: `sub-01`\n    - with session folder: `ses-mri`\n      - with an `anat` folder for the structural MRI data\n      - with an `func` folder for the functional MRI data\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003eBy now you should have this.\u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n  \u003cpre\u003e\n  ├── code\n  │   └── conversion\n  ├── sourcedata\n  │   ├── multimodal_fmri\n  │   │   └── fMRI\n  │   │       ├── Session1\n  │   │       └── Session2\n  │   └── multimodal_smri\n  │       └── sMRI\n  └── sub-01\n      └── ses-mri\n          ├── anat\n          └── func\n  \u003c/pre\u003e\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n\u003ch3 id=\"starters\"\u003e2. Starters: converting the anatomical MRI file\u003c/h3\u003e\n\n- In Matlab launch SPM: `spm fmri`.\n- In SPM:\n\n  - use the SPM 3D to 4D module:\n    ```\n      Batch --\u003e SPM --\u003e Utils --\u003e 3D to 4D File conversion\n    ```\n  - select the `*.img` file to convert\n  - keep track of what you did by saving the batch in `code/conversion`\n  - run the batch\n\n#### a. Cooking is not just about the taste, it is also about how things look: naming files\n\n- Move the `.nii` file you have just created into `sub-01/ses-mri/anat`.\n- Give this file a valid BIDS filename.\n\n\u003cdetails\u003e\u003csummary\u003e ✅ Valid BIDS filenames \u003c/summary\u003e\u003cbr\u003e\n  \u003cul\u003e\n    \u003cli\u003e\n      BIDS filenames are composed of:\n      \u003cul\u003e\n        \u003cli\u003e\u003ccode\u003eextension\u003c/code\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ccode\u003esuffix\u003c/code\u003e preceded by a \u003ccode\u003e_\u003c/code\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ccode\u003eentity-label\u003c/code\u003e pairs separated by a \u003ccode\u003e_\u003c/code\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      So a BIDS filename can look like: \u003ccode\u003eentity1-label1_entity2-label2_suffix.extension\u003c/code\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ccode\u003eentities\u003c/code\u003e and \u003ccode\u003elabels\u003c/code\u003e can only contain letters and / or numbers.\n    \u003c/li\u003e\n    \u003cli\u003e\n      For a given suffix, some entities are \u003ccode\u003erequired\u003c/code\u003e and some others are \u003ccode\u003e[optional]\u003c/code\u003e.\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ccode\u003eentity-label\u003c/code\u003e pairs pairs have a specific order in which they must appear in filename.\n    \u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/details\u003e\n\nIn case you do not remember which suffix to use and which entities are required\nor optional, the BIDS specification has:\n\n- [filename templates](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#anatomy-imaging-data)\n  at the beginning of the section for each imaging modality,\n- a summary\n  [entity table](https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html).\n\n#### b. Taste your dish while you prepare it: using the BIDS validator\n\nTry it directly in your\n\u003ca href=\"https://bids-standard.github.io/bids-validator/\" target=\"_blank\"\u003ebrowser.\u003c/a\u003e\n\n#### c. Season to taste: adding missing files\n\n- `README`\n- `dataset_description.json`\n\nYou can get content for those files from:\n\n- from the [BIDS specification](https://bids-specification.readthedocs.io) (use\n  the search bar)\n- the BIDS starter\n  [templates](https://github.com/bids-standard/bids-starter-kit/tree/main/templates)\n\n\u003e Suggestion:\n\u003e\n\u003e Add the \"table\" output of the BIDS validator to your README to give a quick\n\u003e overview of the content of your dataset.\n\n\u003cdetails\u003e\u003csummary\u003e 🚨 About JSON files \u003c/summary\u003e\u003cbr\u003e\nJSON files are text files to store \u003ccode\u003ekey-value\u003c/code\u003e pairs.\n\nIf your editor cannot help you format them properly, you can always use the\n\u003ca href=\"https://jsoneditoronline.org/\" target=\"_blank\"\u003e online editor.\u003c/a\u003e\n\n\u003cp\u003e\nMore information on how read and write JSON files is available on the\n\u003ca  href=\"https://github.com/bids-standard/bids-starter-kit/wiki/Metadata-file-formats#json-files\"\n    target=\"_blank\"\u003e\n  BIDS stater kit.\n\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cpre\u003eJSON CONTENT EXAMPLE:\n\n{\n  \"key\": \"value\",\n  \"key2\": \"value2\",\n  \"key3\": {\n    \"subkey1\": \"subvalue1\"\n  },\n  \"array\": [ 1, 2, 3 ],\n  \"boolean\": true,\n  \"color\": \"gold\",\n  \"null\": null,\n  \"number\": 123,\n  \"object\": {\n    \"a\": \"b\",\n    \"c\": \"d\"\n  },\n  \"string\": \"Hello World\"\n}\u003c/pre\u003e\n\u003c/details\u003e\n\n#### d. Icing on the cake: adding extra information\n\n- Add `T1w.json` file. Use information from `source/README.md` to create it.\n- Add a participants `participants.tsv`. You can use excel or google sheet to\n  create them.\n\n\u003cdetails\u003e\u003csummary\u003e 🚨 About TSV files \u003c/summary\u003e\u003cbr\u003e\nA Tab-Separate Values (TSV) file is a text file where tab characters\n(\u003ccode\u003e\\t\u003c/code\u003e) separate fields that are in the file.\n\nIt is structured as a table, with each column representing a field of interest,\nand each row representing a single data point.\n\n\u003cp\u003eMore information on how read and write TSV files is available on the\n\u003ca href=\"https://github.com/bids-standard/bids-starter-kit/wiki/Metadata-file-formats#tsv-files\"\n      target=\"_blank\"\u003e BIDS stater kit \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cpre\u003eTSV CONTENT EXAMPLE:\n\nparticipant_id\\tage\\tgender\\n\nsub-01\\t34\\tM\u003c/pre\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003eBy now you should have this.\u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n  \u003cpre\u003e\n  ├── code\n  ├── sourcedata\n  ├── sub-01\n  │   └── ses-mri\n  │       ├── anat\n│ │       │   ├── sub-01_ses-mri_T1w.json\n│ │       │   └── sub-01_ses-mri_T1w.nii\n  │       └── func\n  ├── README\n  ├── participants.tsv\n  ├── participants.json\n  └── dataset_description.json\n  \u003c/pre\u003e\n\u003c/details\u003e\n\n#### e. BIDS is data jam: let's preserve some\n\n**[OPTIONAL]**\n\n- Create a Datalad dataset\n- make a commit when you have a valid dataset to use as a checkpoint.\n\n```bash\ndatalad create --force -c text2git .\ndatalad save -m 'initial commit'\n```\n\n\u003cbr\u003e\n\n\u003ch3 id=\"main-course\"\u003e3. Main course: converting the functional MRI files\u003c/h3\u003e\n\n- Convert the 2 runs of made of 3D series of `*.img` into 2 single 4D `*.nii`\n  images by using the same SPM module used for the anatomical conversion.\n- Make sure to use enter the repetition time in the `interscan interval`.\n- Give the output files valid BIDS filenames. You will need to use `task` and\n  the `run` entities.\n- Use the BIDS validator and any eventual missing file (like `*_bold.json`\n  file).\n- Create `events.tsv`: you can run the function\n  `multimodal/code/convert_func_event_mat.m` to help you convert the files\n  `multimodal/source/multimodal_fmri/fMRI/trials_ses*.mat`\n- Put the `events.tsv` files in the func folders and give them BIDS valid names.\n- Remove duplicate `json` files to make use of the\n  [\"inheritance principle\"](https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#the-inheritance-principle)\n\n\u003cdetails\u003e\u003csummary\u003e \u003cb\u003eBy now you should have this.\u003c/b\u003e \u003c/summary\u003e\u003cbr\u003e\n  \u003cpre\u003e\n  ├── code\n  ├── sourcedata\n  ├── sub-01\n  │   └── ses-mri\n  │       ├── anat\n│ │       │   └── sub-01_ses-mri_T1w.nii\n  │       └── func\n  │           ├── sub-01_ses-mri_task-FaceSymmetry_run-1_bold.nii\n  │           ├── sub-01_ses-mri_task-FaceSymmetry_run-1_events.tsv\n  │           ├── sub-01_ses-mri_task-FaceSymmetry_run-2_bold.nii\n  │           └── sub-01_ses-mri_task-FaceSymmetry_run-2_events.tsv\n  ├── README\n  ├── participants.tsv\n  ├── participants.json\n  ├── T1w.json\n  ├── task-FaceSymmetry_bold.json\n  └── dataset_description.json\n  \u003c/pre\u003e\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n\u003ch3 id=\"dessert\"\u003e4. Dessert: defacing, quality control, upload your data to GIN...\u003c/h3\u003e\n\n#### Defacing\n\n- with SPM:\n  ```\n    Batch --\u003e SPM --\u003e Utils --\u003e De-face images\n  ```\n  \u003c!-- - with [bidsonym](https://github.com/PeerHerholz/BIDSonym)\n    ```bash\n    bids_dir=`pwd`\n    docker run -i --rm \\\n              -v ${bids_dir}:/bids_dataset \\\n              peerherholz/bidsonym:latest \\\n              /bids_dataset \\\n              group --deid quickshear \\\n              --brainextraction bet --bet_frac 0.5\n    ``` --\u003e\n\n#### [MRIQC](https://mriqc.readthedocs.io/en/latest/)\n\n```bash\n# from within the `raw` folder\n\nbids_dir=`pwd`\n\noutput_dir=${bids_dir}/../derivatives/mriqc\n\ndocker run -it --rm \\\n  -v ${bids_dir}:/data:ro \\\n  -v ${output_dir}:/out \\\n  poldracklab/mriqc:0.16.1 /data /out \\\n  --participant_label sub-01 \\\n  --verbose-reports \\\n  participant\n```\n\n#### uploading your data on GIN\n\n- create an account on [GIN](https://gin.g-node.org/)\n- [upload your public SSH key to GIN](http://handbook.datalad.org/en/latest/basics/101-139-gin.html#prerequisites)\n  for SSH access\n  - you might need to\n    [create one first](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)\n- create an empty repository on GIN\n  ```\n  datalad siblings add --name gin --url git@gin.g-node.org:/your_username/your_repository.git\n  datalad push --to gin\n  ```\n- More information on the\n  [datalad handbook](http://handbook.datalad.org/en/latest/basics/101-139-gin.html)\n\n#### Things to improve ?\n\n  \u003c!-- - Do not version control data before defacing. --\u003e\n  \u003c!-- - Do not version control source in the raw dataset. --\u003e\n\n\u003cbr\u003e\n\n## Useful links\n\n- [BIDS specification](https://bids-specification.readthedocs.io)\n- [BIDS starter kit](https://github.com/bids-standard/bids-starter-kit)\n  - [templates](https://github.com/bids-standard/bids-starter-kit/tree/main/templates)\n  - [wiki](https://github.com/bids-standard/bids-starter-kit/wiki)\n    - [validator](https://github.com/bids-standard/bids-starter-kit/wiki/bids-validator-info)\n- [BIDS validator](https://github.com/bids-standard/bids-validator)\n- [BIDS examples](https://github.com/bids-standard/bids-examples)\n- [Neurostars forum](https://neurostars.org/tag/bids)\n- Other conversion tutorial\n  - [reproducibility.stanford.edu](https://reproducibility.stanford.edu/bids-tutorial-series-part-1a/)\n  - [fieldtrip](https://www.fieldtriptoolbox.org/example/bids_mous/)\n- [Conversion tools](https://bids.neuroimaging.io/benefits.html#converters)\n- [Datalad handbook](http://handbook.datalad.org/en/latest/index.html)\n- [GIN](https://gin.g-node.org/)\n\n---\n\n\u003cbutton\u003e\u003ca href=\"#TOC\"\u003eback to the top\u003c/a\u003e\u003c/button\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremi-gau%2Fbids_cookbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fremi-gau%2Fbids_cookbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremi-gau%2Fbids_cookbook/lists"}