From afa0d287f02d2b986f949c1085e733aad6935600 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Fri, 27 Sep 2024 09:17:22 +0200 Subject: [PATCH] [ENH] Move starter kit to new BIDS website with redirects (#414) * updates * update templates * update blog, converter, FAQ * update FAQ * clean governance * work on rendering bep * improve BEP and grant tables and announcement bar * general fixes * misc * add links to redirects * rm submodules * minor fixes * redirect validator * mv example * add banner * [ENH] move tutorials out of starter kit * [ENH] move remaining pages (#418) * move remaining pages * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> * add redirects and clean up * change links --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .codespellrc | 7 - .faq/FAQ.md | 42 - .faq/suggest.md | 20 - .github/workflows/build_book_on_pr.yml | 46 - .github/workflows/check_md_links.yml | 28 - .github/workflows/codespell.yml | 23 - .github/workflows/deploy_book.yml | 4 +- .github/workflows/faqtory.yml | 39 - .github/workflows/miss_hit.yml | 49 - .github/workflows/no-bad-latin.yml | 63 - .gitmodules | 8 - Makefile | 16 +- README.md | 22 +- faq.yml | 8 - mlc_config.json | 13 - pyproject.toml | 12 - questions/README.md | 6 - questions/eeg_biosemi.question.md | 17 - questions/eeg_filters.question.md | 22 - questions/general_bep.question.md | 55 - questions/general_cite.question.md | 9 - questions/general_convert.question.md | 9 - questions/general_convert_nifti.question.md | 57 - questions/general_excel.question.md | 8 - questions/general_hyperscanning.question.md | 55 - questions/general_json.question.md | 6 - questions/general_license.question.md | 10 - questions/general_micro.question.md | 18 - questions/general_nwb.question.md | 19 - questions/general_schema.question.md | 18 - questions/general_session.question.md | 22 - questions/general_what.question.md | 6 - questions/mri_defacing.question.md | 23 - questions/pheno_epilepsy.question.md | 8 - questions/pheno_pheno.question.md | 14 - requirements.txt | 5 - requirements_dev.txt | 4 - src/CONTRIBUTING.md | 56 +- src/FAQ.md | 387 +- src/_config.yml | 21 +- src/_static/myfile.css | 38 - src/_toc.yml | 61 +- src/contact.md | 29 +- src/dataset_examples.md | 49 +- src/dependencies.md | 51 +- src/folders_and_files/derivatives.md | 233 +- src/folders_and_files/files.md | 660 +-- src/folders_and_files/folders.md | 194 +- src/folders_and_files/metadata.md | 420 +- src/glossary.md | 203 +- src/images/BIDS-minder.svg | 4306 ------------------- src/images/BIDS.minder | 429 -- src/index.md | 87 +- src/links.md | 47 +- src/publications.md | 41 +- src/references.bib | 8 - src/talks.md | 50 +- src/tutorials/annotation.md | 192 +- src/tutorials/asl.md | 70 +- src/tutorials/ieeg.md | 175 +- src/tutorials/media/Pic_1.png | Bin 284746 -> 0 bytes src/tutorials/media/Pic_2.png | Bin 130729 -> 0 bytes src/tutorials/media/Pic_3.png | Bin 90439 -> 0 bytes src/tutorials/media/Pic_4.png | Bin 134115 -> 0 bytes src/tutorials/media/Pic_5.png | Bin 161113 -> 0 bytes src/tutorials/media/README.md | 1 - src/tutorials/mri.md | 30 +- src/tutorials/pet.md | 1170 +---- src/tutorials/tutorials.md | 45 +- src/validator.md | 187 +- tools/bids-specification | 1 - tools/bids-website | 1 - tools/no-bad-latin.py | 161 - tools/print_bep_list.py | 40 - tools/print_filename_templates.py | 61 - tools/pull_files.py | 68 - tools/requirements.txt | 1 - tox.ini | 2 - 78 files changed, 85 insertions(+), 10281 deletions(-) delete mode 100644 .codespellrc delete mode 100644 .faq/FAQ.md delete mode 100644 .faq/suggest.md delete mode 100644 .github/workflows/build_book_on_pr.yml delete mode 100644 .github/workflows/check_md_links.yml delete mode 100644 .github/workflows/codespell.yml delete mode 100644 .github/workflows/faqtory.yml delete mode 100644 .github/workflows/miss_hit.yml delete mode 100644 .github/workflows/no-bad-latin.yml delete mode 100644 .gitmodules delete mode 100644 faq.yml delete mode 100644 mlc_config.json delete mode 100644 pyproject.toml delete mode 100644 questions/README.md delete mode 100644 questions/eeg_biosemi.question.md delete mode 100644 questions/eeg_filters.question.md delete mode 100644 questions/general_bep.question.md delete mode 100644 questions/general_cite.question.md delete mode 100644 questions/general_convert.question.md delete mode 100644 questions/general_convert_nifti.question.md delete mode 100644 questions/general_excel.question.md delete mode 100644 questions/general_hyperscanning.question.md delete mode 100644 questions/general_json.question.md delete mode 100644 questions/general_license.question.md delete mode 100644 questions/general_micro.question.md delete mode 100644 questions/general_nwb.question.md delete mode 100644 questions/general_schema.question.md delete mode 100644 questions/general_session.question.md delete mode 100644 questions/general_what.question.md delete mode 100644 questions/mri_defacing.question.md delete mode 100644 questions/pheno_epilepsy.question.md delete mode 100644 questions/pheno_pheno.question.md delete mode 100644 requirements.txt delete mode 100644 requirements_dev.txt delete mode 100644 src/_static/myfile.css delete mode 100644 src/images/BIDS-minder.svg delete mode 100644 src/images/BIDS.minder delete mode 100644 src/tutorials/media/Pic_1.png delete mode 100644 src/tutorials/media/Pic_2.png delete mode 100644 src/tutorials/media/Pic_3.png delete mode 100644 src/tutorials/media/Pic_4.png delete mode 100644 src/tutorials/media/Pic_5.png delete mode 100644 src/tutorials/media/README.md delete mode 160000 tools/bids-specification delete mode 160000 tools/bids-website delete mode 100755 tools/no-bad-latin.py delete mode 100644 tools/print_bep_list.py delete mode 100644 tools/print_filename_templates.py delete mode 100644 tools/pull_files.py delete mode 100644 tools/requirements.txt delete mode 100644 tox.ini diff --git a/.codespellrc b/.codespellrc deleted file mode 100644 index 1ee898ea..00000000 --- a/.codespellrc +++ /dev/null @@ -1,7 +0,0 @@ -[codespell] -skip = .git,*.pdf,*.svg,*.min.js -# TE -- echo time -# nin -- \nin - deficiency in codespell -# ans -- there is matlab involved -# dentifier -- used in **I**dentifier and codespell is not aware of markdown modifiers -ignore-words-list = te,nin,ans,dentifier diff --git a/.faq/FAQ.md b/.faq/FAQ.md deleted file mode 100644 index 2fcc6b93..00000000 --- a/.faq/FAQ.md +++ /dev/null @@ -1,42 +0,0 @@ - -# Frequently Asked Questions - -As this starter-kit grows it gets harder to know where to find information, -so this page is a collection of frequently asked questions. - -Please add to this list! - -It will always be 🚧 **in construction** 🚧 -and we really encourage everyone to update it to be more useful. -If there's a question you've asked or answered more than twice -then it's an FAQ and it should be in the repository. - -Ideally the questions will link to an answer elsewhere in the repository -to maximise the different ways of finding out more about BIDS. - -```{note} -For questions related to the BIDS apps, -please visit [the BIDS apps website](https://bids-apps.neuroimaging.io/dev_faq/). -``` - ---- - - - -{%- for question in questions %} - -## {{ question.title }} - -{{ question.body }} - -{%- endfor %} - -
- -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) diff --git a/.faq/suggest.md b/.faq/suggest.md deleted file mode 100644 index 0a923399..00000000 --- a/.faq/suggest.md +++ /dev/null @@ -1,20 +0,0 @@ -{%- if questions -%} -{% if questions|length == 1 %} -We found the following entry in the [FAQ]({{ faq_url }}) which you may find helpful: -{%- else %} -We found the following entries in the [FAQ]({{ faq_url }}) which you may find helpful: -{%- endif %} - -{% for question in questions %} -- [{{ question.title }}]({{ faq_url }}#{{ question.slug }}) -{%- endfor %} - -Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review. - -{%- else -%} -Thank you for your issue. Give us a little time to review it. - -PS. You might want to check the [FAQ]({{ faq_url }}) if you haven't done so already. -{%- endif %} - -This is an automated reply, generated by [FAQtory](https://github.com/willmcgugan/faqtory) diff --git a/.github/workflows/build_book_on_pr.yml b/.github/workflows/build_book_on_pr.yml deleted file mode 100644 index 0a05160a..00000000 --- a/.github/workflows/build_book_on_pr.yml +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: build-book - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -# run on pushes and pull requests to main -on: - pull_request: - branches: - - main - -# This job installs dependencies, build the book, and pushes it to `gh-pages` - -jobs: - build-book: - if: (github.event.pull_request) && !contains(github.head_ref, 'all-contributors') - strategy: - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - python_version: ['3.10', '3.11', '3.12'] - fail-fast: false # Don't cancel all jobs if one fails - - runs-on: ${{ matrix.os }} - - steps: - - name: Checkout-repository - uses: actions/checkout@v4 - with: - submodules: recursive - fetch-depth: 0 - - - name: Setup Python ${{ matrix.python_version }} - uses: actions/setup-python@v5 - with: - python-version: ${{ matrix.python_version }} - - - name: Install dependencies - run: | - python -m pip install --upgrade pip setuptools wheel - pip install -r requirements.txt - - # Build the book - - name: Build the book - run: make book diff --git a/.github/workflows/check_md_links.yml b/.github/workflows/check_md_links.yml deleted file mode 100644 index 18f22a7b..00000000 --- a/.github/workflows/check_md_links.yml +++ /dev/null @@ -1,28 +0,0 @@ ---- -name: Check Markdown links - -# checking for any dead links in markdown files - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -on: - push: - branches: - - main - pull_request: - branches: ['*'] - -jobs: - markdown-link-check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: gaurav-nelson/github-action-markdown-link-check@v1 - with: - config-file: ./mlc_config.json - folder-path: ./src/, templates - use-verbose-mode: yes - max-depth: -1 - file-path: ./README.md, ./CONTRIBUTING.md, ./CODE_OF_CONDUCT.md diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml deleted file mode 100644 index 7bd4ce54..00000000 --- a/.github/workflows/codespell.yml +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: Codespell - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -on: - push: - branches: [main] - pull_request: - branches: [main] - -jobs: - codespell: - name: Check for spelling errors - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Codespell - uses: codespell-project/actions-codespell@v2 diff --git a/.github/workflows/deploy_book.yml b/.github/workflows/deploy_book.yml index b8b4ba76..304d895e 100644 --- a/.github/workflows/deploy_book.yml +++ b/.github/workflows/deploy_book.yml @@ -30,9 +30,7 @@ jobs: with: python-version: '3.12' - name: Install dependencies - run: | - python -m pip install --upgrade pip setuptools wheel - pip install -r requirements.txt + run: pip install jupyter-book # Build the book - name: Build the book diff --git a/.github/workflows/faqtory.yml b/.github/workflows/faqtory.yml deleted file mode 100644 index ebf04cf8..00000000 --- a/.github/workflows/faqtory.yml +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: FAQtory issues - -on: - - issues: - types: [opened] - -jobs: - add-comment: - - runs-on: ubuntu-latest - - permissions: - issues: write - - steps: - - - uses: actions/checkout@v4 - with: - ref: main - - - name: Install FAQtory - run: pip install FAQtory - - - name: Run Suggest - run: faqtory suggest "${{ github.event.issue.title }}" > suggest.md - - - name: Read suggest.md - id: suggest - uses: juliangruber/read-file-action@v1 - with: - path: ./suggest.md - - - name: Suggest FAQ - uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 - with: - issue-number: ${{ github.event.issue.number }} - body: ${{ steps.suggest.outputs.content }} diff --git a/.github/workflows/miss_hit.yml b/.github/workflows/miss_hit.yml deleted file mode 100644 index aafe4978..00000000 --- a/.github/workflows/miss_hit.yml +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: miss_hit - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -on: - push: - branches: - - main - paths: - - '**.m' - pull_request: - branches: ['*'] - paths: - - '**.m' - -jobs: - - miss_hit: - - runs-on: ubuntu-latest - - strategy: - matrix: - command: [mh_style, mh_metric --ci && mh_lint] - fail-fast: true # cancel all jobs if one fails - - steps: - - - uses: actions/checkout@v4 - with: - submodules: recursive - fetch-depth: 0 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.12' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip setuptools - pip3 install -r requirements_dev.txt - - - name: ${{ matrix.command }} - run: | - ${{ matrix.command }} diff --git a/.github/workflows/no-bad-latin.yml b/.github/workflows/no-bad-latin.yml deleted file mode 100644 index e84c2750..00000000 --- a/.github/workflows/no-bad-latin.yml +++ /dev/null @@ -1,63 +0,0 @@ ---- -# This action initially adopted from The Turing Way from in October 2020. -# doi:10.5281/zenodo.3233853 -# https://github.com/alan-turing-institute/the-turing-way/blob/af98c94/.github/workflows/no-bad-latin.yml -# -# This action triggers the script tools/no-bad-latin.py to and will throw an error if any latin expression (like e.g. or i.e.) is detected: -# -# This action will be triggered -# - on a push to master -# - on a PR to the master branch and will only check files that were modified in src - -name: Check for Latin Phrases - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -# Decide when to run the tests -# -# This configuration sets the test to run on pushes to master -# and on pull requests that are opened to master -on: - push: - branches: - - main - pull_request: - branches: ['*'] - -# Set up the Continuous Integration job -jobs: - latin-phrases: - # Run on the latest Ubuntu distribution - runs-on: ubuntu-latest - # This section collects together the steps involved in running the test - steps: - # Checkout the repository. Relies on another GH-Action. - - uses: actions/checkout@v4 - with: - submodules: recursive - fetch-depth: 0 - # Set up the Python version. Relies on another GH-Action. - - name: Setup Python - uses: actions/setup-python@v5 - with: - python-version: '3.12' - # Install Python dependencies - - name: Install dependencies - working-directory: ./tools - run: | - python -m pip install --upgrade pip - python -m pip install -r requirements.txt - # Run a Python script - - name: Run Python script to check for latin phrases - Master - working-directory: ./tools - if: github.event_name == 'push' && github.ref == 'refs/heads/master' - run: | - python no-bad-latin.py - - - name: Run Python script to check for latin phrases - Pull Request - working-directory: ./tools - if: github.event.pull_request - run: | - python no-bad-latin.py --pull-request ${{ github.event.pull_request.number }} diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index ee4f6314..00000000 --- a/.gitmodules +++ /dev/null @@ -1,8 +0,0 @@ -[submodule "tools/bids-specification"] - path = tools/bids-specification - url = https://github.com/bids-standard/bids-specification.git - datalad-url = https://github.com/bids-standard/bids-specification.git -[submodule "tools/bids-website"] - path = tools/bids-website - url = https://github.com/bids-standard/bids-website.git - datalad-url = https://github.com/bids-standard/bids-website.git diff --git a/Makefile b/Makefile index f642c42e..3d71a59a 100644 --- a/Makefile +++ b/Makefile @@ -29,23 +29,11 @@ help: clean: rm -fr src/_build/ -update_bep_list: - python tools/print_bep_list.py - -update_faq: update_bep_list - faqtory build - -update_filename_templates: - python tools/print_filename_templates.py - -book: clean update_faq update_filename_templates ## build the book +book: clean ## build the book jupyter-book build src view: book ## view the book $(BROWSER) $$PWD/src/_build/html/index.html -latin_check: - cd tools && python no-bad-latin.py - test: ## build the book and tests the links - jupyter-book build src -W --builder linkcheck + jupyter-book build src --builder linkcheck diff --git a/README.md b/README.md index 749db594..172efd09 100755 --- a/README.md +++ b/README.md @@ -2,27 +2,7 @@ [![All Contributors](https://img.shields.io/badge/all_contributors-43-orange.svg?style=flat-square)](#contributors-) -
-

The BIDS starter-kit

-

- https://bids-standard.github.io/bids-starter-kit/ -

-
- -## Contributing - -There are many ways to get in touch with us! -Please see our [Contact Page](https://bids-standard.github.io/bids-starter-kit/contact.html) -for all the details. - -To find out more about all the different ways to contribute to the BIDS Starter Kit, -check out our [**contributing guidelines**](https://bids-standard.github.io/bids-starter-kit/CONTRIBUTING.html). -They'll tell help you figure out how to -[contribute via GitHub](https://bids-standard.github.io/bids-starter-kit/CONTRIBUTING.html#contributing-through-github), -how to make a change [using issues](https://bids-standard.github.io/bids-starter-kit/CONTRIBUTING.html#where-to-start-issue-labels) -(you can also check out GitHub's help on -[issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues)) and a -[pull request](https://bids-standard.github.io/bids-starter-kit/CONTRIBUTING.html#making-a-change-with-a-pull-request). +# The Starter-kit has moved to the new BIDS website. ## Contributors ✨ diff --git a/faq.yml b/faq.yml deleted file mode 100644 index 022ab989..00000000 --- a/faq.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -# FAQtory settings - -faq_url: https://bids-standard.github.io/bids-starter-kit/faq.html # Replace this with the URL to your FAQ.md! - -questions_path: ./questions # Where questions should be stored -output_path: ./src/FAQ.md # Where FAQ.md should be generated -templates_path: .faq # Path to templates diff --git a/mlc_config.json b/mlc_config.json deleted file mode 100644 index 7abc0fc0..00000000 --- a/mlc_config.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "ignorePatterns": [ - { - "pattern": "^https://docs.github.com/.*" - }, - { - "pattern": "^https://guides.github.com/.*" - }, - { - "pattern": "^https://github.com/.*" - } - ] -} diff --git a/pyproject.toml b/pyproject.toml deleted file mode 100644 index 20da40b1..00000000 --- a/pyproject.toml +++ /dev/null @@ -1,12 +0,0 @@ -[tool.black] -line-length = 99 -target-version = ['py39'] -exclude = ''' -( - /( - tools/bids-specification # exclude a few common directories in the root of the project - | \.git - | env - )/ -) -''' diff --git a/questions/README.md b/questions/README.md deleted file mode 100644 index e733072f..00000000 --- a/questions/README.md +++ /dev/null @@ -1,6 +0,0 @@ - -# Questions - -Your questions should go in this directory. - -Question files should be named with the extension ".question.md". diff --git a/questions/eeg_biosemi.question.md b/questions/eeg_biosemi.question.md deleted file mode 100644 index b90f7452..00000000 --- a/questions/eeg_biosemi.question.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "EEG: How to specify EEGReference and EEGGround for Biosemi referencing scheme?" ---- - -Reference and ground electrodes for EEG data can usually be specified -using the `EEGReference` and `EEGGround` fields -in the modality specific sidecar file `_eeg.json`. -Both fields accept a string value such as `"Placed on Cz"`. - -However, some manufacturers use special referencing schemes -such as the combination of a "Common Mode Sense" (CMS) and a "Driven Right Leg" (DRL) electrode. -This is the case for Biosemi, as further documented on -[their website](https://www.biosemi.com/faq/cms&drl.htm). - -For a formatted example on how to deal with this in the BIDS context, -please see this -[template](https://github.com/bids-standard/bids-starter-kit/blob/main/templates/sub-01/ses-01/eeg/sub-01_ses-01_task-ReferenceExample_eeg.json). diff --git a/questions/eeg_filters.question.md b/questions/eeg_filters.question.md deleted file mode 100644 index 12160255..00000000 --- a/questions/eeg_filters.question.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "EEG: How to format Hardware and Software filter fields in a .json?" ---- - -In the modality specific sidecar file `_eeg.json`, we can specify the software -and hardware filters that were applied during the collection or processing of the data. -Generally, there are two accepted formats for that: - -1. a string containing `"n/a"`, to show that no filter was used or the - information on the filter is not available. -2. a json object containing one object per filter. This filter-specific object - contains key-value pairs to describe filter parameters. As per BIDS, all - frequencies SHOULD be in Hz. For example a single hardware filter could be - specified as: - -```json -"HardwareFilters": {"HighpassFilter": {"CutoffFrequency": 0.1}} -``` - -For a formatted example on how to deal with this in the BIDS context, please see -this -[template](https://github.com/bids-standard/bids-starter-kit/blob/main/templates/sub-01/ses-01/eeg/sub-01_ses-01_task-FilterExample_eeg.json). diff --git a/questions/general_bep.question.md b/questions/general_bep.question.md deleted file mode 100644 index f5316fd2..00000000 --- a/questions/general_bep.question.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "General: Is your data type not covered in the current BIDS specification?" ---- - -BIDS extensions proposals [(BEPs)](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification) -aim to extend the BIDS specification to new data types. -A list of extensions proposals can be found below. - -Guidelines for contributing to these extensions or starting your own can be found -in the [BIDS Extension Proposals Guide](https://bids-extensions.readthedocs.io/en/latest/). - -If only part of your data is covered under BIDS, an option to allow additional files -currently not covered in BIDS to pass the validator is -the [.bidsignore](https://github.com/bids-standard/bids-validator/blob/master/bids-validator/README.md) file, -which works just like [.gitignore](https://git-scm.com/docs/gitignore). -It allows you to list all the files (or directories, with wildcards) -that are not BIDS compliant and should be ignored by the validator. -Of course you should still try to adhere to upcoming BEPs -and the general BIDS philosophy for file names and metadata where possible, -but this gives a little extra flexibility. - - - -### raw - -- BEP004: [Susceptibility Weighted Imaging (SWI)](https://bids.neuroimaging.io/bep004) -- BEP020: [Eye Tracking including Gaze Position and Pupil Size](https://bids.neuroimaging.io/bep020) -- BEP022: [Magnetic Resonance Spectroscopy (MRS)](https://bids.neuroimaging.io/bep022) -- BEP024: [Computed Tomography scan (CT)](https://bids.neuroimaging.io/bep024) -- BEP026: [Microelectrode Recordings](https://bids.neuroimaging.io/bep026) -- BEP032: [Animal electrophysiology](https://bids.neuroimaging.io/bep032) -- BEP033: [Advanced Diffusion Weighted Imaging (aDWI)](https://bids.neuroimaging.io/bep033) -- BEP036: [Phenotypic Data Guidelines](https://bids.neuroimaging.io/bep036) -- BEP037: [Non-Invasive Brain Stimulation (NIBS)](https://bids.neuroimaging.io/bep037) -- BEP038: [Atlases](https://bids.neuroimaging.io/bep038) -- BEP039: [Dimensionality reduction-based networks](https://bids.neuroimaging.io/bep039) -- BEP040: [Functional Ultrasound (fUS)](https://bids.neuroimaging.io/bep040) -### derivative - -- BEP011: [Structural preprocessing derivatives](https://bids.neuroimaging.io/bep011) -- BEP012: [Functional preprocessing derivatives](https://bids.neuroimaging.io/bep012) -- BEP014: [Affine transformations and nonlinear field warps](https://bids.neuroimaging.io/bep014) -- BEP016: [Diffusion weighted imaging derivatives](https://bids.neuroimaging.io/bep016) -- BEP017: [Generic BIDS connectivity data schema](https://bids.neuroimaging.io/bep017) -- BEP021: [Common Electrophysiological Derivatives](https://bids.neuroimaging.io/bep021) -- BEP023: [PET Preprocessing derivatives](https://bids.neuroimaging.io/bep023) -- BEP034: [Computational modeling](https://bids.neuroimaging.io/bep034) -- BEP035: [Modular extensions for individual participant data mega-analyses with non-compliant derivatives](https://bids.neuroimaging.io/bep035) -- BEP041: [Statistical Model Derivatives](https://bids.neuroimaging.io/bep041) -- -### metadata -- BEP028: [Provenance](https://bids.neuroimaging.io/bep028) -- BEP034: [Computational modeling](https://bids.neuroimaging.io/bep034) -- -### file format diff --git a/questions/general_cite.question.md b/questions/general_cite.question.md deleted file mode 100644 index 9ae948b3..00000000 --- a/questions/general_cite.question.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "General: How can I cite BIDS?" ---- - -See the specification website for the -[main publications](https://bids-specification.readthedocs.io/en/latest/01-introduction.html#citing-bids) -related to BIDS and its extensions. - -BIDS references are centralized in a [zotero group](https://www.zotero.org/groups/5111637/bids). diff --git a/questions/general_convert.question.md b/questions/general_convert.question.md deleted file mode 100644 index a8b83b26..00000000 --- a/questions/general_convert.question.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "General: How do I convert my data to BIDS?" ---- - -We strongly recommend you pick a BIDS converter to help you convert your data. - -A list of converters can be found [on the BIDS website](https://bids.neuroimaging.io/benefits.html#converters) - -Also look at [the list of tutorials and information about conversions](./tutorials/tutorials.md). diff --git a/questions/general_convert_nifti.question.md b/questions/general_convert_nifti.question.md deleted file mode 100644 index cdad7e08..00000000 --- a/questions/general_convert_nifti.question.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "General: I only have nifti files and no dicom. Can I still create a BIDS dataset?" ---- - -In theory yes, but it is possible that you will be missing some metadata that is required by the BIDS specification. - -A couple of BIDS converters can work with nifti files: - -- bidscoin -- bidsme -- explore asl -- data2bids - -See the list of converters [here](https://bids.neuroimaging.io/benefits.html#mri-and-pet-converters). - -**However**... - -- They may not work with the datatype you have - (for example not sure that explore ASL can deal with `func` data). -- Many of them still expect that you have a json side car for each nifti - (BIDSme for example - from the top of my head). -- They may expect a certain input structure to work efficiently, - so we may have to move files around. - - - -### Regarding the "missing" JSON files - -Depending on the datatype you are dealing with this can be more of less annoying. - -2 examples: - -For the most typical `anat` files, -they don't have any REQUIRED metadata, -so you could have just the data files without any accompanying JSON. -If you get into more exotic anat files (like for quantitative MRI) -then this may become a problem. - -For `func` files you only need `TaskName` and `RepetitionTime` -and the former you can decide what it is and the latter should be in the Nifti header. -So you should be OKish there too. - -Obviously you will be missing some metadata that would be required -for some type of preprocessing (like slice timing info). - -### Tips - -- If you have the PDF with the details of acquisition sequence or a method section - from a paper with that data, you could "recover" some extra metadata. -- SPM dicom import tool usually leaves a couple of metadata in a description field of the nifti header. - That can be a problem for data anonymisation but may help you in your case if this is the tool that was used. - See an example [here](https://github.com/PeerHerholz/BIDSonym/issues/41#issue-768636869) -- If you have to script tings manually rather than using a converter, - remember to use pybids [path construction tools](https://bids-standard.github.io/pybids/examples/pybids_tutorial.html#path-construction) or the [bids matlab equivalent](https://github.com/bids-standard/bids-matlab/blob/master/examples/03_BIDS-Matlab_filenames_and_metadata.ipynb) to make your life easier when constructing bids valid filenames. diff --git a/questions/general_excel.question.md b/questions/general_excel.question.md deleted file mode 100644 index dd2b6df3..00000000 --- a/questions/general_excel.question.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "General: How to import Excel files to TSV file?" ---- - -See [our sections on TSV files](./folders_and_files/metadata.md#tsv-files) for more information. - -See also this bids tool to import and export a `participants.tsv` file: -[bids-matlab-tools](https://github.com/sccn/bids-matlab-tools/blob/master/bids_spreadsheet2participants.m) diff --git a/questions/general_hyperscanning.question.md b/questions/general_hyperscanning.question.md deleted file mode 100644 index 9c061133..00000000 --- a/questions/general_hyperscanning.question.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "General: How should I organize data for hyperscanning data?" ---- - -Hyperscanning is simultaneous fMRI with multiple subjects (see this [paper](https://doi.org/10.1006/nimg.2002.1150)). - -- See this [issue](https://github.com/bids-standard/bids-specification/issues/402) - in the bids specification repository for typical hyperscanning data. - -See an example below with fMRI data: - -``` -sub-01/ - ses-dyadic1/ - func/ - sub-01_ses-dyadic1_* -sub-02/ - ses-dyadic1/ - func/ - sub-02_ses-dyadic1_* -sub-03/ - ses-dyadic2/ - func/ - sub-03_ses-dyadic2_* -sub-04/ - ses-dyadic2/ - func/ - sub-04_ses-dyadic2_* -``` - -- See this [post on neurostars](https://neurostars.org/t/bids-structure-for-longitudinal-dyadic-data/26173) - for hyperscanning longitunal data. - -See an example below with fMRI data: - -``` -sub-S001/ - ses-1/ - func/ - sub-S001_ses-1_task-video_acq-dyad001_bold.nii.gz - ses-2/ -sub-S002/ - ses-1/ - func/ - sub-S002_ses-1_task-video_acq-dyad001_bold.nii.gz - ses-2/ -sub-S003/ - ses-1/ - func/ - sub-S003_ses-1_task-video_acq-dyad002_bold.nii.gz - ses-2/ -``` - - -- See this [thread on the bids discussion forum](https://groups.google.com/g/bids-discussion/c/v660DuzOf3w/m/q-0PLHt5BgAJ) diff --git a/questions/general_json.question.md b/questions/general_json.question.md deleted file mode 100644 index 98ce7bf8..00000000 --- a/questions/general_json.question.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "General: What is a `json` file?" ---- - -You can find more information about `json` (and `tsv`) files in the -[Metadata-file-formats](./folders_and_files/metadata.md#json) page. diff --git a/questions/general_license.question.md b/questions/general_license.question.md deleted file mode 100644 index a2b17324..00000000 --- a/questions/general_license.question.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "General: What liense should I choose for my dataset?" ---- - -If you want to know more about what license to choose for your dataset, -see the [turing way](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-data.html#data-licenses) -page dedicated to this topic. - -If you plan to put your dataset on [openneuro](https://openneuro.org/), -you should use a CC0 or a PDDL license as explained in their [FAQ](https://openneuro.org/faq). diff --git a/questions/general_micro.question.md b/questions/general_micro.question.md deleted file mode 100644 index 787edaa7..00000000 --- a/questions/general_micro.question.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "General: How to specify the micro sign in MATLAB?" ---- - -BIDS requires physical units to be specified according to the SI unit symbol and -possibly prefix symbol (for example: mV, ΞΌV for milliVolt and microVolt). - -The symbol used to indicate `Β΅` has unicode U+00B5, which is in MATLAB: - -```matlab -char(181) -``` - -or - -```matlab -native2unicode(181, 'latin1') -``` diff --git a/questions/general_nwb.question.md b/questions/general_nwb.question.md deleted file mode 100644 index b67212f4..00000000 --- a/questions/general_nwb.question.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "General: Can I combine BIDS and neurodata without border (NWB)?" ---- - -BIDS and [NWB](https://www.nwb.org/) are compatible. - -An NWB data file is an allowed format in the iEEG-BIDS data structure. -This means that one subject (AAA) with a session (BBB) -can have a BIDS folder with raw iEEG data in NWB format: - -``` -/sub-AAA/ses-BBB/ieeg/sub-AAA_ses-BBB_task-rest_ieeg.nwb -``` - -The same subject can have another session (CCC) with raw fMRI data in BIDS: - -``` -/sub-AAA/ses-CCC/func/sub-AAA_ses-CCC_task-rest_bold.nii.gz -``` diff --git a/questions/general_schema.question.md b/questions/general_schema.question.md deleted file mode 100644 index ce24e478..00000000 --- a/questions/general_schema.question.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "General: Is there a machine readable version of the BIDS specification?" ---- - -Yes. The BIDS specification exist as a schema. -The BIDS schema is a machine readable representation of the BIDS Standard. -It is (by and large) the BIDS Specification, but written in a declarative form. - -The BIDS schema is available in two machine readable formats: - -- as a set of [YAML](https://en.wikipedia.org/wiki/YAML) files in the [BIDS specification repository](https://github.com/bids-standard/bids-specification/src/schema) -- as a [single json file](https://bids-specification.readthedocs.io/en/stable/schema.json) - -A light-weight introduction to the schema can be found [here](https://bids-extensions.readthedocs.io/en/latest/schema/). - -A full description of the schema can be found on this [website](https://bidsschematools.readthedocs.io/en/latest/?badge=latest) -where you will also find the documentation for the python package -to interact with the schema, [bidsschematools](https://pypi.org/project/bidsschematools/). diff --git a/questions/general_session.question.md b/questions/general_session.question.md deleted file mode 100644 index e9da6f04..00000000 --- a/questions/general_session.question.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "General: I had to split the testing of one of my participants across 2 days, should I use 2 different session folders to organize the data of that participant?" -reference: ---- - -(faq_session)= - -No. The `session` level in the BIDS folder hierarchy can be used to group data -that go "logically" together: this means that you can put in the same `session` folder -data that were acquired on different days, -but that are "linked" to one another in a way that make sense to how you want to organize your data. - -If you want to keep track of what data was acquired when you can use the -[`scans.tsv` files](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#scans-file). - -For some examples, see this -[issue in the bids-starter kit](https://github.com/bids-standard/bids-starter-kit/issues/193). - -If you deal with EEG data, you may want to read this -[comment in another issue](https://github.com/bids-standard/bids-starter-kit/issues/265#issuecomment-1082240834) -as well before considering combining recordings acquired on different occasions -within the same `session` folder. diff --git a/questions/general_what.question.md b/questions/general_what.question.md deleted file mode 100644 index dd9c704b..00000000 --- a/questions/general_what.question.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "General: What does [this word] mean?" ---- - -We're building a glossary to de-jargonise some of the terms you need to know to -work with data in BIDS format. Check it out [here](./glossary.md). diff --git a/questions/mri_defacing.question.md b/questions/mri_defacing.question.md deleted file mode 100644 index f05673bb..00000000 --- a/questions/mri_defacing.question.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "MRI: What defacing tools can I use?" ---- - -If you want to share your BIDS data set, chances are that you will have to anonymize it -and therefore prevent identification of the participants from their anatomical scans. -You will need to de-identification (or deface) the anatomical images. -There are several options to do that - -- If you already have a valid BIDS data set you can simply use the - [BIDSonym BIDS app](https://github.com/PeerHerholz/BIDSonym) on it. To do - that it relies on several tools that you can also use before you have - finalized your BIDS data set - - [Pydeface](https://github.com/poldracklab/pydeface) - - [MRI deface](https://surfer.nmr.mgh.harvard.edu/fswiki/mri_deface) - - [Quickshear](https://github.com/nipy/quickshear) - -Otherwise you can also use: - -- [Fieldtrip](http://www.fieldtriptoolbox.org/faq/how_can_i_anonymize_an_anatomical_mri/) - under matlab can do it. -- SPM8 and SPM12: when in the batch editor go to: - `SPM menu --> Util --> Deface` diff --git a/questions/pheno_epilepsy.question.md b/questions/pheno_epilepsy.question.md deleted file mode 100644 index f1c61b4c..00000000 --- a/questions/pheno_epilepsy.question.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Phenotype: Is there a standard for epilepsy phenotypes?" ---- - -Yes, open this -[epilepsyClassification2017](https://github.com/bids-standard/bids-starter-kit/blob/main/interactiveTreeVisualization/epilepsyClassification2017/tree.html) -and follow the examples in the -[phenotype templates](https://github.com/bids-standard/bids-starter-kit/tree/main/templates/phenotype). diff --git a/questions/pheno_pheno.question.md b/questions/pheno_pheno.question.md deleted file mode 100644 index 6e1e5a33..00000000 --- a/questions/pheno_pheno.question.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Phenotype: How can I store subject phenotypic data?" ---- - -In the phenotype folder, according to the details provided for -[phenotypes](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#phenotypic-and-assessment-data): - -``` -bids-root - phenotype -``` - -Please the see work on the [BIDS extension proposal for phenotypes](https://bids.neuroimaging.io/bep036) -for more guidelines. diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 5156f4ae..00000000 --- a/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -jupyter-book -Jinja2 -faqtory -ruamel.yaml -tools/bids-specification/tools/schemacode[render] diff --git a/requirements_dev.txt b/requirements_dev.txt deleted file mode 100644 index ebcc5f20..00000000 --- a/requirements_dev.txt +++ /dev/null @@ -1,4 +0,0 @@ -pre-commit -black -miss_hit --r requirements.txt diff --git a/src/CONTRIBUTING.md b/src/CONTRIBUTING.md index 5ee61790..71b4a1bb 100644 --- a/src/CONTRIBUTING.md +++ b/src/CONTRIBUTING.md @@ -5,7 +5,7 @@ The point of this starter kit is to **welcome new users and contributors to the BIDS community**. We hope that these guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, -please let us know through one of the many ways to [get in touch](#get-in-touch). +please let us know through one of the many ways to [get in touch](./contact.md). ## Joining the community @@ -55,7 +55,7 @@ The list of labels for current issues can be found - [![Question](https://img.shields.io/badge/-question-cc317c.svg)][labels-question] _These issues contain a question that you'd like to have answered._ - There are [lots of ways to ask questions](#get-in-touch) + There are [lots of ways to ask questions](./contact.md) but opening an issue is a great way to start a conversation and get your answer. - [![good-first-issue](https://img.shields.io/badge/-good%20first%20issue-1b3487.svg)][labels-firstissue] @@ -133,32 +133,10 @@ We appreciate all contributions to the BIDS Starter Kit. **THANK YOU** for helping us build this useful resource. ✨ 🌟 πŸ’« -If you're updating the [code](#code) or the [templates](#templates), +If you're updating the [code](./#code) or the [templates](#templates), the following steps are a guide to help you contribute in a way that will be easy for everyone to review and accept with ease 😎. -### Requirements - -To make a contribution you will need to have: - -- a github account (see above) -- python 3.8 or higher -- a code editor like vs-code - -To make edits you will need to: - -- fork the bids-starter-kit repository -- clone your fork to your computer -- install the dependencies -- make changes -- push your changes to your fork -- submit a pull request - - ### [Fork][github-fork] the [BIDS Starter Kit repository][bids-starterkit-repo] to your profile @@ -169,19 +147,6 @@ so it's a safe space to explore edits to the code! Make sure to [keep your fork up to date][github-syncfork] with the upstream repository, otherwise you can end up with lots of dreaded [merge conflicts][github-mergeconflicts]. -### Clone your fork to your computer - -```bash -git clone --recurse-submodules https://github.com/YOUR_USER_NAME/BIDS-Starter-Kit.git -``` - -### Install the dependencies and set up pre-commit hooks - -```bash -pip install -r requirements_dev.txt -pre-commit install -``` - ### Make the changes you've discussed Try to keep the changes focused. @@ -213,17 +178,6 @@ git add . git commit -m "your commit message" ``` - - -### view your changes - -```bash -jupyter-book build src -``` - -This will build the book in the `src/_build` folder. -You can then open the `src/_build/html/index.html` file in your browser to view the changes. - ### Submit a [pull request][github-pullrequest] A member of the BIDS Starter Kit team will review your changes @@ -249,7 +203,7 @@ but please [get in touch](#get-in-touch) if you have any questions 🎈.
-## Code ([link][bids-starterkit-repo]) +## Code This repository is under development, but we hope that it becomes a useful place for people to share @@ -269,7 +223,7 @@ We are using the Miss_hit linter to help us keep out matlab "clean". You can find more information on how to set it up and use it on the bids-matlab [contributing guidelines](https://github.com/bids-standard/bids-matlab/blob/master/CONTRIBUTING.md#matlab-code-style-guide-and-quality). -### Templates ([link][bids-starterkit-repo]) +### Templates This repository is under development, but we aim to have two templates for each BIDS sidecar file: diff --git a/src/FAQ.md b/src/FAQ.md index 16af4668..cf84abff 100644 --- a/src/FAQ.md +++ b/src/FAQ.md @@ -1,389 +1,4 @@ # Frequently Asked Questions -As this starter-kit grows it gets harder to know where to find information, -so this page is a collection of frequently asked questions. - -Please add to this list! - -It will always be 🚧 **in construction** 🚧 -and we really encourage everyone to update it to be more useful. -If there's a question you've asked or answered more than twice -then it's an FAQ and it should be in the repository. - -Ideally the questions will link to an answer elsewhere in the repository -to maximise the different ways of finding out more about BIDS. - -```{note} -For questions related to the BIDS apps, -please visit [the BIDS apps website](https://bids-apps.neuroimaging.io/dev_faq/). -``` - ---- - - - -## EEG: How to format Hardware and Software filter fields in a .json? - -In the modality specific sidecar file `_eeg.json`, we can specify the software -and hardware filters that were applied during the collection or processing of the data. -Generally, there are two accepted formats for that: - -1. a string containing `"n/a"`, to show that no filter was used or the - information on the filter is not available. -2. a json object containing one object per filter. This filter-specific object - contains key-value pairs to describe filter parameters. As per BIDS, all - frequencies SHOULD be in Hz. For example a single hardware filter could be - specified as: - -```json -"HardwareFilters": {"HighpassFilter": {"CutoffFrequency": 0.1}} -``` - -For a formatted example on how to deal with this in the BIDS context, please see -this -[template](https://github.com/bids-standard/bids-starter-kit/blob/main/templates/sub-01/ses-01/eeg/sub-01_ses-01_task-FilterExample_eeg.json). - -## EEG: How to specify EEGReference and EEGGround for Biosemi referencing scheme? - -Reference and ground electrodes for EEG data can usually be specified -using the `EEGReference` and `EEGGround` fields -in the modality specific sidecar file `_eeg.json`. -Both fields accept a string value such as `"Placed on Cz"`. - -However, some manufacturers use special referencing schemes -such as the combination of a "Common Mode Sense" (CMS) and a "Driven Right Leg" (DRL) electrode. -This is the case for Biosemi, as further documented on -[their website](https://www.biosemi.com/faq/cms&drl.htm). - -For a formatted example on how to deal with this in the BIDS context, -please see this -[template](https://github.com/bids-standard/bids-starter-kit/blob/main/templates/sub-01/ses-01/eeg/sub-01_ses-01_task-ReferenceExample_eeg.json). - -## General: Can I combine BIDS and neurodata without border (NWB)? - -BIDS and [NWB](https://www.nwb.org/) are compatible. - -An NWB data file is an allowed format in the iEEG-BIDS data structure. -This means that one subject (AAA) with a session (BBB) -can have a BIDS folder with raw iEEG data in NWB format: - -``` -/sub-AAA/ses-BBB/ieeg/sub-AAA_ses-BBB_task-rest_ieeg.nwb -``` - -The same subject can have another session (CCC) with raw fMRI data in BIDS: - -``` -/sub-AAA/ses-CCC/func/sub-AAA_ses-CCC_task-rest_bold.nii.gz -``` - -## General: How can I cite BIDS? - -See the specification website for the -[main publications](https://bids-specification.readthedocs.io/en/latest/01-introduction.html#citing-bids) -related to BIDS and its extensions. - -BIDS references are centralized in a [zotero group](https://www.zotero.org/groups/5111637/bids). - -## General: How do I convert my data to BIDS? - -We strongly recommend you pick a BIDS converter to help you convert your data. - -A list of converters can be found [on the BIDS website](https://bids.neuroimaging.io/benefits.html#converters) - -Also look at [the list of tutorials and information about conversions](./tutorials/tutorials.md). - -## General: How should I organize data for hyperscanning data? - -Hyperscanning is simultaneous fMRI with multiple subjects (see this [paper](https://doi.org/10.1006/nimg.2002.1150)). - -- See this [issue](https://github.com/bids-standard/bids-specification/issues/402) - in the bids specification repository for typical hyperscanning data. - -See an example below with fMRI data: - -``` -sub-01/ - ses-dyadic1/ - func/ - sub-01_ses-dyadic1_* -sub-02/ - ses-dyadic1/ - func/ - sub-02_ses-dyadic1_* -sub-03/ - ses-dyadic2/ - func/ - sub-03_ses-dyadic2_* -sub-04/ - ses-dyadic2/ - func/ - sub-04_ses-dyadic2_* -``` - -- See this [post on neurostars](https://neurostars.org/t/bids-structure-for-longitudinal-dyadic-data/26173) - for hyperscanning longitunal data. - -See an example below with fMRI data: - -``` -sub-S001/ - ses-1/ - func/ - sub-S001_ses-1_task-video_acq-dyad001_bold.nii.gz - ses-2/ -sub-S002/ - ses-1/ - func/ - sub-S002_ses-1_task-video_acq-dyad001_bold.nii.gz - ses-2/ -sub-S003/ - ses-1/ - func/ - sub-S003_ses-1_task-video_acq-dyad002_bold.nii.gz - ses-2/ -``` - - -- See this [thread on the bids discussion forum](https://groups.google.com/g/bids-discussion/c/v660DuzOf3w/m/q-0PLHt5BgAJ) - -## General: How to import Excel files to TSV file? - -See [our sections on TSV files](./folders_and_files/metadata.md#tsv-files) for more information. - -See also this bids tool to import and export a `participants.tsv` file: -[bids-matlab-tools](https://github.com/sccn/bids-matlab-tools/blob/master/bids_spreadsheet2participants.m) - -## General: How to specify the micro sign in MATLAB? - -BIDS requires physical units to be specified according to the SI unit symbol and -possibly prefix symbol (for example: mV, μV for milliVolt and microVolt). - -The symbol used to indicate `¡` has unicode U+00B5, which is in MATLAB: - -```matlab -char(181) -``` - -or - -```matlab -native2unicode(181, 'latin1') -``` - -## General: I had to split the testing of one of my participants across 2 days, should I use 2 different session folders to organize the data of that participant? - -(faq_session)= - -No. The `session` level in the BIDS folder hierarchy can be used to group data -that go "logically" together: this means that you can put in the same `session` folder -data that were acquired on different days, -but that are "linked" to one another in a way that make sense to how you want to organize your data. - -If you want to keep track of what data was acquired when you can use the -[`scans.tsv` files](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#scans-file). - -For some examples, see this -[issue in the bids-starter kit](https://github.com/bids-standard/bids-starter-kit/issues/193). - -If you deal with EEG data, you may want to read this -[comment in another issue](https://github.com/bids-standard/bids-starter-kit/issues/265#issuecomment-1082240834) -as well before considering combining recordings acquired on different occasions -within the same `session` folder. - -## General: I only have nifti files and no dicom. Can I still create a BIDS dataset? - -In theory yes, but it is possible that you will be missing some metadata that is required by the BIDS specification. - -A couple of BIDS converters can work with nifti files: - -- bidsme -- explore asl -- data2bids - -See the list of converters [here](https://bids.neuroimaging.io/benefits.html#mri-and-pet-converters). - -**However**... - -- They may not work with the datatype you have - (for example not sure that explore ASL can deal with `func` data). -- Many of them still expect that you have a json side car for each nifti - (BIDSme for example - from the top of my head). -- They may expect a certain input structure to work efficiently, - so we may have to move files around. - - - -### Regarding the "missing" JSON files - -Depending on the datatype you are dealing with this can be more of less annoying. - -2 examples: - -For the most typical `anat` files, -they don't have any REQUIRED metadata, -so you could have just the data files without any accompanying JSON. -If you get into more exotic anat files (like for quantitative MRI) -then this may become a problem. - -For `func` files you only need `TaskName` and `RepetitionTime` -and the former you can decide what it is and the latter should be in the Nifti header. -So you should be OKish there too. - -Obviously you will be missing some metadata that would be required -for some type of preprocessing (like slice timing info). - -### Tips - -- If you have the PDF with the details of acquisition sequence or a method section - from a paper with that data, you could "recover" some extra metadata. -- SPM dicom import tool usually leaves a couple of metadata in a description field of the nifti header. - That can be a problem for data anonymisation but may help you in your case if this is the tool that was used. - See an example [here](https://github.com/PeerHerholz/BIDSonym/issues/41#issue-768636869) -- If you have to script tings manually rather than using a converter, - remember to use pybids [path construction tools](https://bids-standard.github.io/pybids/examples/pybids_tutorial.html#path-construction) or the [bids matlab equivalent](https://github.com/bids-standard/bids-matlab/blob/master/examples/03_BIDS-Matlab_filenames_and_metadata.ipynb) to make your life easier when constructing bids valid filenames. - -## General: Is there a machine readable version of the BIDS specification? - -Yes. The BIDS specification exist as a schema. -The BIDS schema is a machine readable representation of the BIDS Standard. -It is (by and large) the BIDS Specification, but written in a declarative form. - -The BIDS schema is available in two machine readable formats: - -- as a set of [YAML](https://en.wikipedia.org/wiki/YAML) files in the [BIDS specification repository](https://github.com/bids-standard/bids-specification/src/schema) -- as a [single json file](https://bids-specification.readthedocs.io/en/stable/schema.json) - -A light-weight introduction to the schema can be found [here](https://bids-extensions.readthedocs.io/en/latest/schema/). - -A full description of the schema can be found on this [website](https://bidsschematools.readthedocs.io/en/latest/?badge=latest) -where you will also find the documentation for the python package -to interact with the schema, [bidsschematools](https://pypi.org/project/bidsschematools/). - -## General: Is your data type not covered in the current BIDS specification? - -BIDS extensions proposals [(BEPs)](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification) -aim to extend the BIDS specification to new data types. -A list of extensions proposals can be found below. - -Guidelines for contributing to these extensions or starting your own can be found -in the [BIDS Extension Proposals Guide](https://bids-extensions.readthedocs.io/en/latest/). - -If only part of your data is covered under BIDS, an option to allow additional files -currently not covered in BIDS to pass the validator is -the [.bidsignore](https://github.com/bids-standard/bids-validator/blob/master/bids-validator/README.md) file, -which works just like [.gitignore](https://git-scm.com/docs/gitignore). -It allows you to list all the files (or directories, with wildcards) -that are not BIDS compliant and should be ignored by the validator. -Of course you should still try to adhere to upcoming BEPs -and the general BIDS philosophy for file names and metadata where possible, -but this gives a little extra flexibility. - - - -### raw - -- BEP004: [Susceptibility Weighted Imaging (SWI)](https://bids.neuroimaging.io/bep004) -- BEP020: [Eye Tracking including Gaze Position and Pupil Size](https://bids.neuroimaging.io/bep020) -- BEP022: [Magnetic Resonance Spectroscopy (MRS)](https://bids.neuroimaging.io/bep022) -- BEP024: [Computed Tomography scan (CT)](https://bids.neuroimaging.io/bep024) -- BEP026: [Microelectrode Recordings](https://bids.neuroimaging.io/bep026) -- BEP032: [Animal electrophysiology](https://bids.neuroimaging.io/bep032) -- BEP033: [Advanced Diffusion Weighted Imaging (aDWI)](https://bids.neuroimaging.io/bep033) -- BEP036: [Phenotypic Data Guidelines](https://bids.neuroimaging.io/bep036) -- BEP037: [Non-Invasive Brain Stimulation (NIBS)](https://bids.neuroimaging.io/bep037) -- BEP038: [Atlases](https://bids.neuroimaging.io/bep038) -- BEP039: [Dimensionality reduction-based networks](https://bids.neuroimaging.io/bep039) -- BEP040: [Functional Ultrasound (fUS)](https://bids.neuroimaging.io/bep040) -### derivative - -- BEP011: [Structural preprocessing derivatives](https://bids.neuroimaging.io/bep011) -- BEP012: [Functional preprocessing derivatives](https://bids.neuroimaging.io/bep012) -- BEP014: [Affine transformations and nonlinear field warps](https://bids.neuroimaging.io/bep014) -- BEP016: [Diffusion weighted imaging derivatives](https://bids.neuroimaging.io/bep016) -- BEP017: [Generic BIDS connectivity data schema](https://bids.neuroimaging.io/bep017) -- BEP021: [Common Electrophysiological Derivatives](https://bids.neuroimaging.io/bep021) -- BEP023: [PET Preprocessing derivatives](https://bids.neuroimaging.io/bep023) -- BEP034: [Computational modeling](https://bids.neuroimaging.io/bep034) -- BEP035: [Modular extensions for individual participant data mega-analyses with non-compliant derivatives](https://bids.neuroimaging.io/bep035) -- BEP041: [Statistical Model Derivatives](https://bids.neuroimaging.io/bep041) -### metadata - -- BEP028: [Provenance](https://bids.neuroimaging.io/bep028) -- BEP034: [Computational modeling](https://bids.neuroimaging.io/bep034) -### file format - -## General: What does [this word] mean? - -We're building a glossary to de-jargonise some of the terms you need to know to -work with data in BIDS format. Check it out [here](./glossary.md). - -## General: What is a `json` file? - -You can find more information about `json` (and `tsv`) files in the -[Metadata-file-formats](./folders_and_files/metadata.md#json) page. - -## General: What liense should I choose for my dataset? - -If you want to know more about what license to choose for your dataset, -see the [turing way](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-data.html#data-licenses) -page dedicated to this topic. - -If you plan to put your dataset on [openneuro](https://openneuro.org/), -you should use a CC0 or a PDDL license as explained in their [FAQ](https://openneuro.org/faq). - -## MRI: What defacing tools can I use? - -If you want to share your BIDS data set, chances are that you will have to anonymize it -and therefore prevent identification of the participants from their anatomical scans. -You will need to de-identification (or deface) the anatomical images. -There are several options to do that - -- If you already have a valid BIDS data set you can simply use the - [BIDSonym BIDS app](https://github.com/PeerHerholz/BIDSonym) on it. To do - that it relies on several tools that you can also use before you have - finalized your BIDS data set - - [Pydeface](https://github.com/poldracklab/pydeface) - - [MRI deface](https://surfer.nmr.mgh.harvard.edu/fswiki/mri_deface) - - [Quickshear](https://github.com/nipy/quickshear) - -Otherwise you can also use: - -- [Fieldtrip](http://www.fieldtriptoolbox.org/faq/how_can_i_anonymize_an_anatomical_mri/) - under matlab can do it. -- SPM8 and SPM12: when in the batch editor go to: - `SPM menu --> Util --> Deface` - -## Phenotype: How can I store subject phenotypic data? - -In the phenotype folder, according to the details provided for -[phenotypes](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#phenotypic-and-assessment-data): - -``` -bids-root - phenotype -``` - -Please the see work on the [BIDS extension proposal for phenotypes](https://bids.neuroimaging.io/bep036) -for more guidelines. - -## Phenotype: Is there a standard for epilepsy phenotypes? - -Yes, open this -[epilepsyClassification2017](https://github.com/bids-standard/bids-starter-kit/blob/main/interactiveTreeVisualization/epilepsyClassification2017/tree.html) -and follow the examples in the -[phenotype templates](https://github.com/bids-standard/bids-starter-kit/tree/main/templates/phenotype). - -
- -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) +Moved [here](https://bids-website.readthedocs.io/en/latest/faq/) diff --git a/src/_config.yml b/src/_config.yml index d43f3644..a1a5b6bb 100644 --- a/src/_config.yml +++ b/src/_config.yml @@ -8,8 +8,8 @@ # Book settings title: BIDS starter kit # The title of the book. Will be placed in the left navbar. author: The BIDS community # The author of the book -copyright: '2021-2024' # Copyright year to be placed in the footer -logo: ../tools/bids-specification/BIDS_logo/BIDS_logo_black_transparent_background_crop.png # A path to the book logo +copyright: '' # Copyright year to be placed in the footer +logo: https://github.com/bids-standard/bids-specification/blob/master/BIDS_logo/BIDS_logo_black_transparent_background_crop.png # A path to the book logo exclude_patterns: ['**README.md', epilepsy_phenotype.rst, questions] # Patterns to skip when building the book. Can be glob-style (for example "*skip.ipynb") ####################################################################################### @@ -41,16 +41,23 @@ parse: # HTML-specific settings html: favicon: images/favicon.ico # A path to a favicon image - use_edit_page_button: true # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in - use_repository_button: true # Whether to add a link to your repository button - use_issues_button: true # Whether to add an "open an issue" button - extra_navbar: Powered by Jupyter Book # Will be displayed underneath the left navbar. + use_edit_page_button: false # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in + use_repository_button: false # Whether to add a link to your repository button + use_issues_button: false # Whether to add an "open an issue" button + extra_navbar: # Will be displayed underneath the left navbar. extra_footer: '' # Will be displayed underneath the footer. google_analytics_id: G-VZJHGNQV6D # A GA id that can be used to track book views. home_page_in_navbar: true # Whether to include your home page in the left Navigation Bar baseurl: '' # The base URL where your book will be hosted. Used for creating image previews and social links.for example: https://mypage.com/mybook/ comments: - hypothesis: true + hypothesis: false + announcement: | +
+

+ The Starter-kit has moved to the new BIDS website. +

+

Go and check it out and let us know what you think.

+
####################################################################################### # Launch button settings launch_buttons: diff --git a/src/_static/myfile.css b/src/_static/myfile.css deleted file mode 100644 index 14ce5f57..00000000 --- a/src/_static/myfile.css +++ /dev/null @@ -1,38 +0,0 @@ -/* https://colorbrewer2.org/#type=qualitative&scheme=Paired&n=12 */ -:root { - --mri: #a6cee3; - --pet: #1f78b4; - --micr: #33a02c; - --meeg: #6a3d9a; - --beh: #fb9a99; - --nirs: #b2df8a; - --motion: #e31a1c; - --unused: #fdbf6f; - --unused2: #ff7f00; - --unused3: #cab2d6; - --unused4: #ffff99; - --unused5: #b15928; - --key: #e41a1c; - --label: #377eb8; - --suffix: #4daf4a; - --ext: #984ea3; - --underscore: #ff7f00; -} - -p { text-align: justify; } - -.iframe-container{ - position: relative; - width: 90%; - margin-left: 5%; - padding-bottom: 56.25%; - height: 0; -} - -.iframe-container > iframe{ - position: absolute; - top:0; - left: 0; - width: 100%; - height: 100%; -} diff --git a/src/_toc.yml b/src/_toc.yml index 1cbb3170..641142bc 100644 --- a/src/_toc.yml +++ b/src/_toc.yml @@ -4,32 +4,51 @@ root: index.md parts: - caption: Folders and files chapters: - - file: folders_and_files/folders.md - - file: folders_and_files/files.md - - file: folders_and_files/metadata.md - - url: https://github.com/bids-standard/bids-starter-kit/tree/main/templates - title: BIDS files templates - - file: folders_and_files/derivatives + - title: Folders + url: https://bids-website.readthedocs.io/en/latest/getting_started/folders_and_files/folders.html + - title: Filenames + url: https://bids-website.readthedocs.io/en/latest/getting_started/folders_and_files/files.html + - title: Metadata and file formats + url: https://bids-website.readthedocs.io/en/latest/getting_started/folders_and_files/metadata.html + - title: BIDS files templates + url: https://github.com/bids-standard/bids-starter-kit/tree/main/templates + - title: Derivatives + url: https://bids-website.readthedocs.io/en/latest/getting_startedfolders_and_files/derivatives.html - caption: Tutorials chapters: - - file: tutorials/annotation.md - - file: tutorials/ieeg.md - - file: tutorials/asl.md - - file: tutorials/pet.md - - file: tutorials/mri.md - - file: tutorials/tutorials.md + - title: Annotating a BIDS dataset + url: https://bids-website.readthedocs.io/en/latest/getting_started/tutorials/annotation.html + - title: iEEG data conversion + url: https://bids-website.readthedocs.io/en/latest/getting_started/tutorials/conversion/ieeg.html + - title: ASL data conversion + url: https://bids-website.readthedocs.io/en/latest/getting_started/tutorials/conversion/asl.html + - title: PET data conversion + url: https://bids-website.readthedocs.io/en/latest/getting_started/tutorials/conversion/pet.html + - title: MRI data conversion + url: https://bids-website.readthedocs.io/en/latest/getting_started/tutorials/conversion/mri.html + - title: Tutorials + url: https://bids-website.readthedocs.io/en/latest/getting_started/tutorials/index.html - caption: Resources chapters: - - file: dataset_examples.md - - file: talks.md - - file: publications.md - - file: dependencies.md - - file: links.md + - title: Dataset examples + url: https://bids-website.readthedocs.io/en/latest/datasets/ + - title: Talks + url: https://bids-website.readthedocs.io/en/latest/getting_started/resources/talks.html + - title: Publications + url: https://bids-website.readthedocs.io/en/latest/getting_started/resources/publications.html + - title: Dependencies + url: https://bids-website.readthedocs.io/en/latest/getting_started/resources/dependencies.html + - title: Links + url: https://bids-website.readthedocs.io/en/latest/getting_started/resources/links.html - caption: Others chapters: - - file: FAQ.md - - file: validator.md - - file: glossary.md - - file: contact.md + - title: FAQ + url: https://bids-website.readthedocs.io/en/latest/faq/ + - title: Validator + url: https://bids-website.readthedocs.io/en/latest/tools/validator.html + - title: Glossary + url: https://bids-website.readthedocs.io/en/latest/getting_started/resources/glossary.html + - title: Contact + url: https://bids-website.readthedocs.io/en/latest/contact/ - file: CONTRIBUTING.md - file: CODE_OF_CONDUCT.md diff --git a/src/contact.md b/src/contact.md index f7ff9e37..58c6bfb5 100644 --- a/src/contact.md +++ b/src/contact.md @@ -1,30 +1,3 @@ # Contact -We have lots of different ways of staying in touch! - -**Our preferred way to answer questions** is via our forum -[Neurostars](https://neurostars.org/tags/bids) (we have a 90%+ answer rate!) - -We understand that posting a question on a forum can seem a bit uncertain and intimidating. -However, if _you_ have a question it's almost certain that somebody else will too, -and this way we can avoid answering the same question multiple times. -Even if your question is not well-defined, -just post what you have so far and we will be able to point you in the right direction! - -Some example questions that have already been answered include: - -- [BIDS file naming specifications](https://neurostars.org/t/bids-beginner-convert-data-to-bids-format/1364) -- [BIDS beginner - convert data to BIDS format](https://neurostars.org/t/bids-beginner-convert-data-to-bids-format/1364) - -You can also come chat on the -[Brainhack mattermost](https://mattermost.brainhack.org/): - -- on the - [`~bids_general`](https://mattermost.brainhack.org/brainhack/channels/bids_general) - channel -- or on the - [`~starter-kit`](https://mattermost.brainhack.org/brainhack/channels/bids-starter-kit) - -We'd love for you to join the mailing list (bids-discussion@googlegroups.com, -click [here](https://groups.google.com/g/bids-discussion) to join). -You might find some helpful answers and discussions there. +Moved [here](https://bids-website.readthedocs.io/en/latest/contact/) diff --git a/src/dataset_examples.md b/src/dataset_examples.md index 93cd17da..e3ca0950 100644 --- a/src/dataset_examples.md +++ b/src/dataset_examples.md @@ -1,50 +1,3 @@ # BIDS data -Here are some links to BIDS compliant data. Sourcedata (pre-BIDS) are sometimes -also available, these can be used to just see (or to build tutorials) of how -source data are converted to BIDS. - -## BIDS examples with empty raw data files - -- Many examples can be found - [here](https://github.com/bids-standard/bids-examples) - -## BIDS examples with data files - -- [OpenNeuro](https://openneuro.org/): If you're looking for full data files - to run the validator on or simply compare to your own _bidsified_ data try - searching here. Datasets here are (by and large) publicly available and - conform to BIDS. - - [anat](https://openneuro.org/search/anat) - - [beh](https://openneuro.org/search/beh) - - [dwi](https://openneuro.org/search/dwi) - - [eeg](https://openneuro.org/search/eeg) - - [fmap](https://openneuro.org/search/fmap) - - [func](https://openneuro.org/search/func) - - [ieeg](https://openneuro.org/search/ieeg) - - [meg](https://openneuro.org/search/meg) - - [pet](https://openneuro.org/search/pet) - -## Brainhack Western 2018 dataset - -- sourcedata: - [ds001](https://drive.google.com/drive/folders/15GiGHqit0gFFblOUuL2hSoWEJVw6q1M5) -- rawdata: - [ds001_BIDS](https://drive.google.com/drive/folders/1A3TbarHbtXqx7FfW0UbWWuY1GflF3630) - -## Mother of unification studies - - - -- a 204-subject multimodal (MEG, MRI, fMRI) -[dataset](http://data.donders.ru.nl/collections/di/dccn/DSC_3011020.09_236?0) -to study language processing - - -## Other data that is not in BIDS format - -Datasets used in Stanford Reproducibility Center tutorials: -[NKI Rockland](http://fcon_1000.projects.nitrc.org/indi/pro/eNKI_RS_TRT/FrontPage.html) - -Resting state fMRI datasets: -[FCON 1000](http://fcon_1000.projects.nitrc.org/fcpClassic/FcpTable.html) +Moved [here](https://bids-website.readthedocs.io/en/latest/datasets/) diff --git a/src/dependencies.md b/src/dependencies.md index 816b2ba9..6f060ef7 100644 --- a/src/dependencies.md +++ b/src/dependencies.md @@ -1,52 +1,3 @@ # BIDS Dependencies List -The following is a list of **options** available for working with BIDS - -BIDS is language independent, and can be used with any of the languages listed -below. Feel free to choose whichever one you are most comfortable with! - -Please note that for each choice of language, the additional listed packages are -required to work with BIDS. - -## Text editors - -Code can be written in anything from Notepad(Windows) to TextEdit(macOS) to -vim(Linux). - -But there are some text-editors built specifically for coding that can help with -some parts of programming. - -One that's free and easy to use is [Visual studio code](https://code.visualstudio.com/). -It'll work for all the languages below! - -## MATLAB / Octave (Free, open source equivalent) - -**_MATLAB Information_**: - -**_Octave Information_**: - -Required JSON package **JSONio** - -Install Link: https://github.com/gllmflndn/JSONio - -## Python - -**_Information_**: (Both Python 2 and 3 will work for -BIDS) - -**Anaconda** Recommended package to use for installing Python - -Install Link: https://conda.io/docs/user-guide/install/download.html - -**Pandas** Pandas is already included in Anaconda, but use the link below if you -just want the data analysis library. - -Install Link: https://pandas.pydata.org/ - -## R - -**_Information_**: - -**Jsonlite** package required to read and write JSON files - -https://cran.r-project.org/web/packages/jsonlite/index.html +Moved [here](https://bids-website.readthedocs.io/en/latest/getting_started/resources/dependencies.html) diff --git a/src/folders_and_files/derivatives.md b/src/folders_and_files/derivatives.md index 61a1b90e..2dcc53e0 100644 --- a/src/folders_and_files/derivatives.md +++ b/src/folders_and_files/derivatives.md @@ -1,234 +1,3 @@ # Derivatives -Derivatives are outputs of (pre-)processing pipelines, capturing data -and meta-data sufficient for a researcher to understand -and (critically) reuse those outputs in subsequent processing. -Standardizing derivatives is motivated by use cases where formalized machine-readable access -to processed data enables higher level processing. - -A derivative dataset is a collection of derivatives, or files that have been generated from the data. -Broadly, a derivative can be considered to be preprocessed or processed, -such that the data type is unchanged or changed, respectively, from that of the source data file(s). - -BIDS Derivatives was finalized in version 1.4.0 of the BIDS specification. - -## Tour of a BIDS Derivative - -As with BIDS datasets, all conformant derivative datasets contain a `dataset_description.json`. - -New fields include `DatasetType`, which distinguishes `"derivative"` datasets from `"raw"`: - -- `GeneratedBy`, a list of processes that generated the data -- `SourceDatasets`, a list of datasets used to generate the derivative. - -```json -{ - "Name": "FMRIPREP Outputs", - "BIDSVersion": "1.4.0", - "DatasetType": "derivative", - "GeneratedBy": [ - { - "Name": "fmriprep", - "Version": "1.4.1", - "Container": { - "Type": "docker", - "Tag": "poldracklab/fmriprep:1.4.1" - } - }, - { - "Name": "Manual", - "Description": "Re-added RepetitionTime metadata to bold.json files" - } - ], - "SourceDatasets": [ - { - "DOI": "10.18112/openneuro.ds000114.v1.0.1", - "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1", - "Version": "1.0.1" - } - ] -} -``` - -### Preprocessed data - -Data is considered to be _preprocessed_ if it is fundamentally similar to the source data. -Artifact removal, motion correction and resampling to a template space are examples of preprocessing. - -An example of a subject with simultaneous EEG/fMRI resting state scan, -aligned along with a T1w image to the MNI305 template: - -```bash -pipeline1/ - sub-01/ - anat/ - sub-01_space-MNI305_T1w.nii.gz - sub-01_space-MNI305_T1w.json - eeg/ - sub-01_task-rest_desc-filtered_eeg.edf - sub-01_task-rest_desc-filtered_eeg.json - func/ - sub-01_task-rest_space-MNI305_desc-preproc_bold.nii.gz - sub-01_task-rest_space-MNI305_desc-preproc_bold.json -``` - -The `space` entity indicates that a file is aligned to some reference space. -For standard templates, this is sufficient. -For custom templates (for example: individual or study-specific), -additional `SpatialReference` metadata is required in the JSON sidecar files. - -The `desc` (description) entity allows for unrestricted alphanumeric labels, -in the absence of a more appropriate entity to distinguish one file from another. - -### Derivative data types - -Data is considered to be _processed_ if it is fundamentally different to the source data. -Processed data may differ substantially in BIDS datatypes from the original input data. - -The initial offering of BIDS Derivatives only specifies anatomical derivatives -that are of general use: masks and segmentations. - -Mask images are binary images with 1 representing the region of interest -and all other voxels containing 0. -The following example shows a manually constructed lesion mask: - -```bash -manual_masks/ - sub-01/ - anat/ - sub-01_desc-lesion_mask.nii.gz - sub-01_desc-lesion_mask.json -``` - -A mask of the functionally-defined area fusiform face area could be encoded: - -```bash -localizer/ - sub-01/ - func/ - sub-01_task-loc_space-individual_label-FFA_mask.nii.gz - sub-01_task-loc_space-individual_label-FFA_mask.json -``` - -BIDS Derivatives introduces "discrete segmentations" and "probabilistic segmentations". - -A _segmentation_ is a labeling of regions of an image such that each location -(for example, a voxel or a surface vertex) is identified with a label or a combination of labels. -Labeled regions may include anatomical structures -(such as tissue class, Brodmann area or white matter tract), discontiguous, -functionally-defined networks, tumors or lesions. - -A _discrete segmentation_ represents each region with a unique integer label. -A _probabilistic segmentation_ represents each region as values between 0 and 1 -(inclusive) at each location in the image, and one volume/frame per structure -may be concatenated in a single file. - -A BIDS App that calculates ROIs in BOLD space from the automated anatomical -labeling (AAL, doi:[10.1006/nimg.2001.0978]) could store discrete -and probabilistic (or partial volume) segmentations as follows: - -```bash -tissue_segmentation/ - desc-AAL_dseg.tsv - desc-AAL_probseg.json - sub-01/ - func/ - sub-01_task-rest_desc-AAL_dseg.nii.gz - sub-01_task-rest_desc-AAL_probseg.nii.gz -``` - -The `dseg.tsv` file is a lookup table for interpreting a discrete segmentation -and `probseg.json` contains a list identifying the labels for each consecutive volume. - -### Unspecified data types - -Derivatives can never be fully specified, as new methods can always be developed, -requiring new data representations. -BIDS recognizes this and encourages adopting "BIDS-style naming conventions". - -Additional files and folders containing raw data MAY be added as needed for special cases. -All non-standard file entities SHOULD conform to BIDS-style naming conventions, -including alphabetic entities and suffixes and alphanumeric labels/indices. -Non-standard suffixes SHOULD reflect the nature of the data, -and existing entities SHOULD be used when appropriate. - -This recommendation remains in force for derivatives datasets. -Additionally, BIDS Derivatives acknowledges that it may be desirable -to distribute derivatives generated by non-compliant applications, -for the sake of reproducibility and non-duplication of effort. -Therefore, if a BIDS dataset contains a `derivatives/` sub-directory, -the contents of that directory may be a heterogeneous mix of BIDS Derivatives datasets -and non-compliant derivatives. - -One example of such a non-compliant derivative dataset would be FreeSurfer reconstructions of subject surfaces: - -```bash -bids-root/ - derivatives/ - freesurfer/ - sub-01/ - label/ - mri/ - ... - ... - sub-01/ - anat/ - sub-01_T1w.nii.gz - ... -``` - -Note that subject directory names conform to BIDS conventions, -but contents are determined by the generating application, in this case, FreeSurfer. - -### Organizing datasets and their derivatives - -BIDS Derivatives datasets are intended to be interpretable and distributable -with or without the datasets used to generate them. -This is necessary for storage and bandwidth constraints, -as well as to permit the distribution of derivatives when the source data are restricted. - -This independence affords flexibility in the relative organization of datasets. -The following examples show three ways to organize, relative to each other, -a raw BIDS dataset, a preprocessed derivative dataset, and an analysis that uses both as inputs. - -A collection of derivative datasets may be stored in the `derivatives/` subdirectory -of a BIDS (or BIDS Derivatives) dataset: - -```bash -my_dataset/ - derivatives/ - preprocessed/ - analysis/ - sub-01/ - ... -``` - -A BIDS Derivatives dataset may contain references to its input datasets -in the `sourcedata/` subdirectory: - -```bash -my_analysis/ - sourcedata/ - raw/ - preprocessed/ - sub-01/ - ... -``` - -Note that the `sourcedata/` and `derivatives/` subdirectories constitute dataset boundaries. -Any contents of these directories may be validated independently, -but their contents must not affect the interpretation of the nested or containing datasets. - -Unnested datasets are also possible. For example: - -```bash -my_study/ - raw_data/ - sub-01/ - ... - derivatives/ - preprocessed/ - analysis/ -``` - - +Moved [here](https://bids-website.readthedocs.io/en/latest/getting_started/folders_and_files/derivatives.html) diff --git a/src/folders_and_files/files.md b/src/folders_and_files/files.md index 5f8f3ee2..d0b4d5a5 100644 --- a/src/folders_and_files/files.md +++ b/src/folders_and_files/files.md @@ -1,661 +1,3 @@ # Filenames -These are the three main types of files you'll find in a BIDS dataset: - -1. `.json` files that contain `key: value` metadata -2. `.tsv` files that contain tables of metadata -3. Raw data files (for example: `.jpg` files for images or `.nii.gz` files for - fMRI data.) - -BIDS has a standardized way of naming files that tries to implement the -following principles: - -- Do not include white spaces in file names - - They make scripting harder. -- Use only letters, numbers, hyphens, and underscores. - - Some operating systems cannot handle special characters. -- Do not rely on letter case (`UPPERCASE` and `lowercase`) - - For some operating systems `a` is the same as `A`. -- Use separators and case in a systematic and meaningful way. - - [`thisIsCamelCase`](https://en.wikipedia.org/wiki/Camel_case) - - [`this_is_snake_case`](https://en.wikipedia.org/wiki/Snake_case) - -Source: -[Datalad RDM course](https://psychoinformatics-de.github.io/rdm-course/02-structuring-data/index.html) - -## Filename template - - - -

- key1 - - - value1 - _ - key2 - - - value2 - _ - suffix - .extension -

- -

-

    -
  • Suffixes are preceded by an underscore
    • -
  • Entities are composed of key-value pairs separated by underscores
    • -
  • There is a limited set of suffixes for each data type (anat, func, eeg, …)
    • -
  • For a given suffix, some entities are required and some others are [optional].
    • -
  • Keys, value and suffixes can only contain letters and/or numbers.
    • -
  • Entity key-value pairs have a specific order in which they must appear in filename.
    • -
  • Some entities key-value can only be used for -derivative data.
    • -
-

- -## Modalities - - -### MRI - -#### `anat`: Anatomical MRI - - -Template: -

sub-<label>/
-    [ses-<label>/]
-        anat/
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_<suffix>.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_<suffix>.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_chunk-<index>]_<suffix>.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_chunk-<index>]_<suffix>.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_mod-<label>][_chunk-<index>]_defacemask.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_mod-<label>][_chunk-<index>]_defacemask.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_echo-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_MEGRE.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_echo-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_MEGRE.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_echo-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_MESE.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_echo-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_MESE.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_VFA.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_VFA.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_inv-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_IRT1.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_inv-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_IRT1.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>]_inv-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_MP2RAGE.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>]_inv-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_MP2RAGE.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>_mt-<on|off>[_part-<mag|phase|real|imag>][_chunk-<index>]_MPM.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>_mt-<on|off>[_part-<mag|phase|real|imag>][_chunk-<index>]_MPM.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>_mt-<on|off>[_part-<mag|phase|real|imag>][_chunk-<index>]_MTS.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>_mt-<on|off>[_part-<mag|phase|real|imag>][_chunk-<index>]_MTS.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_mt-<on|off>[_part-<mag|phase|real|imag>][_chunk-<index>]_MTR.json
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_mt-<on|off>[_part-<mag|phase|real|imag>][_chunk-<index>]_MTR.nii[.gz]
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -#### `func`: Functional MRI - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        func/
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_bold.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_bold.nii[.gz]
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_cbv.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_cbv.nii[.gz]
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_sbref.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_sbref.nii[.gz]
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_chunk-<index>]_phase.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_chunk-<index>]_phase.nii[.gz]
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>]_events.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>]_events.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -#### `fmap`: Fieldmap - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        fmap/
-            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>][_chunk-<index>]_<suffix>.json
-            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>][_chunk-<index>]_<suffix>.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>][_chunk-<index>]_epi.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>][_chunk-<index>]_epi.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>][_chunk-<index>]_m0scan.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>][_chunk-<index>]_m0scan.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_flip-<index>[_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1DAM.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_flip-<index>[_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1DAM.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_echo-<index>_flip-<index>[_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1EPI.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_echo-<index>_flip-<index>[_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1EPI.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_RB1COR.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_RB1COR.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1AFI.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1AFI.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1RFM.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1RFM.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1TFL.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>][_flip-<index>][_inv-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_TB1TFL.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>_inv-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_TB1SRGE.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_echo-<index>]_flip-<index>_inv-<index>[_part-<mag|phase|real|imag>][_chunk-<index>]_TB1SRGE.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_chunk-<index>]_RB1map.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_chunk-<index>]_RB1map.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_chunk-<index>]_TB1map.json
-            sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_chunk-<index>]_TB1map.nii[.gz]
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -#### `dwi`: Diffusion MRI - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        dwi/
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_dwi.bval
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_dwi.bvec
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_dwi.json
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_dwi.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_sbref.json
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_part-<mag|phase|real|imag>][_chunk-<index>]_sbref.nii[.gz]
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -#### `perf`: ASL MRI - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        perf/
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_asl.json
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_asl.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_m0scan.json
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_m0scan.nii[.gz]
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>]_aslcontext.tsv
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_run-<index>]_asllabeling.jpg
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_run-<index>]_asllabeling.png
-            sub-<label>[_ses-<label>][_acq-<label>][_rec-<label>][_run-<index>]_asllabeling.tif
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_rec-<label>][_dir-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -### MEEG - -#### `eeg` - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        eeg/
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.tsv
-            sub-<label>[_ses-<label>][_acq-<label>][_space-<label>]_coordsystem.json
-            sub-<label>[_ses-<label>][_acq-<label>][_space-<label>]_electrodes.json
-            sub-<label>[_ses-<label>][_acq-<label>][_space-<label>]_electrodes.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_eeg.<extension>
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_eeg.json
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.jpg
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.png
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.tif
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -#### `meg` - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        meg/
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>]_channels.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>]_channels.tsv
-            sub-<label>[_ses-<label>][_acq-<label>]_coordsystem.json
-            sub-<label>[_ses-<label>][_acq-<label>][_proc-<label>][_space-<label>]_electrodes.json
-            sub-<label>[_ses-<label>][_acq-<label>][_proc-<label>][_space-<label>]_electrodes.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_split-<index>]_meg.<extension>
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_split-<index>]_meg.json
-            sub-<label>[_ses-<label>]_acq-<calibration>_meg.dat
-            sub-<label>[_ses-<label>]_acq-<crosstalk>_meg.fif
-            sub-<label>[_ses-<label>][_acq-<label>]_headshape.*
-            sub-<label>[_ses-<label>][_acq-<label>]_headshape.pos
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_space-<label>]_markers.mrk
-            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_space-<label>]_markers.sqd
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.jpg
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.png
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.tif
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -#### `ieeg` - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        ieeg/
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.tsv
-            sub-<label>[_ses-<label>][_acq-<label>][_space-<label>]_coordsystem.json
-            sub-<label>[_ses-<label>][_acq-<label>][_space-<label>]_electrodes.json
-            sub-<label>[_ses-<label>][_acq-<label>][_space-<label>]_electrodes.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_ieeg.<extension>
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_ieeg.json
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.jpg
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.png
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.tif
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -### `pet` - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        pet/
-            sub-<label>[_ses-<label>][_task-<label>][_trc-<label>][_rec-<label>][_run-<index>]_pet.json
-            sub-<label>[_ses-<label>][_task-<label>][_trc-<label>][_rec-<label>][_run-<index>]_pet.nii[.gz]
-            sub-<label>[_ses-<label>][_task-<label>][_trc-<label>][_rec-<label>][_run-<index>]_recording-<label>_blood.json
-            sub-<label>[_ses-<label>][_task-<label>][_trc-<label>][_rec-<label>][_run-<index>]_recording-<label>_blood.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>]_events.json
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>]_events.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_trc-<label>][_rec-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -### `nirs` - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        nirs/
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.tsv
-            sub-<label>[_ses-<label>][_acq-<label>]_coordsystem.json
-            sub-<label>[_ses-<label>][_acq-<label>]_optodes.json
-            sub-<label>[_ses-<label>][_acq-<label>]_optodes.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_nirs.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_nirs.snirf
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.jpg
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.png
-            sub-<label>[_ses-<label>][_acq-<label>]_photo.tif
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- - -### `motion` - - -Template: -
sub-<label>/
-    [ses-<label>/]
-        motion/
-            sub-<label>[_ses-<label>]_task-<label>_tracksys-<label>[_acq-<label>][_run-<index>]_channels.json
-            sub-<label>[_ses-<label>]_task-<label>_tracksys-<label>[_acq-<label>][_run-<index>]_channels.tsv
-            sub-<label>[_ses-<label>]_task-<label>_tracksys-<label>[_acq-<label>][_run-<index>]_motion.json
-            sub-<label>[_ses-<label>]_task-<label>_tracksys-<label>[_acq-<label>][_run-<index>]_motion.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>]_events.json
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>]_events.tsv
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.json
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>][_recording-<label>]_eyetrack.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>][_recording-<label>]_physio.json
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>][_recording-<label>]_stim.json
-            sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
-
-
-Legend: -
    -
  • -

    For more information about filename elements (for example, entities, suffixes, extensions), -follow the links embedded in the filename template.

    -
    • -
  • -

    Filename entities or directories between square brackets -(for example, [_ses-<label>]) are OPTIONAL.

    -
    • -
  • -

    Some entities may only allow specific values, -in which case those values are listed in <>, separated by |.

    -
    • -
  • -

    _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

    -
    • -
  • -

    .<extension> means that there are several (>6) valid extensions for this file type.

    -
    • -
  • -

    [.gz] means that both the unzipped and gzipped versions of the extension are valid.

    -
    • -
- -
- +Moved [here](https://bids-website.readthedocs.io/en/latest/getting_started/folders_and_files/files.html) diff --git a/src/folders_and_files/folders.md b/src/folders_and_files/folders.md index 413b1efb..ce997488 100644 --- a/src/folders_and_files/folders.md +++ b/src/folders_and_files/folders.md @@ -1,195 +1,3 @@ # Folders -The BIDS format is essentially a way to structure your data / metadata within a -hierarchy of folders. This makes it easy to browse from a computer, as well as -to automatically parse a BIDS folder with a program. The BIDS structure makes -minimal assumptions about the tools needed to interact with the data that's -inside. - -The files in present in BIDS dataset are organized into a hierarchy of folders -that have specific naming conventions. - -The rest of this page describes how these folders are structured. - -## Overview - -There are four main levels of the folder hierarchy, these are: - -``` -project/ -└── subject - └── session - └── datatype -``` - -With the exception of the top-level `project` folder, all sub-folders have a -specific structure to their name (described below). Here's an example of how -this hierarchy looks: - -``` -myProject/ -└── sub-01 - └── ses-01 - └── anat -``` - -Here is the folder name structure of each level: - -## project - -Can have any name, this should be descriptive for the dataset contained in the -folder. - -## subject - -Structure: `sub-` - -One folder per subject in this dataset. Labels should be unique for each -subject. - -## session - -Structure: `ses-` - -In general, a `session` represents a recording session, and subjects will -stay in the scanner or headset during that session. You might have multiple -sessions per subject if you collected data from them on several occasions. -If there is only a single session per subject, this level of the hierarchy -may be omitted. - -For more details, refer to this {ref}`section of the FAQ `. - -## datatype - -Represents different types of data. Must be one of: - -- `anat`: anatomical MRI data -- `func`: functional MRI data -- `fmap`: fieldmap data -- `dwi`: diffusion MRI data -- `perf`: arterial spin labeling data -- `eeg`: electroencephalography data -- `meg`: magnetoencephalography data -- `ieeg`: intracranial EEG data -- `beh`: behavioral data -- `pet`: positron emission tomography data -- `micr`: microscopy data -- `nirs`: near-infrared spectroscopy data -- `motion`: motion capture data - -The name for the datatype depends on the recording modality. - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
modality
datatypeMRIPETmeegbehavioralmicroscopyNIRSmotion
anatpeteegbehmicrnirsmotion
func
meg
dwiieeg
perf
-
- -## BIDS folder example - -Below is the folder hierarchy for one of the -[BIDS example datasets](https://github.com/INCF/BIDS-examples). It has multiple -subjects of data, and includes metadata files (`.tsv` and `.json`) both between- -and within-subjects. - -Note that it has one session per subject, so this level is omitted. - -``` -ds001 -β”œβ”€β”€ dataset_description.json -β”œβ”€β”€ participants.tsv -β”œβ”€β”€ sub-01 -β”‚Β Β  β”œβ”€β”€ anat -β”‚Β Β  β”‚Β Β  β”œβ”€β”€ sub-01_inplaneT2.nii.gz -β”‚Β Β  β”‚Β Β  └── sub-01_T1w.nii.gz -β”‚Β Β  └── func -β”‚Β Β  β”œβ”€β”€ sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz -β”‚Β Β  β”œβ”€β”€ sub-01_task-balloonanalogrisktask_run-01_events.tsv -β”‚Β Β  β”œβ”€β”€ sub-01_task-balloonanalogrisktask_run-02_bold.nii.gz -β”‚Β Β  β”œβ”€β”€ sub-01_task-balloonanalogrisktask_run-02_events.tsv -β”‚Β Β  β”œβ”€β”€ sub-01_task-balloonanalogrisktask_run-03_bold.nii.gz -β”‚Β Β  └── sub-01_task-balloonanalogrisktask_run-03_events.tsv -β”œβ”€β”€ sub-02 -β”‚Β Β  β”œβ”€β”€ anat -β”‚Β Β  β”‚Β Β  β”œβ”€β”€ sub-02_inplaneT2.nii.gz -β”‚Β Β  β”‚Β Β  └── sub-02_T1w.nii.gz -β”‚Β Β  └── func -β”‚Β Β  β”œβ”€β”€ sub-02_task-balloonanalogrisktask_run-01_bold.nii.gz -β”‚Β Β  β”œβ”€β”€ sub-02_task-balloonanalogrisktask_run-01_events.tsv -β”‚Β Β  β”œβ”€β”€ sub-02_task-balloonanalogrisktask_run-02_bold.nii.gz -β”‚Β Β  β”œβ”€β”€ sub-02_task-balloonanalogrisktask_run-02_events.tsv -β”‚Β Β  β”œβ”€β”€ sub-02_task-balloonanalogrisktask_run-03_bold.nii.gz -β”‚Β Β  └── sub-02_task-balloonanalogrisktask_run-03_events.tsv -... -... -└── task-balloonanalogrisktask_bold.json -``` +Moved [here](https://bids-website.readthedocs.io/en/latest/getting_started/folders_and_files/folders.html) diff --git a/src/folders_and_files/metadata.md b/src/folders_and_files/metadata.md index 852e28f5..c2676ac3 100644 --- a/src/folders_and_files/metadata.md +++ b/src/folders_and_files/metadata.md @@ -1,421 +1,3 @@ # Metadata and file formats -Metadata are stored in .json and .tsv files. These files are language-agnostic, -meaning you can work with them in, for example: Python, Matlab, or R. This page -covers common ways to read/write these files in common languages for -neuroscience analysis. - -More extensive example templates can be found -[here](https://github.com/bids-standard/bids-starter-kit/tree/main/templates), -well as -[MATLAB / Octave code](https://github.com/bids-standard/bids-starter-kit/tree/main/matlabCode) -and -[Python code](https://github.com/bids-standard/bids-starter-kit/tree/main/pythonCode) -to help you generate some of those files. - -## JSON Files - -JSON files are text files that take the following structure: - -```json -{ - "key": "value", - "key2": "value2", - "key3": { - "subkey1": "subvalue1" - } -} -``` - -Note that they can be nested (curly brackets within curly brackets). Here are -some common ways to read / write these files. - -## Online - -To read/write JSON online, we recommend the following website: - -[http://jsoneditoronline.org/](http://jsoneditoronline.org/) - -## Matlab / Octave - -There are many toolboxes in Matlab for reading / writing JSON files. - -Since MATLAB R2016b, you can use the built-in functions `jsonencode` (to write) -and `jsondecode` (to read) JSON files. Hopefully they should be available in -Octave 6.1 next year. - -The [JSONio library](https://github.com/gllmflndn/JSONio) will allow you to read -and write JSON files with matlab and octave (see examples below to use -`jsonwrite` and `jsonread`). - -SPM12 uses the JSONio library by calling `spm_jsonwrite` and `spm_jsonread` and -it has -[other interesting functions to help you with BIDS](https://en.wikibooks.org/wiki/SPM/BIDS). - -[bids-matlab](https://github.com/bids-standard/bids-matlab) has 2 functions -(`bids.util.jsonencode` and `bids.util.jsondecode`) that act as wrappers and -will use whatever implementation (SPM, JSONio, MATLAB) is available. - -The examples below are for the -[JSONio library](https://github.com/gllmflndn/JSONio): - -### Reading a `.json` file - -```matlab - jsonread([filename]) -``` - -### Writing a `.json` file - -```matlab -root_dir = './'; -project = 'temp'; -sub_id = '01'; -ses_id = '01'; -acquisition = 'anat'; - -anat_json_name = fullfile(root_dir,project,... - ['sub-' sub_id],... - ['ses-' ses_id],... - acquisition,... - ['sub-' sub_id '_ses-' ses_id '_T1W.json']); - -% Assign the fields in the Matlab structure that can be saved as a json: -anat_json.Manufacturer = 'GE'; -anat_json.ManufacturersModelName = 'Discovery MR750'; -anat_json.MagneticFieldStrength = 3; -anat_json.PulseSequence = 'T1 weighted SPGR'; - -json_options.indent = ' '; % this makes the json look pretier when opened in a txt editor -jsonwrite(loc_json_name,anat_json,json_options) -``` - -## Python - -In Python, JSON support is built into the core library, meaning you don't need -to install anything to read/write JSON files. In addition, the structure of JSON -is almost identical to that of Python dictionaries (assuming you are only -storing text / numbers in the dictionary). To that extent. - -### Reading a `.json` file - -```python - -import json -with open('myfile.json', 'r') as ff: - data = json.load(ff) -``` - -### Writing a `.json` file - -```python -import json -data = {'field1': 'value1', 'field2': 3, 'field3': 'field3'} -with open('my_output_file.json', 'w') as ff: - json.dump(data, ff) -``` - -## R - -There is a new package to help intract with BIDS datasets: -https://github.com/bbuchsbaum/bidser - -There are several packages for reading and writing JSON files from R. In this -example, we will be using jsonlite. Remember to install and call a package -before using it. - -https://github.com/jeroen/jsonlite - -### Installing required package - -```R - install.packages('jsonlite') -``` - -### Reading a `.json` file: - -```R - library(jsonlite) - data = fromJSON('myfile.json', pretty=TRUE) -``` - -### Writing a `.json` file: - -```R - library(jsonlite) - data = '{"field1": "value1", "field2": 3, "field3": "field3"}' - writeLines(data, file="myData.json") -``` - -## Interoperability issues - -Many parts of JSON files are often loaded as -[`structures`](https://nl.mathworks.com/help/matlab/ref/struct.html) by MATLAB / -Octave, where a `key` in a JSON file becomes `fieldname` in that structure. - -Here is an example with a simple `example.json` - -```json -{ - "key": "value" -} -``` - -loaded with bids-matlab - -```matlab ->> json_content = bids.util.jsondecode('example.json') - -json_content = - - struct with fields: - - key: 'value' -``` - -There are however some strict rules for what makes a valid fieldname in MATLAB -and octave. - -Fieldnames must: - -- start with a letter, otherwise assigning to that field will error -- contain only letters, numbers, and/or the underscore character, otherwise - assigning to that field will error, and -- must be no longer than `namelengthmax` (currently 63) characters, otherwise - you will receive a warning and the field name will be truncated - -If there are keys in your JSON that do not comply to those rules, they keys will -be renamed when loading which can lead to some headaches down the line. - -For example when loading the `bad_keys.json` - -```json -{ - "@foo": "@foo", - "1": "1", - "x1": "x1", - "x_1": "x_1", - "/t": "/t", - "%f": "%f" -} -``` - -We get some quite different fieldnames when read with matlab: - -```matlab ->> jsondecode(fileread('bad_keys.json')) - -ans = - - struct with fields: - - x_foo: '@foo' - x1: '1' - x1_1: 'x1' - x_1: 'x_1' - x_t: '/t' - x_f: '%f' -``` - -or with JSONio for Octave (though at least here we get a warning): - -``` ->> jsonread('bad_keys.json') -Warning: Duplicate key. - -ans = - - struct with fields: - - x_foo: '@foo' - x1: 'x1' - x_1: 'x_1' - x_t: '/t' - x_f: '%f' -``` - -This can lead to some unexpected behavior if you did not know about this. - -If you load this `collision.json` - -```json -{ - "1": "1", - "x1": "x1", - "x_1": "x_1" -} -``` - -and try to retrieve the value associated to the `key` `x1`, you will in fact be -getting the value for the key `1`. - -```matlab ->> json_content = bids.util.jsondecode('collision.json'); ->> json_content.x1 - - x1: '1' -``` - -**Why and when does this matter for BIDS?** - -In most cases this will not be an issue, but this could be problem if in your -`events.tsv` you have named some of your trial_type things like `1_face`, -`2_sound` and then want to annotate those events in a side car JSON file like -this. - -```json -{ - "trial_type": { - "LongName": "", - "Description": "image type", - "Levels": { - "1_face": "A face is displayed", - "2_sound": "A sound is played" - } - } -} -``` - -If you do this, it will be much harder to work with that JSON file for anyone -who uses MATLAB or Octave. - -```{attention} -So in general here are some suggestions on how to name your events: -- start with a letter -- make sure they contain only letters, numbers, and/or the underscore character -- make sure they are must be no longer than currently 63 characters -``` - -# TSV files - -A Tab-Separate Values (TSV) file is a text file where tab characters (`\t`) -separate fields that are in the file. It is structured as a table, with each -column representing a field of interest, and each row representing a single -datapoint. - -Below are ways to read / write TSV files in common languages. - -## Matlab - -### Reading a `.tsv` file: - -```matlab -table_content = readtable(filename, ... - 'FileType', 'text', ... - 'Delimiter', '\t', ... - 'TreatAsEmpty', {'N/A','n/a'}); -``` - -### Writing a `.tsv` file: - -#### Matlab - -```matlab -root_dir = pwd; -bidsProject = 'temp'; -mkdir(fullfile(root_dir, bidsProject)); -bids_participants_name = 'participants.tsv'; - -participant_id = ['sub-01'; 'sub-02']; -age = [20 30]'; -sex = ['m';'f']; - -t = table(participant_id,age,sex); -writetable(t, fullfile(root_dir, bidsProject, bids_participants_name), ... - 'FileType', 'text', ... - 'Delimiter', '\t'); -``` - -#### Octave - -The `writetable` function is not implemented in older version of Octave (e.g -4.2.2) and the `table` function differs from its matlab counterpart. These are -still in development for future -[releases](https://github.com/apjanke/octave-tablicious) so some of the scripts -provided in the BIDS starter-kit repository in the matlab code folder to create -.tsv might not work with octave because of that reason. - -## Python - -In Python, the easiest way to work with TSV files is to use the Pandas library. -This provides a high-level structure to organize, manipulate, clean, and -visualize tabular data. You can install `pandas` with the following command: - -`pip install pandas` - -### Reading a `.tsv` file - -There are many ways to read a `.tsv` file in Pandas. One option is the -following: - -```python -import pandas as pd -pd.read_csv('./ds001/participants.tsv', delimiter='\t') -``` - -Note that this function will default to using `,` as a delimiter, so we -explicitly give it the tab character. - -### Writing a `.tsv` file - -You can write to a `.tsv` file using the `to_csv` method of a pandas DataFrame: - -```python -import pandas as pd -df = pd.read_csv('./ds001/participants.tsv', delimiter='\t') - -# Add an extra column for demonstration -df['subject_id'] = range(len(df)) - -# Show contents of the dataframe -df.head() - Out: - participant_id sex age subject_id - 0 sub-01 F 26 0 - 1 sub-02 M 24 1 - 2 sub-03 F 27 2 - 3 sub-04 F 20 3 - 4 sub-05 M 22 4 - -# Save as a .tsv file -df.to_csv('my_new_file.tsv', sep='\t') -``` - -## Excel - -- Create a file with the following columns (at least, for other values see - paragraph the - [BIDS spec](https://bids-specification.readthedocs.io/en/latest/03-modality-agnostic-files.html#participants-file)) - - participant_id - - age - - sex -- Save as tab separated `.txt` and change extension to `.tsv` - -## R - -Reading and writing tab separated files comes natively in R, no need for extra -packages. - -### Reading a `.tsv` file: - -In this example, we assume the .tsv includes column names (headers), and -explicitly set column separator (delimiter) to tab ('\t') - -```R -data = read.table('myFile.tsv', header=TRUE, sep='\t') -``` - -### Writing a `.tsv` file: - -When writing files, column and row names are always saved, we remove row names, -and quotes from the outpur explicitly by setting them to FALSE. - -```R -data = cbind.data.frame( - participant_id = c('sub-01', 'sub-02'), - age = c(20,30), - sex = c('m','f')) - -write.table(data, file='myData.tsv',sep='\t', - row.names = FALSE, quote = FALSE) -``` +Moved [here](https://bids-website.readthedocs.io/en/latest/getting_started/folders_and_files/metadata.html). diff --git a/src/glossary.md b/src/glossary.md index d0acff78..eae074ce 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -1,202 +1,3 @@ -# BIDS jargon busting +# Glossary -XKCD comic 771 - -**_Simple definitions for any BIDS related terms_** - -Make sure to also check the -[official glossary](https://bids-specification.readthedocs.io/en/latest/99-appendices/14-glossary.html) -that lists all the terms of the BIDS specification. - -We know that when you're getting started with something new there are often jargon-y words -that make understanding everything that's going on kinda hard. - -The point of this list is to give you a place to go -to figure out some of those terms that "everyone" seems to know. - -Please add to this list! It will always be πŸ‘· **in construction** 🚧 -and we really encourage everyone to update it to be more useful. -If there's a word you don't know, -there's almost certainly someone else who doesn't know what it means either. - -**If you are unsure about a term/definition that you are adding, please add it anyway and add an asterix(\*) to signal that you want it reviewed.** - -## General resources - -## BIDS Terms - - - -### A - -#### **acquisition**: - -One continuous block of a scan. - -### B - -#### **BIDS**: - -Brain Imaging Data Structure - a standardised way to organise your neuroimaging -data. - -- http://bids.neuroimaging.io - -### C - -#### **channel**: - -The combination of the differential amplifier and the analog-to-digital converter -that results in the potential different (for EEG and iEEG) -or magnetic field or gradient (for MEG) to end up on disk. -This should not be confused with [**electrode**](#electrode). - -#### **container**: - -A container is a file which packages all the software -and instructions required to perform a series of tasks. - -### D - -#### **derivatives**: - -Processed (for instance: non-raw) data. - -#### **dataset**: - -Collection of data that can include many subjects or sessions. - -### E - -#### **electrode**: - -The small metal disk that is in contact with the scalp (EEG) -or directly touching the brain (iEEG). -This should not be confused with the EEG or iEGG [**channel**](#channel). - -#### **extensions**: - -Branches of BIDS that are for specific types of data (for instance: PET). - -### F - -#### **file extension**: - -A file extension is the suffix following the last `.` in a filename, -for example the `.jpeg` in `dog.jpeg`. -These exist to give us instructions on how to interpret files. -File extensions that are important in BIDS are [`.json`](#JSON), `.nii`, [`.tsv`](#TSV) - -### H - -#### **heuristic file**: - -A file that can sort your data into categories based on naming patterns - -### I - -#### **inheritance**: - -Any metadata file (.json, .bvec, .tsv, and so on.) may be defined at any -directory level. The values from the top level are inherited by all lower levels -unless they are overridden by a file at the lower level. - -### J - -#### **JSON**: - -A JSON file can be thought of as a form or as a list of name-value pairs. -Example: - -```json -{"firstName": "John", "lastName": "Smith"} -``` - -- You can find more information about `json` files - in the [Metadata file formats](./folders_and_files/metadata.md#json-files) page. - -### M - -#### **metadata**: - -Supporting data that describes your main data (for instance: data about data). -For example if your main data is an MRI image your metadata might be information -about the date and time of imaging, the image type, the machine serial number and so on. -An example: "Scan Date" would be metadata that describes the date at which you acquired the actual data. - -### O - -#### **open science**: - -Scientific research and data that is free and available for everyone to benefit -from. - -### P - -#### **parameter**: - -Generally speaking, a parameter is numerical variable -that we (scientists, computer programs, and so on) -are able to manipulate in order to change outcomes. - -### R - -#### **README**: - -A readme is a text file. -The readme's purpose is to provide explanation -and documentation for the contents of the folder it lives in. - -### S - -#### **subject**: - -A person / animal / object participating in a study. - -#### **session**: - -An uninterrupted period that a subject is in a specific lab. -This often corresponds to a lab visit. -See also this -[definition](https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#definitions). - -#### **sequence**: - -A combination of settings on the MR scanner that determine the way the MR data is acquired. -This includes the TE, TR, FOV, in-plane resolution, slice spacing, and so on. - -#### **sidecar** (as in json sidecar): - -A json file associated to a nii file -(usually by having the same name preceding the [file extension](#f)). -Together these make up an acquisition; -the nii file contains the image and the json contains various [metadata](#m). - -#### **sourcedata**: - -Raw data (or metadata) in its original format prior to conversion to BIDS, -for example: images in DICOM format, -EEG data in a proprietary format or presentation log files. - -### T - -#### **tsv**: - -TSV stands for Tab Separated Values. -A .tsv file contains a table (like a simple excel spreadsheet) containing text. -Table values are separated by tabs. - -- You can find more information about `TSV` files - in the [Metadata file formats](./folders_and_files/metadata.md#tsv-files) page. - -### U - -#### **URI**: - -Stands for **U**niform **R**esource **I**dentifier. -It is a very general term to describe the "address" of an "object" on the web. -A type of URI many of us are familiar with is an URL (Uniform Resource Locator) -that points to a webpage, an image... -Another very common type is a DOI (Digital Object Identifiers) -that can be used to point to a scientific article, -a data or code archive (for example on Zenodo, figshare...) +Moved [here](https://bids-website.readthedocs.io/en/latest/getting_started/resources/glossary.html) diff --git a/src/images/BIDS-minder.svg b/src/images/BIDS-minder.svg deleted file mode 100644 index 0ce2458a..00000000 --- a/src/images/BIDS-minder.svg +++ /dev/null @@ -1,4306 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/src/images/BIDS.minder b/src/images/BIDS.minder deleted file mode 100644 index 31dcb3c2..00000000 --- a/src/images/BIDS.minder +++ /dev/null @@ -1,429 +0,0 @@ - - - - -